[REFACTOR] Organize divisions theme Pydantic package, add missing relationships, tidy and add docs

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

@@ -11,7 +11,6 @@
     Depth,
     Elevation,
     Height,
-    SourcedFromOpenStreetMap,
     SourceTags,
     SurfaceMaterial,
 )
@@ -22,22 +21,22 @@
 from .land_use import LandUse, LandUseClass, LandUseSubtype
 from .water import Water, WaterClass, WaterSubtype
 
-# Only the theme's feature type classes should be available for `import *`.
 __all__ = [
     "Bathymetry",
     "Depth",
     "Elevation",
     "Height",
     "Infrastructure",
     "InfrastructureClass",
-    "InfrastructureSubType",
+    "InfrastructureSubtype",
     "Land",
     "LandClass",
     "LandCover",
     "LandCoverSubtype",
     "LandSubtype",
     "LandUse",
-    "SourcedFromOpenStreetMap",
+    "LandUseClass",
+    "LandUseSubtype",
     "SourceTags",
     "SurfaceMaterial",
     "Water",

packages/overture-schema-base-theme/tests/bathymetry_baseline_schema.json

@@ -214,7 +214,7 @@
       "properties": {
         "cartography": {
           "$ref": "#/$defs/CartographicHints",
-          "title": "cartography"
+          "description": "Cartographic hints useful when including the feature in maps"
         },
         "depth": {
           "description": "Depth below surface level of the feature in meters.",

packages/overture-schema-base-theme/tests/infrastructure_baseline_schema.json

@@ -630,7 +630,8 @@
           "type": "integer"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "source_tags": {
           "additionalProperties": true,

packages/overture-schema-base-theme/tests/land_baseline_schema.json

@@ -505,7 +505,8 @@
           "type": "integer"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "source_tags": {
           "additionalProperties": true,

packages/overture-schema-base-theme/tests/land_cover_baseline_schema.json

@@ -231,7 +231,7 @@
       "properties": {
         "cartography": {
           "$ref": "#/$defs/CartographicHints",
-          "title": "cartography"
+          "description": "Cartographic hints useful when including the feature in maps"
         },
         "sources": {
           "description": "Information about the source data used to assemble the feature.",

packages/overture-schema-base-theme/tests/land_use_baseline_schema.json

@@ -582,7 +582,8 @@
           "type": "integer"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "source_tags": {
           "additionalProperties": true,

packages/overture-schema-base-theme/tests/water_baseline_schema.json

@@ -469,7 +469,8 @@
           "type": "integer"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "source_tags": {
           "additionalProperties": true,

packages/overture-schema-buildings-theme/tests/building_baseline_schema.json

@@ -560,7 +560,8 @@
           "type": "number"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "num_floors": {
           "description": "Number of above-ground floors of the building or part.",

packages/overture-schema-buildings-theme/tests/building_part_baseline_schema.json

@@ -444,7 +444,8 @@
           "type": "number"
         },
         "names": {
-          "$ref": "#/$defs/Names"
+          "$ref": "#/$defs/Names",
+          "description": "All known names by which the feature is called"
         },
         "num_floors": {
           "description": "Number of above-ground floors of the building or part.",

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

@@ -132,17 +132,6 @@ def test_supplementary_types_nested_under_types(self) -> None:
             "buildings/types/building_class.md"
         )
 
-    def test_submodule_supplementary_types_nested_under_types(self) -> None:
-        """Supplementary types in a feature subdirectory go under types/."""
-        specs = flat_specs_from_discovery("divisions")
-        registry, _ = _build_registry(specs)
-
-        # AreaClass is from overture.schema.divisions.division_area.enums,
-        # a subdirectory of the divisions feature directory.
-        assert lookup_by_name(registry, "AreaClass") == PurePosixPath(
-            "divisions/types/division_area/area_class.md"
-        )
-
     def test_shared_types_not_nested(self) -> None:
         """Core/system supplementary types stay at their module-mirrored path."""
         specs = flat_specs_from_discovery("buildings")

packages/overture-schema-core/src/overture/schema/core/cartography.py

@@ -106,4 +106,9 @@ class CartographicallyHinted(BaseModel):
     Properties for adding cartographic hints to a model.
     """
 
-    cartography: Annotated[CartographicHints | None, Field(title="cartography")] = None
+    cartography: Annotated[
+        CartographicHints | None,
+        Field(
+            description="Cartographic hints useful when including the feature in maps"
+        ),
+    ] = None

packages/overture-schema-core/src/overture/schema/core/names.py

@@ -224,4 +224,7 @@ class Names(BaseModel):
 class Named(BaseModel):
     """Properties defining the names of a model."""
 
-    names: Names | None = None
+    names: Annotated[
+        Names | None,
+        Field(description="All known names by which the feature is called"),
+    ] = None

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

@@ -6,8 +6,23 @@
 
 __path__ = __import__("pkgutil").extend_path(__path__, __name__)
 
-from .division import Division
-from .division_area import DivisionArea
-from .division_boundary import DivisionBoundary
+from ._common import AdminLevel, DivisionSubtype
+from .division import CapitalOfDivisionItem, Division, DivisionClass, Norms
+from .division_area import AreaClass, DivisionArea
+from .division_boundary import BoundaryClass, DivisionBoundary
 
-__all__ = ["Division", "DivisionArea", "DivisionBoundary"]
+# Exclude from `__all__`: internal implementation details, and types that are effectively annotated
+# primitives, such as `AdminLevel`, where a person working with one of the feature types likely
+# would not need to import that type because they'll just set the field to a Python primitive value
+# directly. (e.g., `my_division.admin_level = 4`).
+__all__ = [
+    "AreaClass",
+    "BoundaryClass",
+    "CapitalOfDivisionItem",
+    "Division",
+    "DivisionArea",
+    "DivisionClass",
+    "DivisionSubtype",
+    "DivisionBoundary",
+    "Norms",
+]

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

@@ -0,0 +1,115 @@
+import textwrap
+from typing import Annotated, NewType
+
+from pydantic import Field
+
+from overture.schema.system.doc import DocumentedEnum
+from overture.schema.system.model_constraint import FieldEqCondition
+from overture.schema.system.primitive import int32
+
+AdminLevel = NewType(
+    "AdminLevel",
+    Annotated[
+        int32,
+        Field(
+            description=textwrap.dedent("""
+                Integer representing the division's position in its country's administrative
+                hierarchy, where lower numbers correspond to higher level administrative units.
+            """).strip(),
+            ge=0,
+            le=16,
+        ),
+    ],
+)
+
+
+class DivisionSubtype(str, DocumentedEnum):
+    """
+    Category of the division from a finite, hierarchical, ordered list of categories (e.g., country,
+    region, locality, etc.) similar to a Who's on First placetype.
+    """
+
+    COUNTRY = (
+        "country",
+        "Largest unit of independent sovereignty, e.g., the United States, France.",
+    )
+
+    DEPENDENCY = (
+        "dependency",
+        textwrap.dedent("""
+            A place that is not exactly a sub-region of a country but is dependent on a parent
+            country for defence, passport control, etc., e.g., Puerto Rico.
+        """).strip(),
+    )
+
+    MACROREGION = (
+        "macroregion",
+        textwrap.dedent("""
+            A bundle of regions, e.g., England, Scotland, Île-de-France. These exist mainly in
+            Europe.
+        """).strip(),
+    )
+
+    REGION = (
+        "region",
+        textwrap.dedent("""
+            A state, province, region, etc. Largest sub-country administrative unit in most
+            countries, except those that have dependencies or macro-regions.
+        """).strip(),
+    )
+
+    MACROCOUNTY = (
+        "macrocounty",
+        "A bundle of counties, e.g. Inverness. These exist mainly in Europe.",
+    )
+
+    COUNTY = (
+        "county",
+        textwrap.dedent("""
+            Largest sub-region administrative unit in most countries, unless they have
+            macrocounties.
+        """).strip(),
+    )
+
+    LOCALADMIN = (
+        "localadmin",
+        textwrap.dedent("""
+            An administrative unit existing in some parts of the world that contains localities
+            or populated places, e.g. département de Paris. Often the contained places do not
+            have independent authority. Often, but not exclusively, found in Europe.
+        """).strip(),
+    )
+
+    LOCALITY = (
+        "locality",
+        "A populated place that may or may not have its own administrative authority.",
+    )
+
+    BOROUGH = (
+        "borough",
+        "A local government unit subordinate to a locality.",
+    )
+
+    MACROHOOD = (
+        "macrohood",
+        textwrap.dedent("""
+            A super-neighborhood that contains smaller divisions of type neighborhood, e.g.
+            BoCaCa (Boerum Hill, Cobble Hill, and Carroll Gardens).
+        """).strip(),
+    )
+
+    NEIGHBORHOOD = (
+        "neighborhood",
+        textwrap.dedent("""
+            A neighborhood. Most neighborhoods will be just this, unless there's enough granular
+            detail to justify introducing macrohood or microhood divisions.
+        """).strip(),
+    )
+
+    MICROHOOD = (
+        "microhood",
+        "A mini-neighborhood that is contained within a division of type neighborhood.",
+    )
+
+
+IS_COUNTRY = FieldEqCondition("subtype", DivisionSubtype.COUNTRY)