Skip to content

[REFACTOR] Organize transportation theme Pydantic package, add relationships, sync JSON Schema, and tidy docs - #598

Merged
Victor Schappert (vcschapp) merged 1 commit into
mainfrom
pp7
Jul 30, 2026
Merged

[REFACTOR] Organize transportation theme Pydantic package, add relationships, sync JSON Schema, and tidy docs#598
Victor Schappert (vcschapp) merged 1 commit into
mainfrom
pp7

Conversation

@vcschapp

@vcschapp Victor Schappert (vcschapp) commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Description

This brings us closer to the end of the Pydantic package organization journey: transportation was the last theme package still on the old layout. With this PR every theme package—addresses, base, buildings, divisions, places, and now transportation —is organized consistently.

Transportation differs from the earlier themes in three ways. First, segment is a discriminated union over road/rail/water subtypes, so it becomes a small package rather than a single module. Second, this PR makes a couple of technically backwardly-incompatible, but in practice not really, changes to the transportation segment feature to push down a few fields that have been wrongly defined at the segment level down to the level of the road segment: routes and subclass_rules. Third, this change back ports a few changes on to the old legacy JSON Schema to keep it in sync-ish until we delete it. The back-ported changes are the two already mentioned plus removing level from segment to close the loop on a change Seth Fitzsimmons (@sethfitz) made in PR #390.

tl;dr

  • Aligned the organization of the transportation theme with addresses, base, buildings, divisions, and places.
  • segment becomes a package (road.py, rail.py, water.py + a private _common.py for the shared base); connector becomes a flat module.
  • Added missing connector/segment relationships on DestinationRule and ProhibitedTransitionSequenceEntry.
  • Reconciled model ↔ JSON Schema: made routes and subclass_rules road-only (back-ported to the JSON Schema), and removed the scalar level from JSON Schema since [Pydantic] housekeeping #390 removed it from the Pydantic schema.
  • Tidied docs: make docformat clean, converted SegmentSubtype/AccessType to DocumentedEnum, and documented the previously-undefined designated access type.

Merge guidance: Squash

The work is captured as a single squashed commit, so this PR should be squash-merged.

Journey

Testing

make check passes (lint, mypy, doctest, and the full test suite). JSON Schema baselines were regenerated to reflect the reconciled model.

Documentation website

Docs preview for this PR.

Related Issues

Closes #599.

@github-actions

github-actions Bot commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown

🗺️ Schema reference docs preview is live!
🌍 Preview https://staging.overturemaps.org/schema/pr/598/schema/index.html
🕐 Updated Jul 30, 2026 00:46 UTC
📝 Commit 81c1f74
🔧 env SCHEMA_PREVIEW true

Note

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

@vcschapp Victor Schappert (vcschapp) mentioned this pull request Jul 24, 2026
Closed
vcschapp
Victor Schappert (vcschapp) commented Jul 27, 2026
View reviewed changes
Comment thread examples/transportation/segment/road/road.yaml
vcschapp
Victor Schappert (vcschapp) commented Jul 27, 2026
View reviewed changes
Comment thread schema/transportation/segment.yaml
@RoelBollens-TomTom

Roel Bollens (RoelBollens-TomTom) commented Jul 27, 2026

Copy link
Copy Markdown
Collaborator

While reading through this I noticed PYDANTIC_GUIDE.md still references the old module paths (as well as old entry point key naming):

schema/PYDANTIC_GUIDE.md

Lines 852 to 857 in 2358544

[project.entry-points."overture.models"]
"transportation.connector" = "overture.schema.transportation.connector.models:Connector"
"transportation.segment" = "overture.schema.transportation.segment.models:Segment"
```
**Real example:** See [`packages/overture-schema-transportation-theme/src/overture/schema/transportation/segment/models.py`](packages/overture-schema-transportation-theme/src/overture/schema/transportation/segment/models.py) where:

Feel free to change, however the guide has broader staleness that predates this PR such as the models.py convention and several examples reference paths like buildings/building/models.py that were likely removed in earlier changes. That feels out of scope for this PR.

sethfitz
Seth Fitzsimmons (sethfitz) previously approved these changes Jul 28, 2026
View reviewed changes

@sethfitz Seth Fitzsimmons (sethfitz) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Looks good other than the silly backticks (for a follow-up?).

Comment thread ...s/overture-schema-transportation-theme/src/overture/schema/transportation/segment/_common.py Outdated
@sethfitz Seth Fitzsimmons (sethfitz) mentioned this pull request Jul 28, 2026
Open
@sethfitz

Seth Fitzsimmons (sethfitz) commented Jul 28, 2026

Copy link
Copy Markdown
Collaborator

Thanks — filed as #604 so it doesn't ride along here. I confirmed both halves: the entry point keys are unqualified (connector/segment, not transportation.connector) and resolve off the theme package root, and the models.py-under-a-type-subdirectory convention the guide prescribes is already contradicted by buildings' flat layout — this PR removes the last theme-package models.py, which also breaks the guide's L857 link. Agreed it's out of scope here; the rewrite is better done once this lands so the transportation examples describe the settled structure. I've taken it.

@vcschapp

Victor Schappert (vcschapp) commented Jul 28, 2026

Copy link
Copy Markdown
Collaborator Author

While reading through this I noticed PYDANTIC_GUIDE.md still references the old module paths (as well as old entry point key naming):

schema/PYDANTIC_GUIDE.md

Lines 852 to 857 in 2358544

[project.entry-points."overture.models"]
"transportation.connector" = "overture.schema.transportation.connector.models:Connector"
"transportation.segment" = "overture.schema.transportation.segment.models:Segment"
```
**Real example:** See [`packages/overture-schema-transportation-theme/src/overture/schema/transportation/segment/models.py`](packages/overture-schema-transportation-theme/src/overture/schema/transportation/segment/models.py) where:

