overture-schema-common 0.1.1.dev0__tar.gz

overture_schema_common-0.1.1.dev0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: overture-schema-common
+Version: 0.1.1.dev0
+Summary: Common components that are shared across Overture theme schemas
+License-Expression: MIT
+Requires-Dist: overture-schema-system>=0.1.1
+Requires-Dist: pydantic>=2.13.0
+Requires-Dist: shapely>=2.1.1
+Maintainer: Overture Maps Schema Working Group
+Requires-Python: >=3.10
+Project-URL: Homepage, https://overturemaps.org
+Project-URL: Source, https://github.com/OvertureMaps/schema
+Project-URL: Issues, https://github.com/OvertureMaps/schema/issues

overture_schema_common-0.1.1.dev0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["uv_build>=0.11.32,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "overture-schema-common"
+version = "0.1.1.dev0"
+description = "Common components that are shared across Overture theme schemas"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "overture-schema-system>=0.1.1",
+    "pydantic>=2.13.0",
+    "shapely>=2.1.1",
+]
+
+[[project.maintainers]]
+name = "Overture Maps Schema Working Group"
+
+[project.urls]
+Homepage = "https://overturemaps.org"
+Source = "https://github.com/OvertureMaps/schema"
+Issues = "https://github.com/OvertureMaps/schema/issues"
+
+[project.entry-points."overture.tag_providers"]
+overture = "overture.schema.common.tag_providers:overture_provider"
+theme = "overture.schema.common.tag_providers:theme_provider"
+
+[tool.uv.sources.overture-schema-system]
+workspace = true
+
+[tool.uv.build-backend]
+module-name = "overture.schema.common"
+
+[dependency-groups]
+dev = [
+    "deepdiff>=8.6.0",
+    "jsonpath-ng>=1.7.0",
+    "types-pyyaml>=6.0.12.20250516",
+    "types-shapely>=2.1.0.20250710",
+]

overture_schema_common-0.1.1.dev0/pyproject.toml.orig

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["uv_build>=0.11.32,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "overture-schema-common"
+maintainers = [
+    {name = "Overture Maps Schema Working Group"},
+]
+version = "0.1.1.dev0"
+description = "Common components that are shared across Overture theme schemas"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "overture-schema-system>=0.1.1",
+    "pydantic>=2.13.0",
+    "shapely>=2.1.1",
+]
+
+[project.urls]
+Homepage = "https://overturemaps.org"
+Source = "https://github.com/OvertureMaps/schema"
+Issues = "https://github.com/OvertureMaps/schema/issues"
+
+[tool.uv.sources]
+overture-schema-system = { workspace = true }
+
+[tool.uv.build-backend]
+module-name = "overture.schema.common"
+
+[dependency-groups]
+dev = [
+    "deepdiff>=8.6.0",
+    "jsonpath-ng>=1.7.0",
+    "types-pyyaml>=6.0.12.20250516",
+    "types-shapely>=2.1.0.20250710",
+]
+
+[project.entry-points."overture.tag_providers"]
+overture = "overture.schema.common.tag_providers:overture_provider"
+theme = "overture.schema.common.tag_providers:theme_provider"

overture_schema_common-0.1.1.dev0/src/overture/schema/common/__init__.py

