frontend-patterns/canon/PatternSchema.md

Pattern schema 0.1

Status: working contract · 2026-09-24 · FEP-WP-0002-T01

Pattern template is the authoring skeleton; vocabulary.yaml owns serialized enum values and force IDs. The template is intentionally incomplete and is not a pattern record.

Identity and lifecycle

• schema_version: '0.1' identifies this metadata contract.
• id: FEP- followed by four digits, allocated once when creating a pattern file. IDs do not encode families or scale; moving or renaming a pattern retains its ID. Never reuse a retired ID. Check all pattern frontmatter before allocating the next unused number. Candidate P01 identities remain scoped to their source workspace.
• name: human-readable name; family: nonempty list of family keys; scales: nonempty list of distinct L0–L7 keys. Do not serialize cross-scale or L3/L6.
• status: draft, reviewed or deprecated. Reviewed means an editorial review is recorded in Evidence; it does not establish empirical maturity. Deprecation must explain the replacement or reason, and existing references remain resolvable.
• evidence.maturity: hypothesis (untested generalization), emerging (traceable support and contrasting cases with explicit gaps), established (independent known uses and documented limits), canonical (established evidence plus explicit corpus review for reference use). None means universally desirable. Promotion requires a linked review, never a model score or a count of citations alone.

Context, prerequisites and forces

context and prerequisites are lists of explanatory strings. Prerequisites are conditions such as identifiable commands or a durability requirement. They are not unresolved pattern names. Use a requires relation only when another pattern is genuinely required, with its ID and a rationale.

forces.improves and forces.worsens contain vocabulary keys such as interaction-latency and implementation-complexity. At least two distinct forces must be present overall, with both benefits and costs explained in prose. A force may appear on both sides only when the Forces section explains the conditions. Do not infer direction just from a label (lower latency is generally favorable).

Relations

relations is a list of objects:

- type: enables
  target:
    kind: pattern
    ref: FEP-0002
  rationale: Explain the conditional dependency or effect.
  evidence: [E1]

The nine pattern relation types in vocabulary.yaml target a pattern by stable ID. implemented-by targets technology; observed-in targets system or architecture. External targets use a repository-relative Markdown path to an existing mapping or case record. A product label or URL alone is not a graph node. rationale is required. evidence contains local evidence-entry IDs, or is empty when the relation is explicitly marked as a hypothesis in its rationale.

Use kebab-case relation names everywhere. Relations are recorded from this pattern to the target. Do not infer inverse edges, transitivity or symmetric closure. In particular, a cycle of complements is not itself an inconsistency. Requires cycles warrant review; a generic graph cycle count is not a correctness verdict.

Evidence and known uses

evidence.sources is a list with these fields:

- id: E1
  source: SRC-0001
  locator: Source section, page, paragraph or repository revision.
  review: research/cases/ExampleReview.md
  claims: [C01]

Source IDs resolve in research/catalog/SourceCatalog.md. Each review path exists; claim IDs resolve within that review. E1 is local to the pattern, not a global ID. Source statements and our interpretations must be separate in the review. An empty evidence list is allowed for a draft hypothesis, with the gap stated. A source citation is not independent confirmation of all claims in a pattern.

known_uses is a list of {name, locator, evidence} objects: a named observed use, a version-specific URL or source locator, and local evidence IDs supporting the observation. A hypothetical example belongs in Implementation Notes, not Known Uses.

Prose and admission

All sections in the template are required. Explain a recurring problem, competing forces, reusable solution, dynamics, resulting context, consequences and failure modes. State unknowns explicitly rather than leaving misleading empty claims. A technique or framework feature alone does not establish a reusable pattern.

Worked fixtures demonstrate resolution in a deliberately isolated synthetic corpus. Their IDs are not reserved in the real corpus and their contents provide no research evidence. The fixture check is an acceptance check for this contract, not the future full corpus validator.