Skip to content

[FEATURE] Version the schema reference docs per released schema tag - #512

Open
John McCall (lowlydba) wants to merge 4 commits into
mainfrom
lowlydba-schema-docs-versioning
Open

[FEATURE] Version the schema reference docs per released schema tag#512
John McCall (lowlydba) wants to merge 4 commits into
mainfrom
lowlydba-schema-docs-versioning

Conversation

@lowlydba

@lowlydba John McCall (lowlydba) commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Pull Request

Closes #452

The schema reference becomes its own versioned Docusaurus docs instance (schema), separate from the main docs/ instance, so released schema tags can be browsed alongside latest.

  • latest is unchanged in behavior: generated from the schema repo's main on every build, served at /schema/
  • released tags are snapshotted once into schema_versioned_docs/ and served at /schema/<tag>/
  • backfilled v2.0.0, v1.18.0, and v1.17.0 (~250 KB each). Earlier tags predate overture-schema-codegen and can't be generated
  • npm run add-schema-version -- vX.Y.Z does the clone/codegen/docs:version dance; README has the how-to

Why did docs/schema move to schema/?

A docs instance nested inside another instance's path gets its MDX compiled by both instances' webpack rules, and the second pass fails on the JSX output of the first. Moving it out is the only fix. The llms plugin now takes both dirs as sections, so llms-schema.txt still covers latest only.

The version dropdown is a global navbar item; it's hidden via CSS unless <html> carries plugin-id-schema. Tagged versions get banner: 'none' so they don't render as "unmaintained".

One UX tradeoff: on schema pages the sidebar is the schema sidebar only (with an "All docs" link back), and "Schema Reference" in the main sidebar is now a link instead of an expandable category. Docusaurus can't share a sidebar across instances.

Testing

Built locally with main-generated reference docs: all four versions render, cross-links stay within their version, llms-schema.txt contains only latest, and npm test passes. Verified the dropdown lists latest / v2.0.0 / v1.18.0 / v1.17.0 on schema pages and is absent from /.

Not covered: the a11y suite doesn't visit /schema/, same as before this change.

@lowlydba
[FEATURE] Version the schema reference docs per released schema tag
fd8329e 
Schema reference becomes its own versioned Docusaurus docs instance.
latest is generated from the schema repo's main on every build and served
at /schema/; released tags are snapshotted once into schema_versioned_docs/
and served at /schema/<tag>/. Adds scripts/add-schema-version.mjs plus
snapshots for v1.17.0, v1.18.0, and v2.0.0.

Closes #452

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Signed-off-by: John McCall <john@overturemaps.org>
@github-actions

github-actions Bot commented Sep 14, 2026 •
edited
Loading

Copy link
Copy Markdown

🗺️ Overture Docs preview is live!
🌍 Preview site https://staging.overturemaps.org/docs/pr/512/index.html
🗂️ Schema ref main@2092e8f
🕐 Updated Sep 16, 2026 13:31 UTC
📝 Commit 9887b56

Note

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

@lowlydba
Merge branch 'main' into lowlydba-schema-docs-versioning
a22f753 
Signed-off-by: John McCall <16843041+lowlydba@users.noreply.github.com>
@lowlydba
John McCall (lowlydba) marked this pull request as ready for review September 15, 2026 19:32
@lowlydba
John McCall (lowlydba) requested a review from a team as a code owner September 15, 2026 19:32
Copilot AI lite review requested due to automatic review settings September 15, 2026 19:32
@github-actions

github-actions Bot commented Sep 15, 2026 •
edited
Loading

Copy link
Copy Markdown

✅MegaLinter analysis: Success

Descriptor Linter Files Fixed Errors Max errors Warnings Elapsed time
✅ JAVASCRIPT eslint 26 0 0 15.43s
✅ MARKDOWN markdownlint 427 0 0 0.47s
✅ SQL sqlfluff 69 0 0 4.14s