@@ -0,0 +1,50 @@
+"""
+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",
+    "perspectives",
+    "scoping",
+    "sources",
+    "ThemeT",
+    "TypeT",
+    "unit",
+]

overture_schema_common-0.1.1.dev0/src/overture/schema/common/cartography.py

@@ -0,0 +1,114 @@
+"""
+Specify cartographic hints for features and fields of features.
+"""
+
+import textwrap
+from typing import Annotated, NewType
+
+from pydantic import BaseModel, Field
+
+from overture.schema.system.model_constraint import no_extra_fields
+from overture.schema.system.numeric import int32
+
+Prominence = NewType(
+    "Prominence",
+    Annotated[
+        int32,
+        Field(
+            ge=1,
+            le=100,
+            description=textwrap.dedent("""
+                Subjective scale of feature significance or importance, with 1 being the least, and
+                100 being the most, significant.
+
+                This value can be used to help drive decisions about how and when to display a
+                feature, and how to treat it relative to neighboring features.
+
+                When populated by Overture, this value is derived from various factors including,
+                but not limited to: feature and subtype, population, and capital status.
+            """).strip(),
+        ),
+    ],
+)
+
+MinZoom = NewType(
+    "MinZoom",
+    Annotated[
+        int32,
+        Field(
+            ge=0,
+            le=23,
+            description=textwrap.dedent("""
+                Recommended minimum tile zoom level in which this feature should be displayed.
+
+                It is recommended that the feature be hidden at zoom levels below this value.
+
+                Zoom levels follow the Slippy Maps convention, documented in the following
+                references:
+                - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames
+                - https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection
+                """).strip(),
+        ),
+    ],
+)
+
+MaxZoom = NewType(
+    "MaxZoom",
+    Annotated[
+        int32,
+        Field(
+            ge=0,
+            le=23,
+            description=textwrap.dedent("""
+                Recommended maximum tile zoom level in which this feature should be displayed.
+
+                It is recommended that the feature be hidden at zoom levels above this value.
+
+                Zoom levels follow the Slippy Maps convention, documented in the following
+                references:
+                - https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames
+                - https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection
+            """).strip(),
+        ),
+    ],
+)
+
+SortKey = NewType(
+    "SortKey",
+    Annotated[
+        int32,
+        Field(
+            description=textwrap.dedent("""
+                Integer indicating the recommended order in which to draw features.
+
+                Features with a lower number should be drawn "in front" of features with a higher
+                number.
+            """).strip(),
+        ),
+    ],
+)
+
+
+@no_extra_fields
+class CartographicHints(BaseModel):
+    """Cartographic hints for optimal use of Overture features in map-making."""
+
+    # Optional
+
+    prominence: Prominence | None = None
+    min_zoom: MinZoom | None = None
+    max_zoom: MaxZoom | None = None
+    sort_key: SortKey | None = None
+
+
+class CartographicallyHinted(BaseModel):
+    """
+    Properties for adding cartographic hints to a model.
+    """
+
+    cartography: Annotated[
+        CartographicHints | None,
+        Field(
+            description="Cartographic hints useful when including the feature in maps"
+        ),
+    ] = None

overture_schema_common-0.1.1.dev0/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),
+    ],
+)

overture_schema_common-0.1.1.dev0/src/overture/schema/common/feature.py

@@ -0,0 +1,103 @@
+"""
+The Overture feature, an Overture-specific refinement of the base `Feature` type defined in the
+system package.
+"""
+
+import textwrap
+from typing import Annotated, Generic, NewType, TypeVar
+
+from pydantic import (
+    ConfigDict,
+    Field,
+    GetJsonSchemaHandler,
+    model_validator,
+)
+from pydantic.json_schema import JsonSchemaValue
+from pydantic_core import core_schema
+from typing_extensions import Self
+
+from overture.schema.system.feature import Feature
+from overture.schema.system.numeric import int32
+from overture.schema.system.ref import Id, Identified
+
+from .sources import Sources
+
+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]):
+    """
+    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
+    type: TypeT
+    # Superclass `Feature` provides `geometry` and `bbox`.
+    version: FeatureVersion
+
+    # Optional
+
+    sources: Sources | None = None
+
+    @model_validator(mode="after")
+    def __validate_ext_fields__(self) -> Self:
+        extra = self.model_extra
+        invalid_extra_fields = (
+            [f for f in extra.keys() if not f.startswith("ext_")] if extra else ()
+        )
+        if invalid_extra_fields:
+            maybe_plural = "s" if len(invalid_extra_fields) > 1 else ""
+            raise ValueError(
+                f"invalid extra field name{maybe_plural}: {', '.join(invalid_extra_fields)} "
+                f"(extra fields are temporarily allowed, but only if their names start with 'ext_', "
+                f"but all extra field name support in {self.__class__.__name__} is on a deprecation path "
+                f"and will be removed)"
+            )
+        return self
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls,
+        schema: core_schema.CoreSchema,
+        handler: GetJsonSchemaHandler,
+    ) -> JsonSchemaValue:
+        # Get the main Feature JSON schema.
+        json_schema = super().__get_pydantic_json_schema__(schema, handler)
+
+        # Explicitly allow `ext_*` properties, but no other properties, in the properties object.
+        # This feature only exists to get to initial parity between the hand-written JSON Schema and
+        # the Pydantic port. Once Pydantic is the primary, it will be deprecated.
+        properties_object_schema = json_schema["properties"]["properties"]
+        properties_object_schema["patternProperties"] = {
+            "^ext_.*$": {
+                "description": textwrap.dedent("""
+                    Additional top-level properties are allowed if prefixed by `ext_`.
+
+                    This feature is on a deprecation path and will be removed once the schema is
+                    fully migrated to Pydantic.
+                """).strip(),
+            }
+        }
+        properties_object_schema["additionalProperties"] = False
+
+        return json_schema

