Found by the docs audit of the first-run path (#10563).
What is wrong
content/docs/data-modeling/field-types.mdx describes the fate of an unknown field
key as a silent strip, twice — lines 317 and 339, the lookup and master_detail
property tables:
referenceFilters | string[] | — | Removed (#2377, ADR-0049) — no longer a
recognized field property (unknown keys are stripped by the schema). Use
structured lookupFilters + dependsOn instead
FieldSchema is a strictObject (packages/spec/src/data/field.zod.ts:663), so an
unknown key is rejected with a fixable error, not stripped — and
referenceFilters specifically has a hand-written tombstone that carries the
upgrade (field.zod.ts:721-723):
referenceFilters:
'`referenceFilters` (string[]) was removed in the 16.x line (#2377) — the lookup
picker only ever read the structured form. Use `lookupFilters: [{ field,
operator, value }]`.'
strictObject's own docblock (packages/spec/src/shared/strict-object.ts:39-42)
names the distinction as the whole point of the helper: a named surface, the
offending key echoed back, and a suggestion — "which is the difference between a
silent strip and a fixable error."
This matters beyond pedantry: "stripped" tells a reader their typo vanishes quietly
and their metadata still loads, which is the pre-#4001 behaviour and the exact
failure mode ADR-0078 exists to delete. The docs elsewhere state it correctly —
content/docs/data-modeling/objects.mdx describes .strict() on enable as
"rejected with guidance, not stripped (#1535)".
content/docs/data-modeling/validation-rules.mdx:245 and
content/docs/data-modeling/relationships.mdx:39 carry the same referenceFilters
retirement without the wrong claim, so only field-types.mdx needs the edit.
Back-link: #10563
Found by the docs audit of the first-run path (#10563).
What is wrong
content/docs/data-modeling/field-types.mdxdescribes the fate of an unknown fieldkey as a silent strip, twice — lines 317 and 339, the
lookupandmaster_detailproperty tables:
FieldSchemais astrictObject(packages/spec/src/data/field.zod.ts:663), so anunknown key is rejected with a fixable error, not stripped — and
referenceFiltersspecifically has a hand-written tombstone that carries theupgrade (
field.zod.ts:721-723):strictObject's own docblock (packages/spec/src/shared/strict-object.ts:39-42)names the distinction as the whole point of the helper: a named surface, the
offending key echoed back, and a suggestion — "which is the difference between a
silent strip and a fixable error."
This matters beyond pedantry: "stripped" tells a reader their typo vanishes quietly
and their metadata still loads, which is the pre-#4001 behaviour and the exact
failure mode ADR-0078 exists to delete. The docs elsewhere state it correctly —
content/docs/data-modeling/objects.mdxdescribes.strict()onenableas"rejected with guidance, not stripped (#1535)".
content/docs/data-modeling/validation-rules.mdx:245andcontent/docs/data-modeling/relationships.mdx:39carry the samereferenceFiltersretirement without the wrong claim, so only
field-types.mdxneeds the edit.Back-link: #10563