frontend-patterns/canon/PatternSchema.md

# Pattern schema 0.1

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

[Pattern template](../templates/Pattern.md) is the authoring skeleton;
[vocabulary.yaml](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:

```yaml
- 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:

```yaml
- 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](../research/examples/schema-contract.yaml) 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.