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

PYDANTIC_GUIDE.md

@@ -850,11 +850,11 @@ Instead of making classes abstract, we use **entry point registration** where on
 ```python
 # In packages/overture-schema-transportation-theme/pyproject.toml
 [project.entry-points."overture.models"]
-"transportation.connector" = "overture.schema.transportation.connector.models:Connector"
-"transportation.segment" = "overture.schema.transportation.segment.models:Segment"
+connector = "overture.schema.transportation:Connector"
+segment = "overture.schema.transportation: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:
+**Real example:** See [`packages/overture-schema-transportation-theme/src/overture/schema/transportation/segment/__init__.py`](packages/overture-schema-transportation-theme/src/overture/schema/transportation/segment/__init__.py) where:
 
 - **`Segment`** is a discriminated union: `RoadSegment | RailSegment | WaterSegment`
 - **`TransportationSegment`** is the concrete base class that all segment types inherit from
@@ -1095,7 +1095,7 @@ class Address(BaseModel):
     freeform: str | None = None
     locality: str | None = None
 
-# In overture-schema-buildings-theme/src/overture/schema/buildings/building/models.py
+# In overture-schema-buildings-theme/src/overture/schema/buildings/building.py
 class Building(OvertureFeature):
     address: Address | None = None
 ```

examples/transportation/segment/road/road.yaml

@@ -28,7 +28,6 @@ properties:
     - value: gravel
   road_flags:
     - values: [is_link, is_tunnel] # Note: `is_link` is deprecated and will be removed in a future release in favor of the link subclass
-  level: -1
   level_rules:
     - value: -1
   width_rules:

packages/overture-schema-codegen/tests/test_example_loader.py

@@ -23,7 +23,7 @@
 )
 from overture.schema.system.geometric import BBox, Geometry
 from overture.schema.transportation import Segment
-from overture.schema.transportation.segment.models import (
+from overture.schema.transportation.segment import (
     RoadSegment,
     TransportationSegment,
 )

packages/overture-schema-codegen/tests/test_integration_real_models.py

@@ -18,8 +18,7 @@
 from overture.schema.codegen.markdown.renderer import render_model
 from overture.schema.codegen.spec_discovery import extract_model_spec
 from overture.schema.system.discovery import discover_models
-from overture.schema.transportation import Segment
-from overture.schema.transportation.segment.models import RoadSegment
+from overture.schema.transportation import RoadSegment, Segment
 from pydantic import BaseModel
 
 

packages/overture-schema-divisions-theme/src/overture/schema/divisions/division_boundary.py

@@ -70,7 +70,7 @@ class DivisionBoundary(
     Some boundaries may be disputed by the divisions on one or both sides.
     """
 
-    model_config = ConfigDict(title="boundary")
+    model_config = ConfigDict(title="division_boundary")
 
     # Core
     geometry: Annotated[

packages/overture-schema-divisions-theme/tests/division_boundary_baseline_schema.json

@@ -564,6 +564,6 @@
     "geometry",
     "properties"
   ],
-  "title": "boundary",
+  "title": "division_boundary",
   "type": "object"
 }

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

@@ -1,15 +1,75 @@
 """Transportation theme.
 
-Transportation infrastructure including network segments (roads, rail, water) and
-connection points between segments.
+Transportation infrastructure including network segments (road, rail, water) and the
+connection points that join them.
 """
 
 __path__ = __import__("pkgutil").extend_path(__path__, __name__)
 
 from .connector import Connector
-from .segment import Segment
+from .segment import (
+    AccessRule,
+    AccessType,
+    ConnectorReference,
+    DestinationLabels,
+    DestinationLabelType,
+    DestinationRule,
+    DestinationSignSymbol,
+    LevelRule,
+    ProhibitedTransitionRule,
+    ProhibitedTransitionSequenceEntry,
+    RailClass,
+    RailFlag,
+    RailFlagRule,
+    RailSegment,
+    RoadClass,
+    RoadFlag,
+    RoadFlagRule,
+    RoadSegment,
+    RoadSubclass,
+    RoadSubclassRule,
+    RoadSurface,
+    RoadSurfaceRule,
+    RouteReference,
+    Segment,
+    SegmentSubtype,
+    Speed,
+    SpeedLimitRule,
+    TransportationSegment,
+    WaterSegment,
+    WidthRule,
+)
 
 __all__ = [
+    "AccessRule",
+    "AccessType",
     "Connector",
+    "ConnectorReference",
+    "DestinationLabelType",
+    "DestinationLabels",
+    "DestinationRule",
+    "DestinationSignSymbol",
+    "LevelRule",
+    "ProhibitedTransitionRule",
+    "ProhibitedTransitionSequenceEntry",
+    "RailClass",
+    "RailFlag",
+    "RailFlagRule",
+    "RailSegment",
+    "RoadClass",
+    "RoadFlag",
+    "RoadFlagRule",
+    "RoadSegment",
+    "RoadSubclass",
+    "RoadSubclassRule",
+    "RoadSurface",
+    "RoadSurfaceRule",
+    "RouteReference",
     "Segment",
+    "SegmentSubtype",
+    "Speed",
+    "SpeedLimitRule",
+    "TransportationSegment",
+    "WaterSegment",
+    "WidthRule",
 ]