overture-schema-theme-divisions 0.1.1.dev0__tar.gz

overture_schema_theme_divisions-0.1.1.dev0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: overture-schema-theme-divisions
+Version: 0.1.1.dev0
+Summary: Overture Maps divisions theme shared structures, division, division area and division boundary types
+License-Expression: MIT
+Requires-Dist: overture-schema-common>=0.1.1
+Requires-Dist: overture-schema-system>=0.1.1
+Requires-Dist: pydantic>=2.13.0
+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
+Description-Content-Type: text/markdown
+
+# Overture Schema Divisions Theme
+
+Shared structures and validation logic for Overture Maps divisions theme.
+Contains common place types, administrative hierarchy utilities, and validation patterns.

overture_schema_theme_divisions-0.1.1.dev0/README.md

@@ -0,0 +1,4 @@
+# Overture Schema Divisions Theme
+
+Shared structures and validation logic for Overture Maps divisions theme.
+Contains common place types, administrative hierarchy utilities, and validation patterns.

overture_schema_theme_divisions-0.1.1.dev0/pyproject.toml

@@ -0,0 +1,164 @@
+[project]
+dependencies = [
+    "overture-schema-common>=0.1.1",
+    "overture-schema-system>=0.1.1",
+    "pydantic>=2.13.0",
+]
+description = "Overture Maps divisions theme shared structures, division, division area and division boundary types"
+version = "0.1.1.dev0"
+license = "MIT"
+name = "overture-schema-theme-divisions"
+readme = "README.md"
+requires-python = ">=3.10"
+
+[[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.models"]
+division = "overture.schema.divisions:Division"
+division_area = "overture.schema.divisions:DivisionArea"
+division_boundary = "overture.schema.divisions:DivisionBoundary"
+
+[project.entry-points.pytest11]
+overture_baselines = "overture.schema.system.testing.plugin"
+
+[tool.uv.sources.overture-schema-common]
+workspace = true
+
+[tool.uv.sources.overture-schema-system]
+workspace = true
+
+[tool.uv.build-backend]
+module-name = "overture.schema.divisions"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.13"]
+build-backend = "uv_build"
+
+[[examples.Division]]
+admin_level = 2
+capital_division_ids = ["958c67d3-868a-482d-9dd8-1c65b0c1a9e8"]
+country = "US"
+geometry = "POINT (-159.4945109 22.0557204)"
+hierarchies = [[
+    { division_id = "f39eb4af-5206-481b-b19e-bd784ded3f05", subtype = "country", name = "United States" },
+    { division_id = "a2a08395-e968-4be5-bdd7-7f63db8c2165", subtype = "region", name = "Hawaii" },
+    { division_id = "c9b8adc9-4639-4392-8efe-8401eeb19929", subtype = "county", name = "Kauaʻi County" },
+]]
+id = "c9b8adc9-4639-4392-8efe-8401eeb19929"
+parent_division_id = "a2a08395-e968-4be5-bdd7-7f63db8c2165"
+population = 71735
+region = "US-HI"
+subtype = "county"
+theme = "divisions"
+type = "division"
+version = 5
+wikidata = "Q111517"
+
+[examples.Division.bbox]
+xmax = -159.4945068359375
+xmin = -159.49453735351563
+ymax = 22.055721282958984
+ymin = 22.05571746826172
+
+[[examples.Division.sources]]
+dataset = "OpenStreetMap"
+license = "ODbL-1.0"
+property = ""
+record_id = "r166560@15"
+update_time = "2025-08-16T14:25:55Z"
+
+[examples.Division.names]
+primary = "Kauaʻi County"
+
+[examples.Division.names.common]
+haw = "kalana Kauaʻi"
+
+[[examples.Division.names.rules]]
+value = "Kauai County"
+variant = "alternate"
+
+[examples.Division.local_type]
+en = "county"
+
+[[examples.DivisionArea]]
+admin_level = 2
+class = "land"
+country = "US"
+division_id = "c9b8adc9-4639-4392-8efe-8401eeb19929"
+geometry = "MULTIPOLYGON (((-160.5408313 21.6535414, -160.544491 21.6514764, -160.5369253 21.6495783, -160.5408313 21.6535414)), ((-160.0921364 22.005401, -160.1251483 21.9547066, -160.2260792 21.8900136, -160.2470031 21.841157, -160.2339532 21.7921394, -160.2022486 21.7794359, -160.1588705 21.864646, -160.0737812 21.8957962, -160.0826438 21.9302968, -160.05025 21.9848306, -160.0921364 22.005401)), ((-160.0881165 22.0243325, -160.1005193 22.0287469, -160.1026828 22.0166419, -160.0881165 22.0243325)), ((-159.7508422 21.9762242, -159.6679712 21.9531973, -159.604686 21.8923573, -159.5913126 21.9041661, -159.443465 21.8684403, -159.3461084 21.9373297, -159.3624768 21.952083, -159.3309486 21.9590284, -159.3357151 22.0450997, -159.2964497 22.1053479, -159.2926896 22.1434001, -159.335189 22.2040351, -159.4024533 22.2327054, -159.4282799 22.2164343, -159.4864746 22.2298148, -159.5060386 22.2031539, -159.5808829 22.2237075, -159.7228708 22.1497995, -159.7443872 22.099889, -159.7826601 22.0669155, -159.7849578 22.0149525, -159.7508422 21.9762242)))"
+id = "109cfa53-bb13-4e37-aeb0-14f9a08c737d"
+is_land = true
+is_territorial = false
+region = "US-HI"
+subtype = "county"
+theme = "divisions"
+type = "division_area"
+version = 7
+
+[examples.DivisionArea.bbox]
+xmax = -159.29266357421875
+xmin = -160.54449462890625
+ymax = 22.23270606994629
+ymin = 21.649578094482422
+
+[[examples.DivisionArea.sources]]
+dataset = "OpenStreetMap"
+license = "ODbL-1.0"
+property = ""
+record_id = "r166560@15"
+update_time = "2025-08-16T14:25:55Z"
+
+[examples.DivisionArea.names]
+primary = "Kauaʻi County"
+
+[examples.DivisionArea.names.common]
+haw = "kalana Kauaʻi"
+
+[[examples.DivisionArea.names.rules]]
+value = "Kauai County"
+variant = "alternate"
+
+[[examples.DivisionBoundary]]
+admin_level = 2
+class = "land"
+country = "US"
+division_ids = [
+    "a546a5ef-ba43-44ce-a7c3-1999b005b20f",
+    "0554d43c-de68-433c-9a6c-db58161c8b4a",
+]
+geometry = "LINESTRING (-157.0195397035514 21.183903480793326, -157.0201257 21.180663, -157.0084983 21.1786971, -157.0053877 21.1769627, -157.0060747 21.1738084, -157.0003054 21.1722773, -156.9809248 21.1746356, -156.9710241 21.172431, -156.9670723 21.1613703, -156.9550334 21.1531141, -156.9552315 21.1564667, -156.9607515 21.1621168, -156.9584334 21.162083, -156.9598705 21.1636745, -156.958371 21.1708964, -156.9602176 21.1762534, -156.9577173 21.1760764, -156.9556416 21.1715505, -156.9554893 21.157221, -156.9528625 21.1523977, -156.9442066 21.1504038, -156.9389218 21.1568278, -156.938089 21.1530661, -156.9348977 21.15157, -156.9283241 21.1419085, -156.9262384 21.1360023, -156.9186457 21.1279636, -156.9124605 21.1262614, -156.8975854 21.1285336, -156.8979892 21.1337635, -156.8958138 21.1376515, -156.8970853 21.1421243, -156.8929598 21.1451006, -156.8928438 21.1467406, -156.897116 21.1457141, -156.9036748 21.1485179, -156.9059125 21.1527496, -156.910528 21.1563906, -156.917332 21.1590391, -156.9140393 21.1691869)"
+id = "321ed3ec-23c2-376e-a4fd-0df484cb99ca"
+is_disputed = false
+is_land = true
+is_territorial = false
+region = "US-HI"
+subtype = "county"
+theme = "divisions"
+type = "division_boundary"
+version = 2
+
+[examples.DivisionBoundary.bbox]
+xmax = -156.89283752441406
+xmin = -157.02012634277344
+ymax = 21.18390655517578
+ymin = 21.12626075744629
+
+[[examples.DivisionBoundary.sources]]
+dataset = "OpenStreetMap"
+license = "ODbL-1.0"
+property = ""
+record_id = "r166564@15"
+update_time = "2025-02-21T16:35:23Z"
+
+[[examples.DivisionBoundary.sources]]
+dataset = "OpenStreetMap"
+license = "ODbL-1.0"
+property = ""
+record_id = "r166561@26"
+update_time = "2025-08-16T14:01:24Z"

overture_schema_theme_divisions-0.1.1.dev0/pyproject.toml.orig

@@ -0,0 +1,164 @@
+[project]
+maintainers = [
+    { name = "Overture Maps Schema Working Group" },
+]
+dependencies = [
+    "overture-schema-common>=0.1.1",
+    "overture-schema-system>=0.1.1",
+    "pydantic>=2.13.0",
+]
+description = "Overture Maps divisions theme shared structures, division, division area and division boundary types"
+version = "0.1.1.dev0"
+license = "MIT"
+name = "overture-schema-theme-divisions"
+readme = "README.md"
+requires-python = ">=3.10"
+
+[project.urls]
+Homepage = "https://overturemaps.org"
+Source = "https://github.com/OvertureMaps/schema"
+Issues = "https://github.com/OvertureMaps/schema/issues"
+
+[tool.uv.sources]
+overture-schema-common = { workspace = true }
+overture-schema-system = { workspace = true }
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "overture.schema.divisions"
+
+[project.entry-points."overture.models"]
+division = "overture.schema.divisions:Division"
+division_area = "overture.schema.divisions:DivisionArea"
+division_boundary = "overture.schema.divisions:DivisionBoundary"
+
+[project.entry-points.pytest11]
+overture_baselines = "overture.schema.system.testing.plugin"
+
+[[examples.Division]]
+admin_level = 2
+capital_division_ids = ["958c67d3-868a-482d-9dd8-1c65b0c1a9e8"]
+country = "US"
+geometry = "POINT (-159.4945109 22.0557204)"
+hierarchies = [
+    [
+        { division_id = "f39eb4af-5206-481b-b19e-bd784ded3f05", subtype = "country", name = "United States" },
+        { division_id = "a2a08395-e968-4be5-bdd7-7f63db8c2165", subtype = "region", name = "Hawaii" },
+        { division_id = "c9b8adc9-4639-4392-8efe-8401eeb19929", subtype = "county", name = "Kauaʻi County" },
+    ],
+]
+id = "c9b8adc9-4639-4392-8efe-8401eeb19929"
+parent_division_id = "a2a08395-e968-4be5-bdd7-7f63db8c2165"
+population = 71735
+region = "US-HI"
+subtype = "county"
+theme = "divisions"
+type = "division"
+version = 5
+wikidata = "Q111517"
+
+[examples.Division.bbox]
+xmax = -159.4945068359375
+xmin = -159.49453735351562
+ymax = 22.055721282958984
+ymin = 22.05571746826172
+
+[[examples.Division.sources]]
+dataset = "OpenStreetMap"
+license = "ODbL-1.0"
+property = ""
+record_id = "r166560@15"
+update_time = "2025-08-16T14:25:55Z"
+
+[examples.Division.names]
+primary = "Kauaʻi County"
+
+[examples.Division.names.common]
+haw = "kalana Kauaʻi"
+
+[[examples.Division.names.rules]]
+value = "Kauai County"
+variant = "alternate"
+
+[examples.Division.local_type]
+en = "county"
+
+[[examples.DivisionArea]]
+admin_level = 2
+class = "land"
+country = "US"
+division_id = "c9b8adc9-4639-4392-8efe-8401eeb19929"
+geometry = "MULTIPOLYGON (((-160.5408313 21.6535414, -160.544491 21.6514764, -160.5369253 21.6495783, -160.5408313 21.6535414)), ((-160.0921364 22.005401, -160.1251483 21.9547066, -160.2260792 21.8900136, -160.2470031 21.841157, -160.2339532 21.7921394, -160.2022486 21.7794359, -160.1588705 21.864646, -160.0737812 21.8957962, -160.0826438 21.9302968, -160.05025 21.9848306, -160.0921364 22.005401)), ((-160.0881165 22.0243325, -160.1005193 22.0287469, -160.1026828 22.0166419, -160.0881165 22.0243325)), ((-159.7508422 21.9762242, -159.6679712 21.9531973, -159.604686 21.8923573, -159.5913126 21.9041661, -159.443465 21.8684403, -159.3461084 21.9373297, -159.3624768 21.952083, -159.3309486 21.9590284, -159.3357151 22.0450997, -159.2964497 22.1053479, -159.2926896 22.1434001, -159.335189 22.2040351, -159.4024533 22.2327054, -159.4282799 22.2164343, -159.4864746 22.2298148, -159.5060386 22.2031539, -159.5808829 22.2237075, -159.7228708 22.1497995, -159.7443872 22.099889, -159.7826601 22.0669155, -159.7849578 22.0149525, -159.7508422 21.9762242)))"
+id = "109cfa53-bb13-4e37-aeb0-14f9a08c737d"
+is_land = true
+is_territorial = false
+region = "US-HI"
+subtype = "county"
+theme = "divisions"
+type = "division_area"
+version = 7
+
+[examples.DivisionArea.bbox]
+xmax = -159.29266357421875
+xmin = -160.54449462890625
+ymax = 22.23270606994629
+ymin = 21.649578094482422
+
+[[examples.DivisionArea.sources]]
+dataset = "OpenStreetMap"
+license = "ODbL-1.0"
+property = ""
+record_id = "r166560@15"
+update_time = "2025-08-16T14:25:55Z"
+
+[examples.DivisionArea.names]
+primary = "Kauaʻi County"
+
+[examples.DivisionArea.names.common]
+haw = "kalana Kauaʻi"
+
+[[examples.DivisionArea.names.rules]]
+value = "Kauai County"
+variant = "alternate"
+
+[[examples.DivisionBoundary]]
+admin_level = 2
+class = "land"
+country = "US"
+division_ids = [
+    "a546a5ef-ba43-44ce-a7c3-1999b005b20f",
+    "0554d43c-de68-433c-9a6c-db58161c8b4a",
+]
+geometry = "LINESTRING (-157.0195397035514 21.183903480793326, -157.0201257 21.180663, -157.0084983 21.1786971, -157.0053877 21.1769627, -157.0060747 21.1738084, -157.0003054 21.1722773, -156.9809248 21.1746356, -156.9710241 21.172431, -156.9670723 21.1613703, -156.9550334 21.1531141, -156.9552315 21.1564667, -156.9607515 21.1621168, -156.9584334 21.162083, -156.9598705 21.1636745, -156.958371 21.1708964, -156.9602176 21.1762534, -156.9577173 21.1760764, -156.9556416 21.1715505, -156.9554893 21.157221, -156.9528625 21.1523977, -156.9442066 21.1504038, -156.9389218 21.1568278, -156.938089 21.1530661, -156.9348977 21.15157, -156.9283241 21.1419085, -156.9262384 21.1360023, -156.9186457 21.1279636, -156.9124605 21.1262614, -156.8975854 21.1285336, -156.8979892 21.1337635, -156.8958138 21.1376515, -156.8970853 21.1421243, -156.8929598 21.1451006, -156.8928438 21.1467406, -156.897116 21.1457141, -156.9036748 21.1485179, -156.9059125 21.1527496, -156.910528 21.1563906, -156.917332 21.1590391, -156.9140393 21.1691869)"
+id = "321ed3ec-23c2-376e-a4fd-0df484cb99ca"
+is_disputed = false
+is_land = true
+is_territorial = false
+region = "US-HI"
+subtype = "county"
+theme = "divisions"
+type = "division_boundary"
+version = 2
+
+[examples.DivisionBoundary.bbox]
+xmax = -156.89283752441406
+xmin = -157.02012634277344
+ymax = 21.18390655517578
+ymin = 21.12626075744629
+
+[[examples.DivisionBoundary.sources]]
+dataset = "OpenStreetMap"
+license = "ODbL-1.0"
+property = ""
+record_id = "r166564@15"
+update_time = "2025-02-21T16:35:23Z"
+
+[[examples.DivisionBoundary.sources]]
+dataset = "OpenStreetMap"
+license = "ODbL-1.0"
+property = ""
+record_id = "r166561@26"
+update_time = "2025-08-16T14:01:24Z"

overture_schema_theme_divisions-0.1.1.dev0/src/overture/schema/divisions/__init__.py

@@ -0,0 +1,28 @@
+"""Divisions theme.
+
+Administrative and political divisions representing human settlements at various scales,
+with point, area, and boundary geometries.
+"""
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+
+from ._common import AdminLevel, DivisionSubtype
+from .division import CapitalOfDivisionItem, Division, DivisionClass, Norms
+from .division_area import AreaClass, DivisionArea
+from .division_boundary import BoundaryClass, 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",
+    "DivisionBoundary",
+    "DivisionClass",
+    "DivisionSubtype",
+    "Norms",
+]

overture_schema_theme_divisions-0.1.1.dev0/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.numeric 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)

