[chore] [but is it?] Release version 2.0.0 🚀🚀🚀🚀🚀 by vcschapp · Pull Request #709 · OvertureMaps/schema

Victor Schappert (vcschapp) · 2026-09-02T17:14:16Z

Description

This PR releases version 2.0.0 of the Overture Schema 🎉

It's been a big team effort to get here, so thanks to everyone who made this happen! 🙌

Reviewers, please review this carefully as it would be ideal to get it right the first time if possible. 🔍

Merge Strategy

This PR should be merged to main as a a MERGE COMMIT. It's important to do it as a merge commit. The branching automation should then be able to rebase vnext on top of it, getting it ready for the next major change.

Checks Failing

The following checks are failing:

DCO. This is because of some old commits from the pre-DCO era that will be merged onto main (Jacob Wasserman (@jwass)' commits from January/February timeframe). Mitigation: Override the check, it's a false positive.
vnext compatibility. This appears to be failing because this type of major change release isn't contemplated by the compatibility check. Mitigation: Please review the analysis here carefully and if it looks right, we override.

What Happens on Merge

When this PR is merged, it should engage the automation machinery to do all of the following:

Publish all overture-schema* packages to PyPI at version 2.0.0.
Cut GitHub releases for each overture-schema* package.
Attach overture-schema.json to the GitHub release for the overture-schema umbrella, ella, ella package.
Rebase vnext over main so that vnext is ready to accept the next major change PR.
And of course publish internal v2.0.0 releases to CodeArtifact.

The machinery is reviewed and tested but it would not be surprising if something breaks and we have to jump in and fix it. In that case we may need to do some patching/kludging effort or manual effort to unstick any failed publishes and get the process to complete itself. It's all good.

Mandatory Bureaucracy

Closes #710.

`connectors` was optional with a `[]` default that its own `min_length=2` constraint rejected. Pydantic does not validate defaults unless `validate_default=True`, so the invalid value was accepted on the way in and refused on the way back out: a segment built without connectors dumped to `connectors: []`, which re-validation rejected. Every segment is physically connected to at least two connectors, and the published data agrees -- across all 350,469,378 segments in release 2026-08-19.0 there is not one null, empty, or single-element `connectors`. So the field becomes required rather than optional-with-a-default, and moves up beside `subtype` in the model's required section. The YAML schema gains `connectors` in its segment `required` list, dropping the matching `default: []` beside `minItems: 2`. Every valid segment example gains a two-connector array, and so does every segment counterexample that was not testing connectors, so each keeps failing only for the defect it names. Both corpora are updated: `reference/` (read by the test suite) and the root `examples/`/`counterexamples/` trees (the docs site symlinks `examples/`). `theme-type-mismatch.json` is left alone -- it declares `theme: buildings` with `type: segment` and never reaches a segment arm. Fixes #669 Signed-off-by: Seth Fitzsimmons <seth@mojodna.net>

Signed-off-by: Connie Sun <connie@overturemaps.org>

…gories Signed-off-by: Connie Sun <connie@overturemaps.org>

…to places init Signed-off-by: Connie Sun <connie@overturemaps.org>

Implements the policy in #695 for three of the four remaining sites: no schema field carries a non-null default, and where a value would come from a default the publisher supplies it in the published data. - `Stacked.level` drops `= 0` and becomes `None`. The absence sentence goes on the field rather than the `Level` NewType, because `Level` is also the type of the required `LevelRule.value`, where absence is impossible. Removing the default also retires the `# type: ignore[assignment]` that existed only to admit it. - `Land.class_`, `Land.subtype`, `Water.class_`, `Water.subtype` become required, matching `Infrastructure` and `LandUse`. No consumer sees a difference. Measured on release 2026-08-19.0, one partition per type: `level = 0` appears in 0 of 1,174,629 land and 0 of 1,985,644 water rows, and `class`/`subtype` are never null in either. Both partitions validate clean against the changed models. `SpeedLimitRule.is_max_speed_variable` is deliberately left out. Its default cannot be removed without stating what absence means, and the data does not settle that: the publisher writes an explicit `false` for closed-world booleans (`building.has_parts` is 0 null / 4,777,998 false) but never for this one (0 false in 1,376,379 rules across three partitions), so absence is an unrecorded value rather than a recorded "no". That call needs a domain owner. Refs #696 Signed-off-by: Seth Fitzsimmons <seth@mojodna.net>

Completes the removal begun in the previous commit: `SpeedLimitRule. is_max_speed_variable` drops `= False`. A rule parsed without the flag now yields `None` instead of `False`. The description is left as it stands. What absence means here is a domain question the schema should not answer by inference, and the existing wording does not define the term well enough to extend safely. Both are worth settling, separately, with the transportation folks. Refs #696 Signed-off-by: Seth Fitzsimmons <seth@mojodna.net>

Coordinated 2.0.0 launch of all 13 packages/* for the first public PyPI release. Bumps every package version 0.1.1/1.17.1 -> 2.0.0, raises all intra-repo dependency floors to >=2.0.0 (including overture-schema-validation's previously-bare common/system deps), and folds towncrier changelog.d fragments into per-package CHANGELOG.md. Refreshes uv.lock. The umbrella overture-schema majors purely by cascade: its dependencies overture-schema-theme-places and -transportation carry breaking changes (#434, #669), which forces the umbrella major bump and floor raise per the versioning guardrails. Signed-off-by: schapper <schapper@amazon.com>

github-actions · 2026-09-02T17:15:58Z

🗺️ Schema reference docs preview is live!


🌍 Preview	https://staging.overturemaps.org/schema/pr/709/schema/index.html
🕐 Updated	Sep 02, 2026 19:12 UTC
📝 Commit	a294c12
🔧 env SCHEMA_PREVIEW	`true`

Note

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

github-actions · 2026-09-02T17:18:55Z

⚠️ `vnext` compatibility conflict detected

If this PR merges to main, vnext cannot be cleanly rebased on top.
Your changes conflict with something already on vnext.

Conflicting files:

packages/overture-schema-theme-places/src/overture/schema/places/__init__.py

How to fix:

Do not rebase your branch onto vnext — that would pull unreleased breaking
changes into main. Instead:

See exactly what vnext changes in the conflicting file(s):

git fetch origin
git diff origin/main...origin/vnext -- packages/overture-schema-theme-places/src/overture/schema/places/__init__.py

Open each conflicting file in your editor. The diff above shows what vnext adds
or changes there — adjust your edits so they no longer overlap with those lines.
Commit the adjustment and push:

git add packages/overture-schema-theme-places/src/overture/schema/places/__init__.py
git commit -m "fix: resolve vnext compatibility"
git push origin 2_0_0

After pushing, this check will re-run automatically.

Victor Schappert (vcschapp) · 2026-09-02T17:20:58Z

John McCall (@lowlydba) Are there supposed to be two vnext compatibility checks or is that redundantly redundant?

Victor Schappert (vcschapp) · 2026-09-02T17:41:06Z

John McCall (@lowlydba) I think the vnext compatibility check failure is a false positive in this case. This is all very Claude-driven, but here's my analysis:

Structure of this PR:

origin/main   A
                \
origin/vnext     \── X(#434: Categories→Taxonomy)      ← real breaking work
                       \
release/2.0.0           \── B(bump+changelogs)          ← this PR head
                                                          (X is an ancestor of B)

Scenario the vnext compatibility check is looking for:

    main + this PR  ─────►  A + X + B
    then "replay vnext's X on top"  ─►  X applied twice  ─►  💥 phantom conflict

Scenario that should actually happen if we create a normal non-squash merge commit. First we merge with a merge commit:

   A ───────────────── M   ◄── main tip
        \             /
         X ─── B ─────┘   ◄── vnext tip (still at B)

Then the vnext rebase automation runs and brings vnext forward to M:

   A ───────────────── M   ◄── main tip AND vnext tip (both here now)
        \             /
         X ─── B ─────┘

John McCall (lowlydba) · 2026-09-02T17:42:27Z

John McCall (John McCall (@lowlydba)) Are there supposed to be two vnext compatibility checks or is that redundantly redundant?

Its the same workflow, one is the actual check, one is the rollup-check to allow for no-op skip use cases where we're targeting vnext. working as expected 👍🏻

John McCall (lowlydba) · 2026-09-02T17:51:24Z

Scenario that should actually happen if we create a normal non-squash merge commit...

question: Good catch, but I think the fix is narrower than "use a merge commit for this PR.". I may have misspoken earlier in the meeting about the level of flexibility for release paths.

Victor Schappert (@vcschapp)

CONTRIBUTING.md already documents this exact case: vnext opens the PR directly against main and merges as a regular merge commit, not a squash (the vnext → major release section). That's why vnext-compat.yaml's squash-simulation and rebase-vnext.yaml's skip check are both keyed on head_ref == 'vnext'. #709's head is 2_0_0, so neither treats it as the release merge, hence the false positive.

Two ways to close this:

Retarget [chore] [but is it?] Release version 2.0.0 🚀🚀🚀🚀🚀 #709 onto vnext itself (push the bump + changelog commit there, merge as a regular merge commit) and follow the documented flow as-is. No workflow changes needed.
Keep the 2_0_0 staging branch (useful if vnext needs to stay open for more breaking work while this release stabilizes) and formalize it: extend both workflows to detect any PR whose head already contains vnext's tip as an ancestor (git merge-base --is-ancestor origin/vnext HEAD), not just head_ref == 'vnext', and document the branch + merge-commit requirement in CONTRIBUTING.md.

Either way, squash stays the default everywhere else; only the release path itself needs a real merge commit. We may want to consider disabling rebasing altogether to reduce the complications from differing merge contributions overall.

2_0_0 here, is that just an artifact of how this release got staged, or is there a reason to keep vnext open for more breaking work while it stabilizes? That decides which of the two above we want.

Victor Schappert (vcschapp) · 2026-09-02T18:09:55Z

Scenario that should actually happen if we create a normal non-squash merge commit...

question: Good catch, but I think the fix is narrower than "use a merge commit for this PR.". I may have misspoken earlier in the meeting about the level of flexibility for release paths.

Victor Schappert (Victor Schappert (@vcschapp))

CONTRIBUTING.md already documents this exact case: vnext opens the PR directly against main and merges as a regular merge commit, not a squash (the vnext → major release section). That's why vnext-compat.yaml's squash-simulation and rebase-vnext.yaml's skip check are both keyed on head_ref == 'vnext'. #709's head is 2_0_0, so neither treats it as the release merge, hence the false positive.

Two ways to close this:

Retarget [chore] [but is it?] Release version 2.0.0 🚀🚀🚀🚀🚀 #709 onto vnext itself (push the bump + changelog commit there, merge as a regular merge commit) and follow the documented flow as-is. No workflow changes needed.

Keep the 2_0_0 staging branch (useful if vnext needs to stay open for more breaking work while this release stabilizes) and formalize it: extend both workflows to detect any PR whose head already contains vnext's tip as an ancestor (git merge-base --is-ancestor origin/vnext HEAD), not just head_ref == 'vnext', and document the branch + merge-commit requirement in CONTRIBUTING.md.

Either way, squash stays the default everywhere else; only the release path itself needs a real merge commit. We may want to consider disabling rebasing altogether to reduce the complications from differing merge contributions overall.

2_0_0 here, is that just an artifact of how this release got staged, or is there a reason to keep vnext open for more breaking work while it stabilizes? That decides which of the two above we want.

I like the version of option 2 that is "JFDY and cut an issue to update the automation"! Thoughts?

This was a Copilot suggestion on the v2.0.0 release PR, #709. Signed-off-by: Victor Schappert <victor.schappert@protonmail.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Victor Schappert <victor.schappert@protonmail.com>

Seth Fitzsimmons (sethfitz)

The CHANGELOG entries are a bit weird with their recency bias, so I’d be inclined to clear them out in a follow-up commit and point to the launch blog post once it’s live.

Victor Schappert (vcschapp) · 2026-09-02T21:54:54Z

John McCall (@lowlydba) Can we merge this w/ waiting on those checks? I used to have Admin and could do this but was unceremoniously stripped of my privileges :)

I'd rather not wait for #714 and also rather not go fix the DCO on Jake's old commits (although perhaps if you add him as a member that would solve itself on a re-run?)

Seth Fitzsimmons (sethfitz) and others added 13 commits September 2, 2026 16:22

Remove old categories in favor of the new taxonomy field

18da555

Update examples/counterexamples to remove categories field

5bd5cc6

Remove categories references from reference and package tests

86f424f

remove remaining references to categories in docs and examples

d966644

Signed-off-by: Connie Sun <connie@overturemaps.org>

add towncrier changelog fragments for categories deprecation

f2a06df

Signed-off-by: Connie Sun <connie@overturemaps.org>

fix uv lock and remove unnecessary comment for basic category

81a6f46

Signed-off-by: Connie Sun <connie@overturemaps.org>

update baseline snapshot after deleting repetitive comment

2c092a6

Signed-off-by: Connie Sun <connie@overturemaps.org>

update places pyproject with taxonomy and basic_category, remove cate…

f249d72

…gories Signed-off-by: Connie Sun <connie@overturemaps.org>

pr feedback - fix counterexample missing 'websites' and add taxonomy …

cf6bbd8

…to places init Signed-off-by: Connie Sun <connie@overturemaps.org>

Victor Schappert (vcschapp) added change type - cosmetic 🌹 Cosmetic change release 🚀 labels Sep 2, 2026