Feel free to change, however the guide has broader staleness that predates this PR such as the models.py convention and several examples reference paths like buildings/building/models.py that were likely removed in earlier changes. That feels out of scope for this PR.

This is a good find - thanks. I think the right call is just to update it now, so I did that. PYDANTIC_GUIDE.md should have the right references now.

Merged
danabauer
Dana Bauer (danabauer) previously approved these changes Jul 29, 2026
View reviewed changes
Comment thread examples/transportation/segment/road/road.yaml
@vcschapp
Organize transportation pkg, add relationships, sync schema, tidy docs
81c1f74 
This commit organizes the transportation Pydantic package to align with
the other theme packages already done: addresses, base, buildings,
divisions, and places. Transportation was the last theme still using the
old layout, so with this commit the whole theme set is organized
consistently.

Organization work done:

1. Each feature type gets its own main module. `connector` becomes a
   flat `connector.py`, but because `segment` is a discriminated union
   over road, rail, and water subtypes, `segment` becomes a *package*
   with one module per subtype (`road.py`, `rail.py`, `water.py`) plus a
   private `_common.py` for the shared base. This is the one place we do
   NOT eliminate a sub-directory (unlike divisions): the subtype union
   makes a package the natural fit.
2. Types used exclusively by one subtype move into that subtype's module
   and are renamed to be subtype-scoped: `Subtype` -> `SegmentSubtype`,
   `Subclass` -> `RoadSubclass`, `SubclassRule` -> `RoadSubclassRule`,
   `SurfaceRule` -> `RoadSurfaceRule`, `AccessRestrictionRule` ->
   `AccessRule`, `SequenceEntry` -> `ProhibitedTransitionSequenceEntry`.
   Exception (deliberate): the mode-independent rule types currently used
   only by road but conceivably reusable by other subtypes (the
   prohibited-transition, speed, and width types) are kept in `_common.py`.
3. Eliminated the old flat `enums.py`, `models.py`, and `types.py`, and
   the `connector/` and `segment/` (models.py) sub-packages.
4. Curated `__all__` in both the theme `__init__.py` and the segment
   package's `__init__.py`.

Relationships added:

1. `from_connector_id` and `to_connector_id` in `DestinationRule` (to
   `Connector`).
2. `to_segment_id` in `DestinationRule` (to `TransportationSegment`).
3. `connector_id` in `ProhibitedTransitionSequenceEntry` (to `Connector`).
4. `segment_id` in `ProhibitedTransitionSequenceEntry` (to
   `TransportationSegment`).

Docs tidied and updated:

1. Eliminated all `make docformat` errors pertaining to transportation.
2. Converted `SegmentSubtype` and `AccessType` to `DocumentedEnum` so
   they have a richer presence in the schema reference. (`RoadSurface`
   and `DestinationLabelType` are intentionally left as plain enums for
   now, as I don't have cycles to generate docs for them.)

Schema reconciliation (a dimension the divisions refactor did not have):

1. Made `routes` and `subclass_rules` road-only (moved from the shared
   base to `RoadSegment`) and back-ported the change to the JSON Schema
   so both representations agree. While technically backwardly-
   incompatible, this fixes a error that dates back to the JSON Schema
   and that was never intended.
2. Removed the scalar `level` from segment in both the Pydantic model and
   the JSON Schema, finishing the model/schema sync begun in "Remove
   levels from types without data for them" (commit dd5d3f2, PR #390),
   which updated the model but left `level` on the legacy JSON Schema,
   leading to a discrepancy between schemas.

Signed-off-by: schapper <schapper@amazon.com>
@vcschapp
Victor Schappert (vcschapp) merged commit 54a584a into main Jul 30, 2026
20 checks passed
@vcschapp Victor Schappert (vcschapp) mentioned this pull request Jul 31, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sethfitz Seth Fitzsimmons (sethfitz) sethfitz approved these changes
@RoelBollens-TomTom Roel Bollens (RoelBollens-TomTom) RoelBollens-TomTom approved these changes
@danabauer Dana Bauer (danabauer) danabauer left review comments
@TristanDiet-TomTom TristanDiet-TomTom Awaiting requested review from TristanDiet-TomTom

Assignees

No one assigned

Labels

change type - cosmetic 🌹 Cosmetic change

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Refactor transportation theme Pydantic schema to match other packages

4 participants

@vcschapp @RoelBollens-TomTom @sethfitz @danabauer