overture_schema_common-0.1.1.dev0/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]

overture_schema_common-0.1.1.dev0/src/overture/schema/common/names.py

@@ -0,0 +1,230 @@
+"""
+Names for features and their child attributes.
+
+This module includes all Overture's standard naming types. It supports multi-language names,
+multiple name variants, and naming rules for specifying conditional or partial names to things.
+
+Examples
+--------
+Create a feature type that can have a name:
+
+>>> from typing import Literal
+>>> from overture.schema.common import OvertureFeature
+>>> from overture.schema.system.geometric import Geometry
+>>> class MyFeature(OvertureFeature[Literal["mytheme"], Literal["mytype"]], Named):
+...     pass
+...
+>>> my_feature = MyFeature(
+...    id='12345678-1234-5678-9abc-123456789012',
+...    geometry=Geometry.from_wkt('POINT(0 0)'),
+...    theme='mytheme',
+...    type='mytype',
+...    version=1,
+...    names=Names(primary='my feature primary name')
+... )
+
+Create an arbitrary Pydantic model that can have a name:
+
+>>> from pydantic import BaseModel
+>>> from overture.schema.system.model_constraint import no_extra_fields
+>>> @no_extra_fields
+... class MyModel(Named):
+...     myfield: int
+...
+>>> MyModel(names=Names(primary='foo'), myfield=42)
+MyModel(names=Names(primary='foo', common=None, rules=None), myfield=42)
+
+Create a simple names structure with names in multiple languages:
+
+>>> names = Names(
+...     primary='Le Léman',
+...     common={
+...         'de': 'Genfersee',
+...         'en': 'Lake Geneva',
+...         'fr': 'Le Léman',
+...     }
+... )
+
+Create a name structure with official, alternate, and short names:
+
+>>> names = Names(
+...     primary='City of New York',
+...     rules=[
+...         NameRule(value='New York', variant='official', language='en'),
+...         NameRule(value='New York City', variant='alternate', language='en'),
+...         NameRule(value='The Big Apple', variant='alternate', language='en'),
+...         NameRule(value='NYC', variant='alternate'),
+...     ]
+... )
+
+Create a name structure for a street where the name changes based on the side of the street.
+
+>>> from overture.schema.common.scoping import Side
+>>> names = Names(
+...     primary='Fir St',
+...     rules=[
+...         NameRule(value='2 Ave', variant='common', between=[0, 0.3], side=Side.LEFT),
+...         NameRule(value='Fir St', variant='common', between=[0.3, 1], side=Side.LEFT),
+...         NameRule(value='Fir St', variant='common', side=Side.RIGHT),
+...     ]
+... )
+"""
+
+import textwrap
+from typing import Annotated, NewType
+
+from pydantic import BaseModel, Field
+
+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
+from overture.schema.system.string import (
+    LanguageTag,
+    StrippedString,
+)
+
+CommonNames = NewType(
+    "CommonNames",
+    Annotated[
+        dict[
+            Annotated[
+                LanguageTag,
+                Field(
+                    description=textwrap.dedent("""
+                        A mapping from language to the most commonly used or recognized name in that
+                        language.
+
+                        Each entry consists of a key that is an IETF BCP 47 language tag; and a
+                        value that reflects the common name in the language represented by the key's
+                        language tag.
+
+                        The validating regular expression for this property follows the pattern
+                        described in https://www.rfc-editor.org/rfc/bcp/bcp47.txt with the exception
+                        that private use tags are not supported.
+                    """).strip(),
+                ),
+            ],
+            StrippedString,
+        ],
+        Field(json_schema_extra={"additionalProperties": False}),
+    ],
+)
+CommonNames.__doc__ = """A mapping from language to the most commonly used or recognized name in that language."""
+
+
+class NameVariant(str, DocumentedEnum):
+    """
+    Name variant used in a `NameRule`.
+    """
+
+    COMMON = (
+        "common",
+        textwrap.dedent("""
+            The most commonly used or recognized name for a feature in the specified language.
+
+            In a `Names` value, most common names will appear in the `Names.common` field and will
+            not need to be specified as `NameRule` values in `Names.rules`. This member of the
+            enumeration should only be used to construct a `NameRule` if the common name needs to
+            be scoped in some way and therefore cannot be accurately represented in `CommonNames`.
+        """).strip(),
+    )
+    OFFICIAL = (
+        "official",
+        textwrap.dedent("""
+            The legally or administratively recognized name, often used by government agencies or
+            official documents.
+        """).strip(),
+    )
+    ALTERNATE = (
+        "alternate",
+        textwrap.dedent("""
+            An alternative name, which may be a historical name, a local colloquial name, or some
+            other well-known name is not the common name.
+        """).strip(),
+    )
+    SHORT = (
+        "short",
+        textwrap.dedent("""
+            An abbreviated or shortened version of the name, which may be an acronym or some other
+            commonly-used short form. An example is "NYC" for New York City.
+        """).strip(),
+    )
+
+
+@no_extra_fields
+@scoped(Scope.GEOMETRIC_RANGE, Scope.SIDE)
+class NameRule(BaseModel):
+    """
+    A rule that can be evaluated to determine the name in advanced scenarios.
+
+    Name rules are used for cases where the primary name is not sufficient; the common name is not
+    the right fit for the use case and another variant is needed; or where the name only applies in
+    certain specific circumstances.
+
+    Examples might include:
+    - An official, alternate, or short name.
+    - A name that only applies to part of a linear path like a road segment (geometric range
+      scoping).
+    - A name that only applies to the left or right side of a linear path like a road segment (side
+      scoping).
+    - A name that is only accepted by some political perspectives.
+    """
+
+    # Required
+
+    value: Annotated[
+        StrippedString, Field(description="The actual name value.", min_length=1)
+    ]
+    variant: NameVariant = Field(description="The name variant for this name rule.")
+
+    # Optional
+
+    language: Annotated[
+        LanguageTag | None,
+        Field(
+            description=textwrap.dedent("""
+                The language in which the name `value` is specified, if known, as an IETF BCP 47
+                language tag.
+            """).strip()
+        ),
+    ] = None
+    perspectives: (
+        Annotated[
+            Perspectives,
+            Field(
+                description="Political perspectives from which a named feature is viewed."
+            ),
+        ]
+        | None
+    ) = None
+
+
+@no_extra_fields
+class Names(BaseModel):
+    """Multilingual names container."""
+
+    # Required
+
+    primary: Annotated[
+        StrippedString, Field(min_length=1, description="The most commonly used name.")
+    ]
+
+    # Optional
+
+    common: CommonNames | None = None
+    rules: Annotated[
+        list[NameRule] | None,
+        Field(
+            description="Rules for names that cannot be specified in the simple common names property. These rules can cover other name variants such as official, alternate, and short; and they can optionally include geometric scoping (linear referencing) and side-of-road scoping for complex cases.",
+        ),
+    ] = None
+
+
+class Named(BaseModel):
+    """Properties defining the names of a model."""
+
+    names: Annotated[
+        Names | None,
+        Field(description="All known names by which the feature is called"),
+    ] = None

overture_schema_common-0.1.1.dev0/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(),
+    ]