overture_schema_theme_divisions-0.1.1.dev0/src/overture/schema/divisions/division.py

@@ -0,0 +1,418 @@
+"""
+The `Division` feature type model and supporting types.
+"""
+
+from __future__ import annotations
+
+import textwrap
+from typing import Annotated, Literal, NewType
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from overture.schema.common import (
+    OvertureFeature,
+)
+from overture.schema.common.cartography import CartographicallyHinted
+from overture.schema.common.names import CommonNames, Named, Names
+from overture.schema.common.perspectives import (
+    Perspectives,
+)
+from overture.schema.common.scoping.side import Side
+from overture.schema.system.doc import DocumentedEnum
+from overture.schema.system.field_constraint import (
+    UniqueItemsConstraint,
+)
+from overture.schema.system.geometric import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
+from overture.schema.system.model_constraint import (
+    FieldEqCondition,
+    forbid_if,
+    no_extra_fields,
+    require_if,
+)
+from overture.schema.system.numeric import int32
+from overture.schema.system.ref import Id, Reference, Relationship
+from overture.schema.system.string import (
+    CountryCodeAlpha2,
+    RegionCode,
+    StrippedString,
+    WikidataId,
+)
+
+from ._common import (
+    IS_COUNTRY,
+    AdminLevel,
+    DivisionSubtype,
+)
+
+
+@no_extra_fields
+class Norms(BaseModel):
+    """Local norms and standards."""
+
+    # Optional
+
+    driving_side: Annotated[
+        Side | None,
+        Field(
+            description="Side of the road on which vehicles drive in the division.",
+        ),
+    ] = None
+
+
+class DivisionClass(str, DocumentedEnum):
+    """
+    Further classification of a division that is more specific than its `subtype`.
+
+    A division's `class` adds detail to the broad classification found in `DivisionSubtype`.
+    """
+
+    MEGACITY = (
+        "megacity",
+        textwrap.dedent("""
+            A very large city or metropolitan area, typically having a population of 10 million or
+            more. Example: Tokyo, Japan.
+        """).strip(),
+    )
+
+    CITY = (
+        "city",
+        "A large, permanent human settlement. Example: Guadalajara, Mexico.",
+    )
+
+    TOWN = (
+        "town",
+        textwrap.dedent("""
+            A medium-sized permanent human settlement that is smaller than a city, but larger than a
+            village. Example: Walldürn, Germany.
+        """).strip(),
+    )
+
+    VILLAGE = (
+        "village",
+        textwrap.dedent("""
+            A smallish permanent human settlement that is smaller than a town, but larger than a
+            hamlet. Example: Wadi El Karm, Lebanon.
+        """).strip(),
+    )
+
+    HAMLET = (
+        "hamlet",
+        "A very small, isolated human settlement in a rural area. Example: Tjarnabyggð, Iceland.",
+    )
+
+
+@no_extra_fields
+class CapitalOfDivisionItem(BaseModel):
+    """A division of which the owning division is the capital, together with its subtype."""
+
+    model_config = ConfigDict(frozen=True)
+
+    # Required
+
+    division_id: Annotated[
+        Id,
+        Field(description="ID of the division whose capital is the current division."),
+        Reference(Relationship.HIERARCHY, Division, role="capital_of"),
+    ]
+    subtype: DivisionSubtype
+
+
+@no_extra_fields
+class HierarchyItem(BaseModel):
+    """One division in a hierarchy."""
+
+    model_config = ConfigDict(frozen=True)
+
+    # Required
+
+    division_id: Annotated[
+        Id,
+        Field(
+            description=textwrap.dedent("""
+            ID of a division that is an ancestor of the current division.
+
+            In the context of division hierarchies, the ancestor divisions of a division include
+            the division itself, and any other division that is an ancestor of the division's parent.
+        """).strip()
+        ),
+        Reference(Relationship.HIERARCHY, Division, role="descendant_of"),
+    ]
+    subtype: DivisionSubtype
+    name: Annotated[
+        StrippedString, Field(min_length=1, description="Primary name of the division")
+    ]
+
+
+Hierarchy = NewType(
+    "Hierarchy",
+    Annotated[
+        list[HierarchyItem],
+        Field(
+            min_length=1,
+            description=textwrap.dedent("""
+                A hierarchy of divisions, with the first entry being a country; each subsequent
+                entry, if any, being a division that is a direct child of the previous entry; and
+                the last entry representing the division that contains the hierarchy.
+
+                For example, a hierarchy for the United States is simply [United States]. A
+                hierarchy for the U.S. state of New Hampshire would be
+                [United States, New Hampshire], and a hierarchy for the city of Concord, NH would be
+                [United States, New Hampshire, Merrimack County, Concord].
+            """).strip(),
+        ),
+        UniqueItemsConstraint(),
+    ],
+)
+
+
+@forbid_if(["parent_division_id"], IS_COUNTRY)
+@require_if(["parent_division_id"], ~IS_COUNTRY)
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.COUNTRY))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.DEPENDENCY))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.MACROREGION))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.REGION))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.MACROCOUNTY))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.COUNTY))
+class Division(
+    OvertureFeature[Literal["divisions"], Literal["division"]],
+    Named,
+    CartographicallyHinted,
+):
+    """
+    Divisions are recognized official or non-official organizations of people as seen from a given
+    political perspective.
+
+    Examples include countries, provinces, cities, towns, neighborhoods, etc.
+    """
+
+    model_config = ConfigDict(title="division")
+
+    # Core
+    geometry: Annotated[
+        Geometry,
+        GeometryTypeConstraint(GeometryType.POINT),
+        Field(
+            description=textwrap.dedent("""
+                Approximate location of a position commonly associated with the real-world entity
+                modeled by the division feature.
+            """).strip(),
+        ),
+    ]
+
+    # Required
+
+    names: Annotated[
+        Names, Field(description="All known names by which the division is called")
+    ]
+    subtype: Annotated[
+        DivisionSubtype,
+        Field(
+            description=textwrap.dedent("""
+                A broad classification of the division (e.g., country, region, locality, etc.).
+            """).strip()
+        ),
+    ]
+    country: Annotated[
+        CountryCodeAlpha2,
+        Field(
+            description=textwrap.dedent("""
+                ISO 3166-1 alpha-2 country code of the country or country-like entity, that this
+                division represents or belongs to.
+
+                If the entity this division represents has a country code, the country property
+                contains it. If it does not, the country property contains the country code of the
+                first division encountered by traversing the parent_division_id chain to the root.
+
+                For example:
+                - The country value for the United States is 'US'
+                - The country value for New York City is 'US'
+                - The country value for Puerto Rico, a dependency of the US, is 'PR'.
+                - The country value for San Juan, Puerto Rico is 'PR'.
+
+                If an entity has an internationally-recognized ISO 3166-1 alpha-2 country code, it
+                should always be used. In cases where the schema requires the code but no
+                internationally-recognized code is available, a synthetic code may be used provided
+                it does not conflict with any internationally-recognized codes.
+            """).strip(),
+        ),
+    ]
+    hierarchies: Annotated[
+        list[Hierarchy],
+        Field(
+            min_length=1,
+            description=textwrap.dedent("""
+                Hierarchies in which this division participates.
+
+                Every division participates in at least one hierarchy. Most participate in only one.
+                Some divisions may participate in more than one hierarchy, for example if they are
+                claimed by different parent divisions from different political perspectives; or if
+                there are other real-world reasons why the division or one of its ancestors has
+                multiple parents.
+
+                The first hierarchy in the list is the default hierarchy, and the second-to-last
+                entry in the default hierarchy (if there is such an entry) always corresponds to the
+                `parent_division_id` property. The ordering of hierarchies after the first one is
+                arbitrary.
+            """).strip(),
+        ),
+        UniqueItemsConstraint(),
+    ]
+    parent_division_id: Annotated[
+        Id | None,
+        Field(
+            description=textwrap.dedent("""
+                Division ID of this division's parent division.
+
+                Not allowed for top-level divisions (countries) and required for all other
+                divisions.
+
+                The default parent division is the parent division as seen from the default
+                political perspective, if there is one, and is otherwise chosen somewhat
+                arbitrarily. The hierarchies property can be used to inspect the exhaustive list of
+                parent divisions.
+        """).strip()
+        ),
+        Reference(Relationship.HIERARCHY, Division, role="child_of"),
+    ] = None
+    admin_level: AdminLevel | None = None
+
+    # Optional
+
+    class_: Annotated[
+        DivisionClass | None,
+        Field(
+            alias="class",
+            description=textwrap.dedent("""
+                A more specific classification of the division than is provided by `subtype`.
+            """).strip(),
+        ),
+    ] = None
+    local_type: Annotated[
+        CommonNames | None,
+        Field(
+            description=textwrap.dedent("""
+                Local name for the subtype property, optionally localized.
+
+                For example, the Canadian province of Quebec has the subtype `"region"`, but in the
+                local administrative hierarchy it is referred to as a province. Similarly, the
+                Canadian Yukon territory also has subtype `"region"`, but is locally called a
+                territory.
+
+                This property is localized using a standard Overture names structure. So for
+                example, in Switzerland the top-level administrative subdivision corresponding to
+                subtype 'region' is the canton, which may be translated in each of Switzerland's
+                official languages as, 'canton' in French, 'kanton' in German, 'cantone' in Italian,
+                and 'chantun' in Romansh.
+            """).strip(),
+        ),
+    ] = None
+    region: Annotated[
+        RegionCode | None,
+        Field(
+            description=textwrap.dedent("""
+                ISO 3166-2 principal subdivision code of the subdivision-like entity this division
+                represents or belongs to.
+
+                If the entity this division represents has a principal subdivision code, the region
+                property contains it. If it does not, the region property contains the principal
+                subdivision code of the first division encountered by traversing the
+                `parent_division_id` chain to the root.
+
+                For example:
+                - The region value for the United States is omitted.
+                - The region value for the U.S. state of New York is 'US-NY'.
+                - The region value for New York City is 'US-NY', which it inherits from the state
+                  of New York.
+                - The region value for Puerto Rico is 'US-PR'.
+            """).strip(),
+        ),
+    ] = None
+    perspectives: Annotated[
+        Perspectives | None,
+        Field(
+            description=textwrap.dedent("""
+                Political perspectives from which this division is considered to be an accurate
+                representation.
+
+                If this property is absent, then this division is not known to be disputed from
+                any political perspective. Consequently, there is only one division feature
+                representing the entire real world entity.
+
+                If this property is present, it means the division represents one of several
+                alternative perspectives on the same real-world entity.
+
+                There are two modes of perspective:
+
+                1. `accepted_by` means the representation of the division is accepted by the
+                   listed entities and would be included on a map drawn from their perspective.
+
+                2. `disputed_by` means the representation of the division is disputed by the
+                   listed entities and would be excluded from a map drawn from their perspective.
+
+                When drawing a map from the perspective of a given country, one would start by
+                gathering all the undisputed divisions (with no `perspectives` property), and then
+                adding to that first all divisions explicitly accepted by the country, and second
+                all divisions not explicitly disputed by the country.
+            """).strip(),
+        ),
+    ] = None
+    # If we decide to include default language, it will go here. But is it really generally-useful information?
+    norms: Annotated[
+        Norms | None,
+        Field(
+            description=textwrap.dedent("""
+                Collects information about local norms and rules within the division that are
+                generally useful for mapping and map-related use cases.
+
+                If the norms property or a desired sub-property of the norms property is missing
+                on a division, but at least one of its ancestor divisions has the norms property
+                and the desired sub-property, then the value from the nearest ancestor division
+                may be assumed.
+            """).strip(),
+        ),
+    ] = None
+    population: Annotated[
+        int32 | None, Field(ge=0, description="Population of the division")
+    ] = None
+    capital_division_ids: Annotated[
+        list[
+            Annotated[
+                Id,
+                Reference(Relationship.HIERARCHY, Division, role="has_as_capital"),
+            ]
+        ]
+        | None,
+        Field(
+            min_length=1,
+            description=textwrap.dedent("""
+                Division IDs of this division's capital divisions. If present, this property will
+                refer to the division IDs of the capital cities, county seats, etc. of a division.
+            """).strip(),
+        ),
+        UniqueItemsConstraint(),
+    ] = None
+    capital_of_divisions: Annotated[
+        list[CapitalOfDivisionItem] | None,
+        Field(
+            min_length=1,
+            description="Division IDs and subtypes of divisions this division is a capital of.",
+        ),
+        UniqueItemsConstraint(),
+    ] = None
+    wikidata: WikidataId | None = None
+
+
+# Materialize forward references to `Division`.
+def __materialize_forward_refs(model_class: type[BaseModel]) -> None:
+    rebuilt: bool | None = model_class.model_rebuild()
+    assert rebuilt, (
+        f"expected `{model_class.__name__}` to be rebuilt to materialize forward references to `{Division.__name__}`, but it wasn't"
+    )
+
+
+__materialize_forward_refs(CapitalOfDivisionItem)
+__materialize_forward_refs(HierarchyItem)

