suaveplan/packages/devtools/docs/sitemap/src/schemas/sitemap.schema.md

sitemap.schema

(no submodules)

Purpose

Defines Zod schemas for every wire-format type in @suaveplan/sitemap, providing runtime validation, static type inference, and a single source of truth for the shape of sitemap data structures. All schemas align with the sitemaps.org protocol and Google's image/video extensions.

Features

• ChangeFrequencySchema — validates the seven allowed change-frequency values
• SitemapImageSchema — image extension entry with optional caption, title, license, and geo-location
• SitemapVideoSchema — full video extension with duration, ratings, tags, and playback metadata
• SitemapAlternateSchema — hreflang alternate link pair
• SitemapUrlSchema — complete URL entry composing all extensions
• SitemapIndexSchema — sitemap index document with loc + optional lastmod entries
• Inferred TypeScript types exported for each schema

Usage: Basic Example

import {
  SitemapUrlSchema,
  type SitemapUrl,
} from "@suaveplan/sitemap";

const raw = {
  loc: "https://example.com/page",
  changefreq: "weekly",
  priority: 0.8,
};

const url: SitemapUrl = SitemapUrlSchema.parse(raw);
console.log(url.loc); // "https://example.com/page"

Usage: Advanced Example

import {
  SitemapUrlSchema,
  SitemapImageSchema,
  SitemapVideoSchema,
} from "@suaveplan/sitemap";

const richUrl = SitemapUrlSchema.parse({
  loc: "https://example.com/media",
  lastmod: "2024-06-01",
  changefreq: "daily",
  priority: 0.9,
  images: [
    SitemapImageSchema.parse({
      loc: "https://cdn.example.com/hero.jpg",
      caption: "Hero image",
      title: "Main hero",
    }),
  ],
  videos: [
    SitemapVideoSchema.parse({
      thumbnailLoc: "https://cdn.example.com/thumb.jpg",
      title: "Product demo",
      description: "A walkthrough of key features",
      duration: 180,
      rating: 4.5,
      familyFriendly: true,
      tags: ["demo", "features"],
    }),
  ],
});

API Reference

ChangeFrequencySchema

z.ZodEnum — one of "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never".

SitemapImageSchema

Object schema with fields: loc (required), caption, title, license, geoLocation (all optional strings).

SitemapVideoSchema

Object schema with required fields thumbnailLoc, title, description; optional fields include contentLoc, playerLoc, duration (integer ≥ 0), publicationDate, expirationDate, rating (0–5), viewCount, familyFriendly, requiresSubscription, live, tags.

SitemapAlternateSchema

Object schema with required hreflang and href string fields.

SitemapUrlSchema

Object schema with required loc; optional lastmod, changefreq, priority (0–1), images, videos, alternates.

SitemapIndexSchema

Object schema with sitemaps array, each entry having a required loc and optional lastmod.

Inferred Types

• ChangeFrequency — union of the seven frequency strings
• SitemapImage — inferred from SitemapImageSchema
• SitemapVideo — inferred from SitemapVideoSchema
• SitemapAlternate — inferred from SitemapAlternateSchema
• SitemapUrl — inferred from SitemapUrlSchema
• SitemapIndex — inferred from SitemapIndexSchema

Implementation Notes

All schemas use .min(1) on required string fields to prevent empty-string entries from passing validation silently. Numeric ranges (priority: 0–1, rating: 0–5, duration ≥ 0, viewCount ≥ 0) are enforced at the schema level rather than in business logic, keeping validation rules co-located with type definitions. The schemas intentionally do not validate URL format — that responsibility lies with url-utils.ts / SitemapBuilder.