Rendered from docs/decisions/0068-the-front-matter-key-that-carries-a-minted-identifier-is-id.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

The front-matter key that carries a minted identifier is id

Context

A kind declares identifier: {scheme: …}. The meta-schema's kind_identifier block closes that declaration to one member, scheme. Nothing in the schema language states which front-matter key holds the value a scheme mints.

The typing pass wrote id anyway, because every governed document in this corpus needs one. headwater_graph::Config carries the key as a parameter, identifier_facet, defaulted to "id". That way the index and the generated identifier check read the same key. .headwater/README.md's guess table carries the row, and HW-OBL-0053 carries the debt.

Q2 already rules that Headwater owns its own schema language. So this record is not blocked on that ruling. It is blocked on someone stating the declaration inside the language Q2 settled.

Q4 met the same shape of gap for relations:. It closed the gap the same way: a fixed literal key, stated once for every kind, and never a per-kind parameter. A relation instance and a minted identifier are both values that every kind's front matter carries in a predictable place. An author, or a check, would otherwise look up the key per kind before it reads a document. That lookup is the cost the fixed key removes.

Decision

The front-matter key id carries the value that a kind's identifier: {scheme: …} facet mints, as a global fixed rule. No kind overrides it. The meta-schema's kind_identifier block stays closed to scheme alone. It gains no second member for the key name, because every kind uses the one key name.

Consequences

headwater_graph::Config's identifier_facet default stops describing a guess. The doc comment on Config, and the matching comment in index.rs, cite this record instead of naming the key an unsettled parameter. The field itself stays a parameter, for the same reason relations_facet stayed a parameter after Q4. The module reads a name rather than a literal. A future change to the declaration then changes one default, and not every call site.

.headwater/README.md's guess table loses the row for this gap. The table lists what the typing pass still had to guess, and this row named a settled question.

HW-OBL-0053 discharges. The obligation was to state the declaration, and this record is that statement. Its entry leaves 13 — Open obligations to match.

Every existing document keeps validating. Every kinds.*.identifier declaration in the base package and the overlay already uses only {scheme: …}. Every governed document already writes id. The decision states what the corpus already does. It changes no file under docs/ beyond the ones this record names.