overture_schema_theme_divisions-0.1.1.dev0/src/overture/schema/divisions/division_area.py

@@ -0,0 +1,159 @@
+"""Division area models for Overture Maps divisions theme."""
+
+import textwrap
+from typing import Annotated, Literal
+
+from pydantic import ConfigDict, Field
+
+from overture.schema.common import (
+    OvertureFeature,
+)
+from overture.schema.common.names import (
+    Named,
+    Names,
+)
+from overture.schema.system.doc import DocumentedEnum
+from overture.schema.system.geometric import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
+from overture.schema.system.model_constraint import (
+    FieldEqCondition,
+    require_any_true,
+    require_if,
+)
+from overture.schema.system.ref import Id, Reference, Relationship
+from overture.schema.system.string import CountryCodeAlpha2, RegionCode
+
+from ._common import AdminLevel, DivisionSubtype
+from .division import Division
+
+
+class AreaClass(str, DocumentedEnum):
+    """
+    Further classification of a division area that is more specific than its `subtype`.
+
+    A division area's `class` adds detail to the broad classification found in `DivisionSubtype`.
+    """
+
+    LAND = ("land", "The area does not extend beyond the coastline.")
+    MARITIME = (
+        "maritime",
+        textwrap.dedent("""
+            The area extends beyond the coastline, in most cases to the extent of the division's
+            territorial sea, if it has one.
+        """).strip(),
+    )
+
+
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.COUNTRY))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.DEPENDENCY))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.MACROREGION))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.REGION))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.MACROCOUNTY))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.COUNTY))
+@require_any_true(
+    FieldEqCondition("is_land", True),
+    FieldEqCondition("is_territorial", True),
+)
+class DivisionArea(
+    OvertureFeature[Literal["divisions"], Literal["division_area"]], Named
+):
+    """
+    Division areas are polygon features that represent the land or maritime area covered by a
+    division.
+
+    Each division area belongs to a division which it references by ID, and for which the division
+    area provides an area polygon. For ease of use, every division area repeats the subtype, names,
+    country, and region properties of the division it belongs to.
+    """
+
+    model_config = ConfigDict(title="division_area")
+
+    # Core
+    geometry: Annotated[
+        Geometry,
+        GeometryTypeConstraint(GeometryType.POLYGON, GeometryType.MULTI_POLYGON),
+        Field(
+            description=textwrap.dedent("""
+                The area covered by the division with which this area feature is
+                associated.
+            """).strip(),
+        ),
+    ]
+
+    # Required
+
+    names: Annotated[
+        Names,
+        Field(description="All known names by which the owning division is called"),
+    ]
+    subtype: Annotated[
+        DivisionSubtype,
+        Field(
+            description=textwrap.dedent("""
+                A broad classification of the division this area belongs to (e.g., country, region,
+                locality, etc.).
+
+                This value is the same as the owning division's `subtype`.
+            """).strip()
+        ),
+    ]
+    class_: Annotated[
+        AreaClass,
+        Field(
+            alias="class",
+            description=textwrap.dedent("""
+                A more specific classification of the division area than is provided by `subtype`.
+            """).strip(),
+        ),
+    ]
+    is_land: Annotated[
+        bool | None,
+        Field(
+            description=textwrap.dedent("""
+                Flag indicating whether or not the feature geometry represents the land-clipped,
+                non-maritime boundary. The geometry can be used for map rendering, cartographic
+                display, and similar purposes.
+            """).strip(),
+            strict=True,
+        ),
+    ] = None
+    is_territorial: Annotated[
+        bool | None,
+        Field(
+            description=textwrap.dedent("""
+                Flag indicating whether or not the feature geometry represents Overture's best
+                approximation of the division's territorial boundary. For coastal places, this will
+                tend to include the water area. The geometry can be used for data processing,
+                reverse-geocoding, and similar purposes.
+            """).strip(),
+            strict=True,
+        ),
+    ] = None
+    division_id: Annotated[
+        Id,
+        Field(
+            description="Division ID of the parent division of this area.",
+        ),
+        Reference(Relationship.HIERARCHY, Division, role="child_of"),
+    ]
+    country: Annotated[
+        CountryCodeAlpha2,
+        Field(
+            description="ISO 3166-1 alpha-2 country code of the division this area belongs to.",
+        ),
+    ]
+
+    # Optional
+
+    region: Annotated[
+        RegionCode | None,
+        Field(
+            description=textwrap.dedent("""
+                ISO 3166-2 principal subdivision code of the division this area belongs to.
+            """).strip(),
+        ),
+    ] = None
+    admin_level: AdminLevel | None = None

