Skip to main content

Frontmatter Schema

This document defines the canonical frontmatter schema for all content in the Engineering Journal.

This schema is deterministic and enforced via repository governance.

Core Schema (Required for ALL content)​

title: string
description: string
content_type: doc | journal | lab | case-study
type: doc | journal | lab | case-study
status: draft | review | active | deprecated | archived
lifecycle: draft | review | active | deprecated | archived
tags: [string]
owners: ["@github-username"]
created_at: YYYY-MM-DD
last_reviewed: YYYY-MM-DD
primary_domain: string
category: string

Content Type and Path Enforcement​

All content MUST:

  1. Declare content_type in frontmatter
  2. Reside in the correct directory
content_typerequired path
docwebsite/docs/**
labwebsite/docs/labs/**
case-studywebsite/docs/case-studies/**
journalwebsite/docs/journal/**

Mismatch between content_type and path is a CI failure.

Field Definitions​

title​

Human-readable title of the document.

description​

Short summary used for SEO and previews.

content_type​

Determines schema validation and taxonomy alignment.

status​

Lifecycle state of the content. Allowed values: draft, review, active, deprecated, archived.

tags​

Must match controlled vocabulary defined in .github/taxonomy.yml.

owners​

GitHub usernames responsible for maintaining the content. Must include @ prefix.

created_at​

ISO 8601 date the content was created (YYYY-MM-DD).

last_reviewed​

ISO 8601 date the content was last reviewed for accuracy (YYYY-MM-DD).

primary_domain​

Must match a domain defined in .github/taxonomy.yml.

category​

Must match an allowed category for the given content_type.

Validation Rules​

  • All required fields MUST be present
  • status and lifecycle MUST match allowed enum
  • tags MUST match approved taxonomy
  • owners MUST be valid GitHub usernames with @ prefix
  • Dates MUST be ISO 8601 (YYYY-MM-DD)
  • content_type MUST match directory path
  • primary_domain MUST exist in taxonomy

Related Content​