[FEATURE](codegen) Carry field defaults through the IR into the Markdown reference, and refuse default_factory

[Seth Fitzsimmons (sethfitz)]

Description

Codegen renderers can read each field's declared default: a target that supports defaults can emit one, and a target that does not can report that it dropped one. The Markdown reference is the first to emit one, as a note on the field's row. A model that declares default_factory fails extraction with an error naming the field, where before the factory was discarded silently.

FieldSpec, the codegen IR's per-field record, is (name, shape, description, is_required, is_optional). Extraction reads FieldInfo.default and FieldInfo.default_factory, uses them to settle one question — whether the field is required — and discards the values. Nothing downstream can emit a field's default, report that it had to drop one, or refuse one.

This carries the value, renders it in Markdown, and refuses the one form of it no target can render.

FieldSpec.default, with UNDEFINED exported from extraction.specs for the absent case. UNDEFINED is Pydantic's own PydanticUndefined under a shorter name, not a second sentinel: a consumer reads spec.default is UNDEFINED without importing pydantic_core to ask the IR a question, the two values meaning "no default" cannot drift apart, and copy.deepcopy and pickle both return the same object, where a freshly minted singleton returns a different one.

A declared default of None is kept as None, distinct from absence: None is legal, and collapsing the two leaves a consumer unable to tell them apart. = None is also how a Pydantic field is declared optional, and nothing in the source separates that from an intended null default, so the IR reports what it finds. Pydantic's own model_json_schema() does the same, emitting "default": null.

Omitable[T] installs Field(default=MISSING) to get JSON Schema omissibility instead of Pydantic nullability. MISSING is machinery for "this key may be absent", not a value anyone declared, so it normalizes to UNDEFINED — and Feature.bbox and Feature.id are both Omitable, inherited by every feature model, so without that normalization every feature type in the schema would claim two defaults it does not have.

default_factory is refused at extraction, naming the model and field. #695 forbids it outright, because a callable cannot be rendered into any representation but Python. The other two things the extractor could do are both silent: invoking the factory freezes one sample of a value meant to be produced per instance, and the frozen sample is indistinguishable from a declared literal; recording it as "no default" hides a declared default from every consumer. Refusing is the only option the author ever sees.

The Markdown reference shows a non-null default as an italic Default: note in the field's description cell, ahead of any constraint notes. It goes on every row, including the dot-notation rows expanded inline from a sub-model, so a reader who never opens the sub-model's page still sees it. A default of None gets no note: that is the optional spelling above, and the (optional) qualifier in the type column already says it. An enum member shows its value, the form a record carries.

No field in the schema declares a factory, so nothing that exists today is refused. The published reference does not change either: every declared default in the schema is = None on an optional field, and #695 forbids any other. All 139 generated pages are identical before and after this branch.

This does not warn or fail on a declared default. Enforcing #695's policy belongs downstream, in a schema validator distinct from a data validator, and carrying the value is what makes it possible.

Reference

1. Closes Carry field defaults through the extraction IR #758.
2. [ENHANCEMENT](schema) Adopt a policy: schema fields carry no non-null default #695 — the no-non-null-default policy, which forbids default_factory outright. This carries the value so a target can see it; it does not reintroduce defaults to the schema.
3. [ENHANCEMENT](codegen) Decide support-or-reject for Pydantic Field kwargs the extractor ignores or crashes on #640 — the support-or-reject frame for Field() kwargs. [ENHANCEMENT](schema) Adopt a policy: schema fields carry no non-null default #695 settled default as policy; this settles it in the extractor, and settles default_factory alongside it.
4. [FEATURE](codegen) Add a stac-table-columns codegen format #724 — the stac-table-columns renderer, which reads FieldSpec.default to report defaults it cannot carry.
5. [FEATURE] Carry deprecation through extraction and render it in the Markdown reference #674 — the sibling carrier for deprecation, which adds is_deprecated to the same record.

Checklist

1. Add relevant examples. — N/A: no schema change; this is codegen behaviour, exercised by inline test fixtures rather than by published examples.
2. Add relevant counterexamples. — N/A, same reason.
3. Update any counterexamples that became obsolete. — N/A: no published example or counterexample changes meaning here.
4. Update in-schema documentation using plain English written in complete sentences, if an update is required. — N/A: no schema field changed.
5. Update Docusaurus documentation, if an update is required. — Not required. The generated reference is unchanged, because the schema declares no non-null default.
6. Review change with Overture technical writer to ensure any advanced documentation needs will be taken care of, unless the change is trivial and would not affect the documentation. — Not required: the reference gains a note format that no Overture field triggers.

Documentation website

Docs preview for this PR.

[github-actions]

🗺️ Schema reference docs preview is live!

🌍 Preview	https://staging.overturemaps.org/schema/pr/759/schema/index.html
🕐 Updated	Sep 23, 2026 00:07 UTC
📝 Commit	2550142
🔧 env SCHEMA_PREVIEW	true

Note

♻️ This preview updates automatically with each push to this PR.