overture_schema_theme_divisions-0.1.1.dev0/src/overture/schema/divisions/division_boundary.py

@@ -0,0 +1,222 @@
+"""Division boundary models for Overture Maps divisions theme."""
+
+import textwrap
+from typing import Annotated, Literal
+
+from pydantic import ConfigDict, Field
+
+from overture.schema.common import (
+    OvertureFeature,
+)
+from overture.schema.common.perspectives import Perspectives
+from overture.schema.system.doc import DocumentedEnum
+from overture.schema.system.field_constraint import UniqueItemsConstraint
+from overture.schema.system.geometric import (
+    Geometry,
+    GeometryType,
+    GeometryTypeConstraint,
+)
+from overture.schema.system.model_constraint import (
+    FieldEqCondition,
+    forbid_if,
+    require_any_true,
+    require_if,
+)
+from overture.schema.system.ref import Id, Reference, Relationship
+from overture.schema.system.string import CountryCodeAlpha2, RegionCode
+
+from ._common import IS_COUNTRY, AdminLevel, DivisionSubtype
+from .division import Division
+
+
+class BoundaryClass(str, DocumentedEnum):
+    """
+    The kind of boundary: land or maritime.
+    """
+
+    LAND = (
+        "land",
+        textwrap.dedent("""
+            None of the boundary geometry extends beyond the coastline of either associated
+            division.
+        """).strip(),
+    )
+    MARITIME = (
+        "maritime",
+        textwrap.dedent("""
+            All the boundary geometry extends beyond the coastline of both associated divisions.
+        """).strip(),
+    )
+
+
+@forbid_if(["country"], IS_COUNTRY)
+@require_if(["country"], ~IS_COUNTRY)
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.COUNTRY))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.DEPENDENCY))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.MACROREGION))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.REGION))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.MACROCOUNTY))
+@require_if(["admin_level"], FieldEqCondition("subtype", DivisionSubtype.COUNTY))
+@require_any_true(
+    FieldEqCondition("is_land", True),
+    FieldEqCondition("is_territorial", True),
+)
+class DivisionBoundary(
+    OvertureFeature[Literal["divisions"], Literal["division_boundary"]]
+):
+    """
+    Boundaries represent borders between divisions of the same subtype.
+
+    Some boundaries may be disputed by the divisions on one or both sides.
+    """
+
+    model_config = ConfigDict(title="division_boundary")
+
+    # Core
+    geometry: Annotated[
+        Geometry,
+        GeometryTypeConstraint(
+            GeometryType.LINE_STRING, GeometryType.MULTI_LINE_STRING
+        ),
+        Field(
+            description="Boundary line or lines",
+        ),
+    ]
+
+    # Required
+
+    subtype: Annotated[
+        DivisionSubtype,
+        Field(
+            description=textwrap.dedent("""
+                A broad classification of the divisions this boundary separates (e.g., country,
+                region, locality, etc.).
+            """).strip()
+        ),
+    ]
+    class_: Annotated[
+        BoundaryClass,
+        Field(
+            alias="class",
+            description="The kind of boundary: land or maritime.",
+        ),
+    ]
+    is_land: Annotated[
+        bool | None,
+        Field(
+            description=textwrap.dedent("""
+                Flag indicating whether or not the feature geometry represents the land-clipped,
+                non-maritime boundary. The geometry can be used for map rendering, cartographic
+                display, and similar purposes.
+            """).strip(),
+            strict=True,
+        ),
+    ] = None
+    is_territorial: Annotated[
+        bool | None,
+        Field(
+            description=textwrap.dedent("""
+                Flag indicating whether or not the feature geometry represents Overture's best
+                approximation of the division's territorial boundary. For coastal places, this will
+                tend to include the water area. The geometry can be used for data processing,
+                reverse-geocoding, and similar purposes.
+            """).strip(),
+            strict=True,
+        ),
+    ] = None
+    division_ids: Annotated[
+        list[
+            Annotated[
+                Id,
+                Reference(Relationship.COMPOSITION, Division, role="boundary_of"),
+            ]
+        ],
+        Field(
+            min_length=2,
+            max_length=2,
+            description=textwrap.dedent("""
+                Identifies the two divisions to the left and right, respectively, of the
+                boundary line. The left- and right-hand sides of the boundary are considered
+                from the perspective of a person standing on the line facing in the direction
+                in which the geometry is oriented, i.e. facing toward the end of the line.
+
+                The first array element is the Overture ID of the left division. The second
+                element is the Overture ID of the right division.
+            """).strip(),
+        ),
+        UniqueItemsConstraint(),
+    ]
+    country: Annotated[
+        CountryCodeAlpha2 | None,
+        Field(
+            description=textwrap.dedent("""
+                ISO 3166-1 alpha-2 country code of the country or country-like entity that
+                both sides of the boundary share.
+
+                This property will be present on boundaries between two regions, counties,
+                or similar entities within the same country, but will not be present on
+                boundaries between two countries or country-like entities.
+            """).strip(),
+        ),
+    ] = None
+
+    # Optional
+
+    region: Annotated[
+        RegionCode | None,
+        Field(
+            description=textwrap.dedent("""
+                ISO 3166-2 principal subdivision code of the subdivision-like entity that
+                both sides of the boundary share.
+
+                This property will be present on boundaries between two counties, localadmins
+                or similar entities within the same principal subdivision, but will not be
+                present on boundaries between different principal subdivisions or countries.
+            """).strip(),
+        ),
+    ] = None
+    admin_level: AdminLevel | None = None
+    is_disputed: Annotated[
+        bool | None,
+        Field(
+            description=textwrap.dedent("""
+                Flag indicating whether this boundary is either disputed outright or is a "best
+                guess" in a case where the boundary between two divisions is unclear.
+
+                If the boundary is disputed outright, this flag is true and the entities disputing
+                it are listed in the `perspectives` property. If the boundary is simply a "best
+                guess", this flag is true but no disputing entities are listed in `perspectives`.
+            """).strip(),
+            strict=True,
+        ),
+    ] = None
+    perspectives: Annotated[
+        Perspectives | None,
+        Field(
+            description=textwrap.dedent("""
+                Political perspectives from which this division boundary is considered to be
+                an accurate representation.
+
+                If this property is absent, then this boundary is not known to be disputed
+                from any political perspective. Consequently, there is only one boundary
+                feature representing the entire real world entity.
+
+                If this property is present, it means the boundary represents one of several
+                alternative perspectives on the same real-world entity.
+
+                There are two modes of perspective:
+
+                1. `accepted_by` means the representation of the boundary is accepted by the
+                   listed entities and would be included on a map drawn from their perspective.
+
+                2. `disputed_by` means the representation of the boundary is disputed by the
+                   listed entities and would be excluded from a map drawn from their
+                   perspective.
+
+                When drawing a map from the perspective of a given country, one would start by
+                gathering all the undisputed boundaries (those with no `perspectives` value); and
+                then adding to that: first, all boundaries explicitly accepted by the country, and
+                second, all boundaries not explicitly disputed by the country.
+            """).strip(),
+        ),
+    ] = None