ADR-005: Jekyll Frontmatter Schema Validation

Status

Accepted

Context

Jekyll posts require YAML frontmatter for metadata (title, date, tags, etc.). Without validation:

• Required fields get omitted
• Field formats vary inconsistently
• SEO fields have incorrect lengths
• Type mismatches cause build failures

The project initially had YAML-based schemas in schemas/ but the validation script expected JSON Schema format.

Decision

Use JSON Schema (draft-07) for frontmatter validation:

1. Schema location: Co-located with content (_posts/frontmatter-schema.json)
2. Validation library: AJV with ajv-formats for date/uri validation
3. Required fields: title, date, tags (minimal for flexibility)
4. Recommended fields: excerpt, description, image (documented but optional)

Schema design principles:

• Allow Jekyll’s Date object parsing (not just strings)
• Generous length limits for descriptions (max 300, recommended 160)
• Additional properties allowed for future flexibility

Consequences

Positive:

• Consistent frontmatter across all posts
• Clear error messages with field paths
• IDE support via JSON Schema
• Catches issues before Jekyll build

Negative:

• Schema drift if Jekyll requirements change
• Existing posts may need updates for stricter validation
• Schema must handle Jekyll’s YAML parsing quirks (dates as objects)

Schema Evolution

When changing the schema:

1. Update _posts/frontmatter-schema.json
2. Run validation against existing posts
3. Fix or document exceptions
4. Update CLAUDE.md frontmatter documentation