ADR-0006 — Strict schema, x- escape hatch
Unknown keys are errors, not warnings. Keys prefixed with x- are preserved and ignored.
Status: accepted
Any key the schema doesn't recognize is a hard error (MRW-E005). The single
exception: keys prefixed x- are preserved in the file and ignored by the
compiler.
Why
The failure this prevents is specific and nasty. Write teir: core instead of
tier: core and, under a permissive schema, you get a diagram that builds
successfully and is silently wrong — one device missing its tier drops the
entire topology out of tiered classification and into flat layout. The output
looks plausible. Nothing tells you.
A tolerant schema converts typos into wrong pictures. A strict schema converts them into a line number.
Assumed: the teir: example is illustrative, chosen because it's the
highest-consequence typo the schema admits. The repository states the rule and
the "declared, never guessed" principle but does not record a specific
incident.
The escape hatch exists because real topologies carry real metadata — asset tags, CMDB ids, ownership — that has no business in a rendering schema but every business in the file that describes the network. Forcing that into a side-car file guarantees the two drift apart.
Consequences
Adding a key to the schema is a breaking change in one direction only. Adding a new key is safe. Removing or renaming one breaks every file using it, with a clear error rather than silence.
x- is genuinely inert. Preserved on import, round-tripped, never
validated, never rendered. Users can rely on that.
The importer uses it as a preservation mechanism. v1 fields with no v2
equivalent survive as x-v1-tags, x-v1-badges, and so on. Nothing is silently
dropped in conversion.
One inert legacy block causes ongoing confusion. x-v1-config: records v1's
engine × layout matrix and has zero effect in v2. It's preserved by the rule
above but misleads readers into expecting multiple outputs — which is why the
documentation says to delete it on sight rather than merely tolerating it.
Config files behave differently. Unknown keys in marrow.config.yaml warn
rather than error. That asymmetry is intentional: a broken topology produces a
wrong diagram, whereas a stray config key at worst produces a missing footer.
Considered and rejected
Warn on unknown keys. Rejected: a warning in a hundred-line validation report is a warning nobody reads, and the failure mode it permits is a confidently wrong diagram.
A separate metadata file. Rejected: drifts from the topology immediately, and there's no reason to make users maintain two files.