See detailed reports in MegaLinter artifacts

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

  • Documentation: Custom Flavors
  • Command: npx mega-linter-runner@10.1.0 --custom-flavor-setup --custom-flavor-linters JAVASCRIPT_ES,MARKDOWN_MARKDOWNLINT,SQL_SQLFLUFF

MegaLinter is provided by OX Security
Show us your support by starring ⭐ the repository

@lowlydba

John McCall (lowlydba) commented Sep 15, 2026

Copy link
Copy Markdown
Contributor Author

Dana Bauer (@danabauer) This is an MVP for the versioned schema docs - see the main PR body for a few of the minor workarounds involved, but I think it gets the job done more or less.

It'll still be a manual post/release effort to run the script, cut a PR, and add a new schema docs version, but we can enhance later to close that automation gap

Copilot AI reviewed Sep 15, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The schema plugin does not load the committed versioned docs and sidebars, and three snapshot category links remain invalid or unpinned.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR moves schema reference docs into a separate versioned Docusaurus instance, preserving latest and adding snapshots for v1.17.0, v1.18.0, and v2.0.0.

Changes:

  • Adds schema navigation, version metadata, and dropdown styling.
  • Adds versioned documentation snapshots and sidebars.
  • Updates generation tooling, CI workflows, and repository configuration.

Review findings include one critical configuration issue and three nit findings concerning versioned category CSV links.

