[DOCS] Consolidate the Python docs into SCHEMA_GUIDE.md

[Seth Fitzsimmons (sethfitz)]

Summary

Replaces #672. Same consolidation — PYDANTIC_GUIDE.md and README.pydantic.md become a single SCHEMA_GUIDE.md, linked from README.md and CONTRIBUTING.md, and GLOSSARY.md grows from 6 to 22 terms — rebased onto the documentation fixes in #683, with the corrections carried into the new guide. Dana Bauer (@danabauer)'s commit is preserved with its authorship; the second commit is the port.

#672 can be closed in favour of this; it does not rebase cleanly, because the files it deletes are the files #683 edits.

Why this replaces it rather than stacking on it

#672 was written against main before the doc fixes landed, so it did two things this branch undoes:

1. It carried the stale content forward. [DOCS] PYDANTIC_GUIDE.md documents a package layout the repo no longer uses #604's models.py / enums.py / types.py file-type rules, the per-type-subdirectory prescription, and # In buildings/models.py all survive verbatim into SCHEMA_GUIDE.md. Those sections are now taken from the corrected PYDANTIC_GUIDE.md — extracted from the file programmatically rather than retyped, so the two cannot disagree.

2. It catalogued the defects instead of fixing them. The guide gained a "Docs in the repo that are currently wrong" section listing eight items. Seven are fixed in [BUG] Correct the Python package documentation #683. Only pip install survives, and it now points at the section explaining why. A standing list of known-wrong docs is a workaround for not having a check; [BUG] Correct the Python package documentation #683 adds the check.

Other corrections

The transcribed overture-schema list-types output (two copies) and the --group-by output were regenerated by running the commands, so they show the overture tag that #683 adds. The ModelKey examples were showing BuildingModel / PlaceModel, which are not the names of anything.

GLOSSARY.md's Tag entry said "Seven tags exist today ... There is no plain overture tag, despite what some help text suggests." Accurate when written, and the observation is what prompted #683 to add the tag rather than delete the help that referenced it. Now eight, with a note on what the tag does and does not assert — see the open question in #683, which is the place to weigh in on it.

What importing the guide exposed

SCHEMA_GUIDE.md broke the drift detector twice on arrival, which is a fair argument for having it:

• A >>> REPL block failed to parse and dropped out of the sweep whole, taking its imports with it. Transcripts are unwrapped now.
• The guide deliberately shows from overture.schema import Building # ✗ ImportError as a counter-example, and the detector read it as a defect. A line carrying the counter-example glyph is exempt.

Both behaviours have unit fixtures and a mutation that fails them.

Review notes

• Dana Bauer (@danabauer)'s own checks still hold. Every code block in the guide parses, every overture.* import resolves, every internal link resolves. Two of those are now enforced by tests/test_documented_imports.py on every run rather than checked once.
• The SCHEMA_CONVENTIONS.md staleness flags in README.md were spot-checked and are accurate: it does describe JSON Schema as the definition mechanism (line 3) and does spell subType (line 37).
• CONTRIBUTING.md still does not mention the DCO sign-off requirement. Carried over unaddressed, as in [DOCS] test, update, revise, and consolidate schema guides #672.

Closes #685

[github-actions]

🗺️ Schema reference docs preview is live!

🌍 Preview	https://staging.overturemaps.org/schema/pr/684/schema/index.html
🕐 Updated	Aug 26, 2026 16:23 UTC
📝 Commit	fd6a409
🔧 env SCHEMA_PREVIEW	true

Note

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

[John McCall (lowlydba)]

Suggestion:

With really wide-reaching/complex docs like this (several audiences, several different use cases) I really like to cornerstone them with Diataxis, which is roughly just:

Diátaxis identifies four distinct needs, and four corresponding forms of documentation - tutorials, how-to guides, technical reference and explanation. It places them in a systematic relationship, and proposes that documentation should itself be organised around the structures of those needs.

One of the bonuses of this is models seem very adept at following/implementing it just by name reference with "Do the docs in Diataxis", so you can almost completely offload the information theory cognitive load of organizing big documentation, while still being consistent.