[REFACTOR] Organize common package for consistency

PYDANTIC_GUIDE.md

@@ -54,7 +54,7 @@ from overture.schema.system.string import (
     NoWhitespaceString,
     StrippedString,
 )
-from overture.schema.common.types import ConfidenceScore
+from overture.schema.common.confidence import ConfidenceScore
 from overture.schema.system.string import LanguageTag
 
 # Numeric types (use these instead of int/float)
@@ -178,7 +178,7 @@ By specifying `OvertureFeature[Literal["buildings"], Literal["building"]]`, you'
 ```python
 from typing import Literal
 from overture.schema.common import OvertureFeature
-from overture.schema.common.models import Stacked
+from overture.schema.common.level import Stacked
 from overture.schema.common.names import Named
 from overture.schema.system.numeric import float64
 
@@ -1088,7 +1088,7 @@ properties:
 **Pydantic approach:**
 
 ```python
-# In overture-schema-common/src/overture/schema/common/models.py
+# In overture-schema-addresses-theme/src/overture/schema/addresses/address.py
 @no_extra_fields
 class Address(BaseModel):
     """A postal address."""
@@ -1131,7 +1131,7 @@ allOf:
 **Pydantic equivalent** uses **mixin classes**:
 
 ```python
-# In common/models.py
+# In common/names.py
 class Named(BaseModel):
     """Properties defining the names of a feature."""
     names: Names | None = None

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

@@ -12,7 +12,7 @@
 from overture.schema.common import (
     OvertureFeature,
 )
-from overture.schema.common.models import Stacked
+from overture.schema.common.level import Stacked
 from overture.schema.common.names import Named
 from overture.schema.system.geometric import (
     Geometry,

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

@@ -12,7 +12,7 @@
 from overture.schema.common import (
     OvertureFeature,
 )
-from overture.schema.common.models import Stacked
+from overture.schema.common.level import Stacked
 from overture.schema.common.names import Named
 from overture.schema.system.geometric import (
     Geometry,

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

@@ -12,7 +12,7 @@
 from overture.schema.common import (
     OvertureFeature,
 )
-from overture.schema.common.models import Stacked
+from overture.schema.common.level import Stacked
 from overture.schema.common.names import Named
 from overture.schema.system.geometric import (
     Geometry,

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

@@ -10,7 +10,7 @@
 from overture.schema.common import (
     OvertureFeature,
 )
-from overture.schema.common.models import Stacked
+from overture.schema.common.level import Stacked
 from overture.schema.common.names import Named
 from overture.schema.system.geometric import (
     Geometry,

packages/overture-schema-buildings-theme/src/overture/schema/buildings/building.py

@@ -10,7 +10,7 @@
 
 from overture.schema.buildings._common import Appearance
 from overture.schema.common import OvertureFeature
-from overture.schema.common.models import Stacked
+from overture.schema.common.level import Stacked
 from overture.schema.common.names import Named
 from overture.schema.system.geometric import (
     Geometry,

packages/overture-schema-buildings-theme/src/overture/schema/buildings/building_part.py

@@ -9,7 +9,7 @@
 from overture.schema.buildings._common import Appearance
 from overture.schema.buildings.building import Building
 from overture.schema.common import OvertureFeature
-from overture.schema.common.models import Stacked
+from overture.schema.common.level import Stacked
 from overture.schema.common.names import Named
 from overture.schema.system.geometric import (
     Geometry,

packages/overture-schema-common/src/overture/schema/common/__init__.py

@@ -1,15 +1,50 @@
-from . import cartography, names, scoping, sources
-from .models import OvertureFeature, ThemeT, TypeT
-from .scoping import Scope, scoped
+"""
+Shared building blocks common to all Overture theme packages.
+
+The `OvertureFeature` base class and the reusable feature components — naming, sources,
+cartographic hints, scoping, and more — that theme packages compose to define their
+feature types.
+
+Subpackages
+-----------
+- :mod:`cartography <overture.schema.common.cartography>` Cartographic display hints.
+- :mod:`confidence <overture.schema.common.confidence>` The `ConfidenceScore` type.
+- :mod:`feature <overture.schema.common.feature>` The `OvertureFeature` base class and its
+  supporting types (`FeatureVersion`, `ThemeT`, `TypeT`).
+- :mod:`level <overture.schema.common.level>` Feature Z-order / stacking (`Level`, `Stacked`).
+- :mod:`names <overture.schema.common.names>` Multilingual naming with variants and rules.
+- :mod:`perspectives <overture.schema.common.perspectives>` Political perspectives on disputed
+  data.
+- :mod:`scoping <overture.schema.common.scoping>` Scoped, conditionally-applicable field values.
+- :mod:`sources <overture.schema.common.sources>` Data provenance and source attribution.
+- :mod:`unit <overture.schema.common.unit>` Units of measure.
+"""
+
+from . import (
+    cartography,
+    confidence,
+    feature,
+    level,
+    names,
+    perspectives,
+    scoping,
+    sources,
+    unit,
+)
+from .feature import FeatureVersion, OvertureFeature, ThemeT, TypeT
 
 __all__ = [
     "cartography",
+    "confidence",
+    "feature",
+    "FeatureVersion",
+    "level",
     "names",
     "OvertureFeature",
-    "Scope",
-    "scoped",
+    "perspectives",
     "scoping",
     "sources",
     "ThemeT",
     "TypeT",
+    "unit",
 ]

packages/overture-schema-common/src/overture/schema/common/confidence.py

@@ -0,0 +1,17 @@
+"""
+Confidence scores for machine-generated or machine-augmented data.
+"""
+
+from typing import Annotated, NewType
+
+from pydantic import Field
+
+from overture.schema.system.numeric import float64
+
+ConfidenceScore = NewType(
+    "ConfidenceScore",
+    Annotated[
+        float64,
+        Field(description="Confidence score between 0.0 and 1.0", ge=0.0, le=1.0),
+    ],
+)

packages/overture-schema-common/src/overture/schema/common/models.py → packages/overture-schema-common/src/overture/schema/common/feature.py

@@ -1,8 +1,12 @@
+"""
+The Overture feature, an Overture-specific refinement of the base `Feature` type defined in the
+system package.
+"""
+
 import textwrap
-from typing import Annotated, Generic, TypeVar
+from typing import Annotated, Generic, NewType, TypeVar
 
 from pydantic import (
-    BaseModel,
     ConfigDict,
     Field,
     GetJsonSchemaHandler,
@@ -13,42 +17,42 @@
 from typing_extensions import Self
 
 from overture.schema.system.feature import Feature
-from overture.schema.system.field_constraint import UniqueItemsConstraint
-from overture.schema.system.geometric import (
-    Geometry,
-)
-from overture.schema.system.model_constraint import no_extra_fields
+from overture.schema.system.numeric import int32
 from overture.schema.system.ref import Id, Identified
-from overture.schema.system.string import (
-    CountryCodeAlpha2,
-)
 
-from .enums import PerspectiveMode
 from .sources import Sources
-from .types import (
-    FeatureVersion,
-    Level,
-)
 
 ThemeT = TypeVar("ThemeT", bound=str)
 TypeT = TypeVar("TypeT", bound=str)
 
+FeatureVersion = NewType(
+    "FeatureVersion", Annotated[int32, Field(ge=0, description="")]
+)
+
 
 class OvertureFeature(Identified, Feature, Generic[ThemeT, TypeT]):
-    """Base class for all Overture features."""
+    """
+    Overture feature, the base class for all Overture features types.
+
+    An `OvertureFeature` extends the fundamental `Feature` type by:
+    - Making the basic ``id`` field required instead of optional.
+    - Adding required fields ``theme``, ``type``, and ``version``.
+    - Adding the optional field ``sources``.
+    """
 
     # Only used to support `ext_*` fields, which are on a deprecation path.
     model_config = ConfigDict(extra="allow")
 
     # Required
 
+    # Repeating `id` from the superclass `Feature` to make it mandatory: it is optional in the
+    # superclass.
     id: Id = Field(
         description="A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS."
     )  # type: ignore[assignment]
     theme: ThemeT
-    # this is an enum in the JSON Schema, but that prevents OvertureFeature from being extended
     type: TypeT
-    geometry: Geometry
+    # Superclass `Feature` provides `geometry` and `bbox`.
     version: FeatureVersion
 
     # Optional
@@ -97,30 +101,3 @@ def __get_pydantic_json_schema__(
         properties_object_schema["additionalProperties"] = False
 
         return json_schema
-
-
-@no_extra_fields
-class Perspectives(BaseModel):
-    """Political perspectives container."""
-
-    # Required
-
-    mode: Annotated[
-        PerspectiveMode,
-        Field(
-            description="Whether the perspective holder accepts or disputes this name."
-        ),
-    ]
-    countries: Annotated[
-        list[CountryCodeAlpha2],
-        Field(
-            min_length=1, description="Countries holding the given mode of perspective."
-        ),
-        UniqueItemsConstraint(),
-    ]
-
-
-class Stacked(BaseModel):
-    """Properties defining feature Z-order, i.e., stacking order."""
-
-    level: Level | None = 0  # type: ignore[assignment]

packages/overture-schema-common/src/overture/schema/common/level.py

@@ -0,0 +1,23 @@
+"""
+Z-order stacking.
+"""
+
+from typing import Annotated, NewType
+
+from pydantic import BaseModel, Field
+
+from overture.schema.system.numeric import int32
+
+Level = NewType(
+    "Level",
+    Annotated[
+        int32,
+        Field(description="Z-order of the feature where 0 is visual level"),
+    ],
+)
+
+
+class Stacked(BaseModel):
+    """Properties defining feature Z-order, i.e., stacking order."""
+
+    level: Level | None = 0  # type: ignore[assignment]

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

@@ -75,7 +75,7 @@
 
 from pydantic import BaseModel, Field
 
-from overture.schema.common.models import Perspectives
+from overture.schema.common.perspectives import Perspectives
 from overture.schema.common.scoping import Scope, scoped
 from overture.schema.system.doc import DocumentedEnum
 from overture.schema.system.model_constraint import no_extra_fields

packages/overture-schema-common/src/overture/schema/common/perspectives.py

@@ -0,0 +1,40 @@
+"""
+Political perspectives.
+"""
+
+from enum import Enum
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+from overture.schema.system.field_constraint import UniqueItemsConstraint
+from overture.schema.system.model_constraint import no_extra_fields
+from overture.schema.system.string import CountryCodeAlpha2
+
+
+class PerspectiveMode(str, Enum):
+    """Perspective mode for disputed names."""
+
+    ACCEPTED_BY = "accepted_by"
+    DISPUTED_BY = "disputed_by"
+
+
+@no_extra_fields
+class Perspectives(BaseModel):
+    """Political perspectives container."""
+
+    # Required
+
+    mode: Annotated[
+        PerspectiveMode,
+        Field(
+            description="Whether the perspective holder accepts or disputes this name."
+        ),
+    ]
+    countries: Annotated[
+        list[CountryCodeAlpha2],
+        Field(
+            min_length=1, description="Countries holding the given mode of perspective."
+        ),
+        UniqueItemsConstraint(),
+    ]

packages/overture-schema-common/src/overture/schema/common/scoping/__init__.py

@@ -17,7 +17,7 @@
 
 >>> from typing import Annotated, Literal
 >>> from pydantic import BaseModel
->>> from overture.schema.common.models import OvertureFeature
+>>> from overture.schema.common.feature import OvertureFeature
 >>> from overture.schema.system.geometric import (
 ...     Geometry,
 ...     GeometryType,
@@ -71,7 +71,7 @@
 
 >>> from typing import Annotated, Literal
 >>> from pydantic import BaseModel
->>> from overture.schema.common.models import OvertureFeature
+>>> from overture.schema.common.feature import OvertureFeature
 >>> from overture.schema.system.geometric import (
 ...     Geometry,
 ...     GeometryType,
@@ -119,7 +119,7 @@
 
 >>> from typing import Annotated, Literal
 >>> from pydantic import BaseModel, Field
->>> from overture.schema.common.models import OvertureFeature
+>>> from overture.schema.common.feature import OvertureFeature
 >>> from overture.schema.system.geometric import (
 ...     Geometry,
 ...     GeometryType,
@@ -212,7 +212,7 @@
 
 >>> from typing import Annotated, Literal
 >>> from pydantic import BaseModel
->>> from overture.schema.common.models import OvertureFeature
+>>> from overture.schema.common.feature import OvertureFeature
 >>> from overture.schema.system.geometric import (
 ...     Geometry,
 ...     GeometryType,

packages/overture-schema-common/src/overture/schema/common/sources.py

@@ -8,8 +8,8 @@
 
 from pydantic import BaseModel, Field
 
+from overture.schema.common.confidence import ConfidenceScore
 from overture.schema.common.scoping import Scope, scoped
-from overture.schema.common.types import ConfidenceScore
 from overture.schema.system.field_constraint import UniqueItemsConstraint
 from overture.schema.system.model_constraint import no_extra_fields
 from overture.schema.system.string import (