# sitemap.schema

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

```ts
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

```ts
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`.