[ENHANCEMENT](schema) Remove the non-null defaults from the schema models

[Seth Fitzsimmons (sethfitz)]

Closes #696

Implements the policy adopted in #695 for the four remaining declaration sites. No schema field carries a non-null default after this change; a census over discover_models() reports zero, across 54 models.

Eleven fields, four sites in four files — the other seven are inherited and re-reported by subclasses.

Declaration	Was	Now
common/level.py Stacked.level	= 0	Level | None = None
base/land.py Land.class_, Land.subtype	LandClass.LAND, LandSubtype.LAND	required
base/water.py Water.class_, Water.subtype	WaterClass.WATER, WaterSubtype.WATER	required
transportation/segment/_common.py SpeedLimitRule.is_max_speed_variable	= False	bool | None, no default

Land and Water now match Infrastructure and LandUse, which already declared class_ and subtype required with no default. Removing the level default also retires a # type: ignore[assignment] that existed only to admit it — Level is a NewType over Annotated[int32, ...], so 0 was never a value of the field's declared type.

The absence sentence went on the field, not the type

Stacked.level's description states that a feature without a level is at visual level. That sentence is on the field annotation rather than on the Level NewType, because Level is also the type of LevelRule.value in transportation/segment/_common.py, which is required — an absence sentence there renders into a context where absence is impossible.

is_max_speed_variable keeps its description

The default is removed; the description is untouched. What absence means for this field is a domain question, and the existing wording ("Indicates a variable speed corridor") does not define the term precisely enough to extend safely. Both are worth settling with the transportation folks, separately from this change. Flagging it explicitly because #696's second acceptance criterion — that every meaning a removed default carried is stated in the field description — is met for level and moot for class_/subtype, but left open here.

No consumer sees a difference

Measured against release 2026-08-19.0, one partition per type. No published row carries any of these defaults:

Field	Rows measured	Equal to the default	Null
Land.level	1,174,629	0	1,174,529
Water.level	1,985,644	0	1,985,620
Land.class/subtype	1,174,629	n/a	0 null
Water.class/subtype	1,985,644	n/a	0 null
SpeedLimitRule.is_max_speed_variable	601,764 rules	0 (false)	601,497

The publisher already writes class and subtype on every row, so making them required tightens the model to what the release already contains.

Verification

• The JSON Schema goldens were hand-written to the predicted shape first, then the models changed. Seven failed as predicted, and all fifteen went green on the model edit — so the emitted schema matches what was intended rather than whatever the generator happened to produce. That ordering is what caught the Level NewType problem above.
• land, water and segment partitions from 2026-08-19.0 validate clean under overture-validate --skip-schema-check: 0 errors across 5,816,361 rows. That zero is a real result, not a dead check — injecting nulls into 333 class and 200 subtype values makes the same command report class:required / subtype:required and exit 1.
• Regenerated PySpark and Markdown diffs read, not just regenerated. PySpark gains only the four required-field checks (_class_check splits into _class_required_check + _class_enum_check, same for subtype); there is no StructType diff, since schema_builder.py renders every field nullable regardless of requiredness. Markdown drops (optional) from the four fields and the example rows change 0 → null and false → null — those examples were displaying the injected default rather than what the release contains.
• Full suite green on both commits via the pre-commit gate.

Follow-ups

• What is_max_speed_variable asserts, and what its absence means.
• Enforcement — a check that fails on any field carrying a default, so this cannot regress. Better placed in the CLI than in a test, so extensions and third-party schemas built on overture-schema-system can run it too.

[github-actions]

🗺️ Schema reference docs preview is live!

🌍 Preview	https://staging.overturemaps.org/schema/pr/697/schema/index.html
🕐 Updated	Aug 26, 2026 17:55 UTC
📝 Commit	daf99c7
🔧 env SCHEMA_PREVIEW	true

Note

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