File summaries
File Description
src/css/custom.css Schema version dropdown styling.
sidebars.js Main documentation navigation.
sidebars-schema.js Schema navigation.
schema/index.md Schema instance entry page.
schema_versions.json Released schema version registry.
schema_versioned_sidebars/version-v2.0.0-sidebars.json v2.0.0 sidebar snapshot.
schema_versioned_sidebars/version-v1.18.0-sidebars.json v1.18.0 sidebar snapshot.
schema_versioned_sidebars/version-v1.17.0-sidebars.json v1.17.0 sidebar snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/width.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/width_rules.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/width_rule.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/speed.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/speed_value.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/speed_limits.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/segment_subtype.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/routes.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/road_surfaces.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/road_surface.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/road_surface_rule.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/road_subclass.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/road_subclass_rules.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/road_subclass_rule.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/road_flags.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/road_flag.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/road_flag_rule.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/rail_flags.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/rail_flag.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/rail_flag_rule.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/rail_class.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/prohibited_transitions.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/prohibited_transition_sequence_entry.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/level_rules.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/level_rule.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/destinations.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/destination_rule.when.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/destination_labels.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/destination_label_type.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/connector_reference.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/access_type.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/access_rules.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/segment/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/transportation/types/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/transportation/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/system/wikidata_id.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/system/stripped_string.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/system/snake_case_string.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/system/region_code.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/system/ref/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/system/phone_number.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/system/no_whitespace_string.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/system/json_pointer.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/system/hex_color.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/system/geometric.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/system/country_code_alpha2.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/system/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/pydantic/networks/http_url.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/pydantic/networks/email_str.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/pydantic/networks/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/pydantic/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/places/types/operating_status.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/places/types/address.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/places/types/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/places/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/divisions/types/norms.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/divisions/types/hierarchy.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/divisions/types/hierarchy_item.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/divisions/types/capital_of_division_item.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/divisions/types/boundary_class.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/divisions/types/area_class.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/divisions/types/admin_level.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/divisions/types/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/divisions/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/common/weight_unit.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/speed_unit.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/sort_key.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/vehicle_width_selector.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/vehicle_weight_selector.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/vehicle_relation.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/vehicle_length_selector.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/vehicle_height_selector.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/travel_mode.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/side.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/recognized_status.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/purpose_of_use.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/opening_hours.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/linearly_referenced_position.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/heading.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/scoping/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/common/prominence.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/perspectives.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/perspective_mode.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/level.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/length_unit.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/confidence_score.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/common_names.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/common/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/buildings/types/roof_shape.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/buildings/types/roof_orientation.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/buildings/types/roof_material.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/buildings/types/facade_material.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/buildings/types/building_subtype.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/buildings/types/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/buildings/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/base/types/water_subtype.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/base/types/source_tags.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/base/types/land_subtype.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/base/types/land_cover_subtype.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/base/types/infrastructure_subtype.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/base/types/height.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/base/types/elevation.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/base/types/depth.md v2.0.0 schema snapshot.
schema_versioned_docs/version-v2.0.0/reference/base/types/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/base/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/addresses/types/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v2.0.0/reference/addresses/_category_.json v2.0.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/width.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/width_rules.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/width_rule.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/surfaces.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/surface_rule.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/subtype.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/subclass.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/subclass_rules.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/subclass_rule.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/speed.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/speed_value.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/speed_limits.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/sequence_entry.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/routes.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/road_surface.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/road_flags.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/road_flag.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/road_flag_rule.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/road_class.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/rail_flags.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/rail_flag.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/rail_flag_rule.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/rail_class.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/prohibited_transitions.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/level_rules.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/level_rule.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/destinations.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/destination_sign_symbol.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/destination_rule.when.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/destination_labels.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/destination_label_type.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/connector_reference.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/access_type.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/access_rules.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/transportation/types/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/transportation/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/system/wikidata_id.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/system/stripped_string.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/system/snake_case_string.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/system/region_code.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/system/ref/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/system/primitive/geometry.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/system/primitive/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/system/phone_number.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/system/no_whitespace_string.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/system/json_pointer.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/system/hex_color.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/system/country_code_alpha2.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/system/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/pydantic/networks/http_url.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/pydantic/networks/email_str.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/pydantic/networks/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/pydantic/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/places/types/operating_status.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/places/types/address.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/places/types/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/places/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/divisions/types/norms.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/divisions/types/hierarchy.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/divisions/types/hierarchy_item.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/divisions/types/capital_of_division_item.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/divisions/types/boundary_class.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/divisions/types/area_class.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/divisions/types/admin_level.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/divisions/types/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/divisions/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/common/weight_unit.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/speed_unit.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/sort_key.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/vehicle_width_selector.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/vehicle_weight_selector.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/vehicle_relation.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/vehicle_length_selector.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/vehicle_axle_count_selector.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/travel_mode.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/side.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/recognized_status.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/purpose_of_use.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/opening_hours.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/linearly_referenced_position.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/heading.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/scoping/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/common/prominence.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/perspectives.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/perspective_mode.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/level.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/length_unit.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/confidence_score.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/common_names.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/common/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/buildings/types/roof_shape.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/buildings/types/roof_orientation.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/buildings/types/roof_material.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/buildings/types/facade_material.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/buildings/types/building_subtype.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/buildings/types/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/buildings/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/base/types/water_subtype.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/base/types/source_tags.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/base/types/land_subtype.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/base/types/land_cover_subtype.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/base/types/infrastructure_subtype.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/base/types/height.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/base/types/elevation.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/base/types/depth.md v1.18.0 schema snapshot.
schema_versioned_docs/version-v1.18.0/reference/base/types/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/base/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/addresses/types/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.18.0/reference/addresses/_category_.json v1.18.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/width.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/width_rules.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/width_rule.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/surfaces.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/surface_rule.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/subtype.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/subclass.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/subclass_rules.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/subclass_rule.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/speed.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/speed_value.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/speed_limits.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/sequence_entry.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/routes.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/road_surface.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/road_flags.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/road_flag.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/road_flag_rule.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/road_class.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/rail_flags.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/rail_flag.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/rail_flag_rule.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/rail_class.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/prohibited_transitions.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/level_rules.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/level_rule.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/destinations.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/destination_sign_symbol.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/destination_rule.when.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/destination_labels.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/destination_label_type.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/connector_reference.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/access_type.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/access_rules.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/transportation/types/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/transportation/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/system/wikidata_id.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/system/stripped_string.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/system/snake_case_string.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/system/region_code.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/system/ref/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/system/primitive/geometry.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/system/primitive/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/system/phone_number.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/system/no_whitespace_string.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/system/json_pointer.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/system/hex_color.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/system/country_code_alpha2.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/system/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/pydantic/networks/http_url.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/pydantic/networks/email_str.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/pydantic/networks/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/pydantic/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/places/types/operating_status.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/places/types/address.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/places/types/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/places/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/divisions/types/norms.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/divisions/types/hierarchy.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/divisions/types/hierarchy_item.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/divisions/types/capital_of_division_item.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/divisions/types/boundary_class.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/divisions/types/area_class.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/divisions/types/admin_level.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/divisions/types/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/divisions/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/common/weight_unit.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/speed_unit.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/sort_key.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/scoping/vehicle_relation.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/scoping/vehicle_axle_count_selector.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/scoping/travel_mode.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/scoping/side.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/scoping/recognized_status.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/scoping/purpose_of_use.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/scoping/opening_hours.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/scoping/linearly_referenced_position.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/scoping/heading.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/scoping/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/common/prominence.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/perspectives.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/perspective_mode.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/level.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/length_unit.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/confidence_score.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/common_names.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/common/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/buildings/types/roof_shape.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/buildings/types/roof_orientation.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/buildings/types/roof_material.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/buildings/types/facade_material.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/buildings/types/building_subtype.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/buildings/types/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/buildings/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/base/types/water_subtype.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/base/types/source_tags.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/base/types/land_subtype.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/base/types/land_cover_subtype.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/base/types/infrastructure_subtype.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/base/types/height.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/base/types/elevation.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/base/types/depth.md v1.17.0 schema snapshot.
schema_versioned_docs/version-v1.17.0/reference/base/types/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/base/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/addresses/types/_category_.json v1.17.0 category metadata.
schema_versioned_docs/version-v1.17.0/reference/addresses/_category_.json v1.17.0 category metadata.
.markdownlintignore Lint exclusions.
.gitignore Generated-file handling.
.github/workflows/staging_deploy.yaml Staging deployment workflow.
.github/workflows/production_deploy_documentation.yml Production documentation deployment workflow.
.github/workflows/ci.yml CI workflow.
.gitattributes Repository file attributes.
Review details

