Frontmatter

Validate YAML metadata keys with front directives, including presence, allow-lists, dates, placeholders, patterns, and closure.

Bishop: "I may be synthetic, but I'm not stupid." Metadata deserves the same treatment: small rules, clear boundaries, no mystery cargo in the hold.

front declares rules for YAML frontmatter. It is a structural marker, written as front <key> for one metadata key, or as bare front noExtraKeys to close the whole metadata set. It has no end tag.

The frontmatter reader handles the common subset — the leading --- … --- block with top-level key: value pairs. Nested maps, lists, and block scalars are out of scope for the front <key> rules, which target one top-level key each.

<!-- mdv: front status required oneOf=[draft, review, published] -->
<!-- mdv: front date date=iso -->
<!-- mdv: front noExtraKeys -->

That contract says:

status must exist, and it must be draft, review, or published.
date must be an ISO date if it is present.
no other frontmatter keys are allowed.

It validates a document like this:

---
status: review
date: 2026-06-28
---

# Mission log

What it catches

Point that same contract at a document where the metadata is wrong on every axis:

---
status: shipped
date: last-tuesday
author: dana
---

# Mission log

Form — edit the document

mission.md
  2  error  Frontmatter value not allowed  frontmatter-not-allowed-value
      The frontmatter key "status" is "shipped", which is not an allowed value (draft, review, published).
      fix: This metadata key has an allowed vocabulary. Use the allowed value that truthfully describes this document.
     error  Unexpected frontmatter key     unexpected-frontmatter-key
      The frontmatter key "author" is not one the schema declares.
      fix: With `noExtraKeys`, the schema declares the complete metadata set. Move the information into a declared key, or have the schema author declare this key with `front`.

State — do the work, then record it

mission.md
  3  error  Frontmatter date not ISO  frontmatter-bad-date
      The frontmatter key "date" is "last-tuesday", which is not an ISO date.
      fix: This metadata value must be a real date in ISO form (`YYYY-MM-DD`, or a full ISO timestamp if time is required). Find the document's actual date, then record it — do not invent one to satisfy the format.

contract: mission.mdv.md
    Restructuring on purpose? Update the contract in the same change so document and contract move together. One-off exception: <!-- mdv: disable-next-line <rule> -- reason -->

✖ 3 problems (3 errors, 0 warnings)

Two more cases worth knowing:

A missing or empty required key both report [missing-frontmatter-key] ("required, but is missing or empty") — an empty status: is treated the same as omitting it.
A duplicated key emits a [duplicate-frontmatter-key] warning, and the first value is the one validated — so a stray second date: doesn't silently override the real one.

Rules

rule	what it checks
`required`	the key must be present
`optional`	the key may be absent
`oneOf=[a, b, c]`	the value must be one of the listed options
`date=iso`	the value must be ISO-shaped — `YYYY-MM-DD` or a full timestamp. A regex check, not a calendar check, so an impossible date like `2026-13-99` still matches. It is a content concern (the real date is human-owned), so it surfaces under `validateState`, not `validateSyntax`
`noPlaceholder`	placeholder values like TODO or TBD are rejected
`pattern=/regex/`	the value must match the regex
`front noExtraKeys`	no frontmatter key is allowed unless the contract declares it

Use front noExtraKeys when the metadata shape is part of the contract, like a release note with exactly status and date. Leave the fence open when authors need room for local metadata from another tool.

Frontmatter

What it catches

Rules

On this page