Deserialization is only the first gate

YAML frontmatter can deserialize correctly and still be wrong.

Typical examples:

• a date uses the wrong format for one collection

• a field references an author slug that does not exist

• one frontmatter field becomes required only when another field is set

Serde answers the structural question. Sites often still need a semantic validation pass.

The public API surface

The main API pieces are:

• SiteBuilder::validate_collection(...)

• CollectionValidationContext

• CollectionValidationContext::invalid_frontmatter(...)

• CollectionValidationContext::invalid_frontmatter_field(...)

• EntryRef<T>

• entry_by_ref(...)

These are the types and methods that turn frontmatter validation into a deliberate framework feature instead of ad hoc application code.

Validation runs after all collections load

The framework exposes validate_collection(...) for that second step.

Validators receive a CollectionValidationContext plus the typed entries of the target collection. That means they can:

• inspect the whole collection

• resolve references into other collections

• fail before route rendering begins

This is a better fit than scattering semantic checks through route handlers.

Entry references should not be "just strings"

When one collection points at another, the frontmatter model can say so directly:

#[derive(Clone, Debug, Deserialize)]
struct BlogPost {
    title: String,
    author: EntryRef<Author>,
}

That buys two things:

• the intent is visible in the type

• route code can resolve the reference through entry_by_ref(...)

The reference stays collection-agnostic as data, but site code resolves it against the collection it expects.

Diagnostics stay tied to the content file

Validation errors are not just bare strings.

CollectionValidationContext can start a source-aware diagnostic for:

• one whole entry

• one specific frontmatter field

That lets validation failures point back to the actual content file and field that need fixing.

The result is a build that fails early and locally, instead of rendering halfway through and producing a vague error later.

Why this matters for route code

Once validation exists, route handlers get simpler.

They no longer need to perform the same defensive checks everywhere they use a piece of frontmatter. The semantic guarantees live in one build-time validation pass instead.

That is both cleaner and easier to teach.

Where to go next

• Read Validate frontmatter and entry references for the task-oriented version.

• Read Site-building API for the public API surface.

• Read Your first site if you want the simpler content-loading path before adding validation.