Suppressed comments (2)

schema_versioned_docs/version-v1.17.0/reference/places/types/categories.md:5

  • This released snapshot links the category CSV on the schema repository's moving main branch. As a result, /schema/v1.17.0/ can silently display a category list changed after v1.17.0, which breaks the snapshot/versioning contract documented in README.md:31-36. Please have the generator emit a tag-pinned URL (or snapshot the CSV) and regenerate this page.
    schema_versioned_docs/version-v1.17.0/reference/places/types/categories.md:5
  • This snapshot links the category CSV at blob/main/.../overture_categories.csv, but the schema repository does not contain that file at the referenced path (and the v1.17.0 tag's corresponding directory only contains index.mdx), so this rendered link is a 404. Remove the claim for this version or update the generator to emit a valid source link only when the tagged artifact exists.
  • Files reviewed: 299/497 changed files
  • Comments generated: 2
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread docusaurus.config.js
Comment thread schema_versioned_docs/version-v1.18.0/reference/places/types/categories.md Outdated
@lowlydba
Pin schema repo links in versioned snapshots to their tag
2d3a664 
Docstrings link into OvertureMaps/schema at main; those paths drift after
release. add-schema-version now rewrites blob/main and tree/main links to
the snapshotted tag, applied to the existing v1.17.0 and v1.18.0 snapshots.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Signed-off-by: John McCall <john@overturemaps.org>
jjcfrancisco
Francisco Jiménez (jjcfrancisco) approved these changes Sep 16, 2026
View reviewed changes

@jjcfrancisco Francisco Jiménez (jjcfrancisco) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lgtm

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@jjcfrancisco Francisco Jiménez (jjcfrancisco) jjcfrancisco approved these changes
@danabauer Dana Bauer (danabauer) Awaiting requested review from danabauer

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[ENHANCEMENT] Add per-version schema docs

3 participants

@lowlydba @jjcfrancisco