[finding] reference-doc tables render `.default()`-bearing fields as required (✅) for every output-shape def — authors read "must write" where the schema means "may omit"

[os-zhuang]

Observation-class, found while landing #8586 (PR #8702) — filed, not fixed there (out of scope).

What

packages/spec/scripts/build-schemas.ts emits each def's JSON Schema as the output (post-parse) shape by default, falling back to the input shape only when output emission throws (transforms etc.). In the output shape a .default()-bearing field is required (the parse always produces it), so build-docs.ts renders it with ✅ in the reference table's Required column — but an author may omit it, which is exactly what the reference table's Required column is read as answering.

Measured

• The additionalTypes on MetadataPluginConfig is authorable, documented as THE way a plugin declares a metadata type, and has no reader — a plugin cannot declare a kind at all #8586 retirement flipped kernel/MetadataPluginConfig from input-shape fallback to output-shape emission (the old additionalTypes value schema embedded ActionSchema, whose output emission throws). The regenerated content/docs/references/kernel/metadata-plugin.mdx now shows enableEvents / validateOnWrite / enableVersioning / cacheMaxItems / bootstrap — all .default()-bearing, all author-omittable — as ✅ required. Before the flip the same fields rendered optional (input shape).
• gen:schema reports Generated: 1589 (125 as input shape) — so ~1464 defs render the output shape, and every .default() field in them carries the same misleading ✅. Only the 125 input-shape defs (flagged x-io: input) show author-time optionality.

Why it matters

The reference tables are the author-facing contract (very often read by an AI author, ADR-0033). "Required" on a field the author may omit teaches over-specification at best; at worst an author treats a wall of ✅ as boilerplate and misses the genuinely-required fields among them. The two emission modes also make sibling pages inconsistent with each other, and a schema refactor can silently flip a page's whole Required column (as #8702's diff shows) without any semantic change to what authors must write.

Possible directions (not adjudicated here)

• render doc tables from the input shape uniformly (authors write input), keeping output emission for the JSON-Schema artifacts that validate post-parse data; or
• keep output emission but render .default()-bearing members as optional (default: …) in the table.

Relates to: #8586 / PR #8702 (where the flip was observed and explained), #7658 (a different build-docs rendering gap, closed).

---

Generated by Claude Code

[hotlong]

Triage: routed domain:spec-tooling (packages/spec/scripts/build-schemas.ts + build-docs.ts — the machine face that turns schemas into reference pages), graded out of finding to pm:queue, type Bug.

First-touch grading — promote. This is declared-≠-enforced pointed at the author: the Required column of the reference tables is read as "must I write this?", and for ~1464 output-shape defs it answers that question with the post-parse shape, where every .default()-bearing field is required by construction. The card measures both halves — the #8586 flip that made enableEvents / validateOnWrite / enableVersioning / cacheMaxItems / bootstrap turn ✅ on metadata-plugin.mdx with no semantic change, and gen:schema's own 1589 (125 as input shape) split. A reference surface that flips its whole Required column on an unrelated refactor is a defect in the rendering, not a matter of taste, so it does not need a maintainer to authorize fixing.

Domain, per the one-package-three-seats split: the fix changes what the generator emits into docs, not which inputs @objectstack/spec accepts and not the describe/JSDoc prose — machine face, spec-tooling. If the seat finds the honest fix requires changing a schema's shape (rather than how it is rendered), that crosses into the semantic face: stop and route back rather than making the change in a tooling PR.

On the two directions the card offers (uniform input-shape rendering vs. keeping output emission and rendering .default() members as optional (default: …)): both are inside the seat's discretion and neither changes the accept surface, so pick with the measurement in hand and record the reasoning in the PR. Worth noting for whoever takes it — the second direction carries strictly more information for the author (it names the default rather than only relaxing the requirement), and it leaves the JSON-Schema artifacts that validate post-parse data alone; treat that as an input, not a ruling. The JSON-Schema artifacts must keep validating post-parse data either way — if a direction cannot preserve that, it is the wrong direction.

Test-facing note for dispatch: this regenerates a large share of content/docs/references/**, so it is an os-regen-touching PR — the merge discipline for generated artefacts applies (sync then regenerate wholesale, never hand-edit an anchor to make the diff agree). Not a claim.

---

Generated by Claude Code