diff --git a/counterexamples/divisions/geographic_area/bad-class.yaml b/counterexamples/divisions/geographic_area/bad-class.yaml new file mode 100644 index 000000000..caa7728b7 --- /dev/null +++ b/counterexamples/divisions/geographic_area/bad-class.yaml @@ -0,0 +1,16 @@ +--- +id: counterexample:geography:bad-class +type: Feature +geometry: + type: Polygon + coordinates: [[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: cultural + class: regional + names: + primary: A cultural geography with an invalid class. + ext_expected_errors: + - "value must be one of 'colloquial', 'postal'" diff --git a/counterexamples/divisions/geographic_area/bad-geometry-type.yaml b/counterexamples/divisions/geographic_area/bad-geometry-type.yaml new file mode 100644 index 000000000..d8dda06cb --- /dev/null +++ b/counterexamples/divisions/geographic_area/bad-geometry-type.yaml @@ -0,0 +1,17 @@ +--- +id: counterexample:geography:bad-geometry +type: Feature +geometry: + type: Point + coordinates: [0, 0] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: functional + class: postal + names: + primary: A geography with invalid Point geometry (must be Polygon or MultiPolygon). + ext_expected_errors: + - "/properties/type/enum]: value must be 'Polygon'" + - "/properties/type/enum]: value must be 'MultiPolygon'" diff --git a/counterexamples/divisions/geographic_area/bad-subtype.yaml b/counterexamples/divisions/geographic_area/bad-subtype.yaml new file mode 100644 index 000000000..591b4402d --- /dev/null +++ b/counterexamples/divisions/geographic_area/bad-subtype.yaml @@ -0,0 +1,16 @@ +--- +id: counterexample:geography:bad-subtype +type: Feature +geometry: + type: Polygon + coordinates: [[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: administrative + class: colloquial + names: + primary: A geography with an invalid subtype. + ext_expected_errors: + - "value must be one of 'functional', 'cultural'" diff --git a/counterexamples/divisions/geographic_area/colloquial-functional-mismatch.yaml b/counterexamples/divisions/geographic_area/colloquial-functional-mismatch.yaml new file mode 100644 index 000000000..d066c9955 --- /dev/null +++ b/counterexamples/divisions/geographic_area/colloquial-functional-mismatch.yaml @@ -0,0 +1,16 @@ +--- +id: counterexample:geography:colloquial-functional-mismatch +type: Feature +geometry: + type: Polygon + coordinates: [[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: functional + class: colloquial + names: + primary: A functional geography with colloquial class (only allowed for cultural). + ext_expected_errors: + - "value must be 'cultural'" diff --git a/counterexamples/divisions/geographic_area/missing-class-cultural.yaml b/counterexamples/divisions/geographic_area/missing-class-cultural.yaml new file mode 100644 index 000000000..51900edfd --- /dev/null +++ b/counterexamples/divisions/geographic_area/missing-class-cultural.yaml @@ -0,0 +1,15 @@ +--- +id: counterexample:geography:missing-class +type: Feature +geometry: + type: Polygon + coordinates: [[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: cultural + names: + primary: A geography missing required class property. + ext_expected_errors: + - "missing property 'class'" diff --git a/counterexamples/divisions/geographic_area/missing-class-functional.yaml b/counterexamples/divisions/geographic_area/missing-class-functional.yaml new file mode 100644 index 000000000..b759395dd --- /dev/null +++ b/counterexamples/divisions/geographic_area/missing-class-functional.yaml @@ -0,0 +1,15 @@ +--- +id: counterexample:geography:missing-class-functional +type: Feature +geometry: + type: Polygon + coordinates: [[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: functional + names: + primary: A functional geography missing required class property. + ext_expected_errors: + - "missing property 'class'" diff --git a/counterexamples/divisions/geographic_area/negative-population.yaml b/counterexamples/divisions/geographic_area/negative-population.yaml new file mode 100644 index 000000000..09e3f9bca --- /dev/null +++ b/counterexamples/divisions/geographic_area/negative-population.yaml @@ -0,0 +1,17 @@ +--- +id: counterexample:geography:negative-population +type: Feature +geometry: + type: Polygon + coordinates: [[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: cultural + class: colloquial + names: + primary: A geography with negative population. + population: -1000 + ext_expected_errors: + - "minimum: got -1,000, want 0" diff --git a/counterexamples/divisions/geographic_area/postal-cultural-mismatch.yaml b/counterexamples/divisions/geographic_area/postal-cultural-mismatch.yaml new file mode 100644 index 000000000..60998a533 --- /dev/null +++ b/counterexamples/divisions/geographic_area/postal-cultural-mismatch.yaml @@ -0,0 +1,16 @@ +--- +id: counterexample:geography:postal-cultural-mismatch +type: Feature +geometry: + type: Polygon + coordinates: [[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: cultural + class: postal + names: + primary: A cultural geography with postal class (only allowed for functional). + ext_expected_errors: + - "value must be 'functional'" diff --git a/docs/schema/reference/divisions/geographic_area.mdx b/docs/schema/reference/divisions/geographic_area.mdx new file mode 100644 index 000000000..d0c85b49b --- /dev/null +++ b/docs/schema/reference/divisions/geographic_area.mdx @@ -0,0 +1,117 @@ +--- +title: geographic_area +--- + +import CodeBlock from '@theme/CodeBlock'; +import JSONSchemaViewer from "@theme/JSONSchemaViewer"; +import generateResolverOptions from "@site/src/components/shared-libs/generateResolverOptions" +import yamlLoad from "@site/src/components/yamlLoad" +import divisions_geographic_area_schema from '!!raw-loader!@site/docs/_schema/divisions/geographic_area.yaml'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import geographic_area_example_cultural_bay_area from '!!raw-loader!@site/docs/_examples/divisions/geographic_area/cultural_colloquial_bay_area.yaml'; +import geographic_area_example_cultural_wine_country from '!!raw-loader!@site/docs/_examples/divisions/geographic_area/cultural_colloquial_wine_country.yaml'; +import geographic_area_example_functional_zip from '!!raw-loader!@site/docs/_examples/divisions/geographic_area/functional_postal_zip_code.yaml'; + + +# Geographic area + +A geographic area is a functional or cultural region that may span across multiple administrative divisions. These regions capture areas defined by shared characteristics, usage patterns, or cultural identity rather than formal administrative boundaries. + + + + + + + + + + + + + + + + + +
Geometry TypePolygon or MultiPolygon
Themedivisions
Typegeographic_area
+ +## Subtypes + +Geographic areas are categorized into two main subtypes: + + + + + + + + + + +
subtypefunctional
+ +Functional regions are defined by functional characteristics or usage patterns, such as postal code regions or economic zones. These areas serve specific operational or administrative purposes. + +

Classes:

+ + + + + + + + + + + +
subtypecultural
+ +Cultural regions are defined by cultural identity, colloquial usage, or shared cultural characteristics. These areas reflect how people commonly refer to regions in everyday language. + +

Classes:

+ + + + + +## Properties + +Key properties of geographic areas include: + +- **names** - Primary name and optional translations +- **subtype** - Either `functional` or `cultural` +- **class** - Required classification (e.g., `colloquial` for cultural, `postal` for functional) +- **associated_division_ids** - Optional list of division IDs that make up the geographic area +- **population** - Optional population count if inferable +- **cartography** - Cartographic hints including prominence for map display +- **wikidata** - Optional Wikidata ID reference + +## Schema + + + + + + + {divisions_geographic_area_schema} + + + +## Examples + + + + { JSON.stringify(yamlLoad(geographic_area_example_cultural_bay_area), null, 2) } + + + { JSON.stringify(yamlLoad(geographic_area_example_cultural_wine_country), null, 2) } + + + { JSON.stringify(yamlLoad(geographic_area_example_functional_zip), null, 2) } + + diff --git a/examples/divisions/geographic_area/cultural_colloquial_bay_area.yaml b/examples/divisions/geographic_area/cultural_colloquial_bay_area.yaml new file mode 100644 index 000000000..f74797b7f --- /dev/null +++ b/examples/divisions/geographic_area/cultural_colloquial_bay_area.yaml @@ -0,0 +1,48 @@ +--- +id: example:geography:cultural:bay_area +type: Feature +geometry: + type: Polygon + coordinates: [ + [ + [-123.0, 37.3], + [-121.5, 37.3], + [-121.5, 38.5], + [-123.0, 38.5], + [-123.0, 37.3] + ] + ] +bbox: [-123.0, 37.3, -121.5, 38.5] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: cultural + class: colloquial + names: + primary: San Francisco Bay Area + common: + en: Bay Area + es: Área de la Bahía + zh: 舊金山灣區 + cartography: + prominence: 75 + min_zoom: 6 + max_zoom: 12 + associated_division_ids: + - example:division:locality:san_francisco + - example:division:locality:oakland + - example:division:locality:san_jose + - example:division:county:alameda + - example:division:county:contra_costa + - example:division:county:marin + - example:division:county:san_francisco + - example:division:county:san_mateo + - example:division:county:santa_clara + population: 7753000 + wikidata: Q213205 + sources: + - property: "" + dataset: OpenStreetMap + record_id: relation/111968 + update_time: "2023-11-15T10:20:30Z" diff --git a/examples/divisions/geographic_area/cultural_colloquial_east_asia.yaml b/examples/divisions/geographic_area/cultural_colloquial_east_asia.yaml new file mode 100644 index 000000000..7f82dd68f --- /dev/null +++ b/examples/divisions/geographic_area/cultural_colloquial_east_asia.yaml @@ -0,0 +1,48 @@ +--- +id: example:geography:cultural:east_asia +type: Feature +geometry: + type: Polygon + coordinates: [ + [ + [100.0, 20.0], + [145.0, 20.0], + [145.0, 50.0], + [100.0, 50.0], + [100.0, 20.0] + ] + ] +bbox: [100.0, 20.0, 145.0, 50.0] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: cultural + class: colloquial + names: + primary: East Asia + common: + en: East Asia + es: Asia Oriental + fr: Asie de l'Est + zh: 東亞 + zh-Hans: 东亚 + ja: 東アジア + ko: 동아시아 + cartography: + prominence: 85 + min_zoom: 3 + max_zoom: 8 + associated_division_ids: + - example:division:country:cn + - example:division:country:jp + - example:division:country:kr + - example:division:country:kp + - example:division:country:mn + - example:division:country:tw + population: 1677000000 + wikidata: Q27231 + sources: + - property: "" + dataset: OpenStreetMap + record_id: relation/345678 diff --git a/examples/divisions/geographic_area/cultural_colloquial_new_england.yaml b/examples/divisions/geographic_area/cultural_colloquial_new_england.yaml new file mode 100644 index 000000000..d1ba0f030 --- /dev/null +++ b/examples/divisions/geographic_area/cultural_colloquial_new_england.yaml @@ -0,0 +1,45 @@ +--- +id: example:geography:cultural:new_england +type: Feature +geometry: + type: Polygon + coordinates: [ + [ + [-73.5, 41.0], + [-69.5, 41.0], + [-69.5, 47.5], + [-73.5, 47.5], + [-73.5, 41.0] + ] + ] +bbox: [-73.5, 41.0, -69.5, 47.5] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: cultural + class: colloquial + names: + primary: New England + common: + en: New England + es: Nueva Inglaterra + fr: Nouvelle-Angleterre + pt: Nova Inglaterra + cartography: + prominence: 70 + min_zoom: 5 + max_zoom: 10 + associated_division_ids: + - example:division:region:connecticut + - example:division:region:maine + - example:division:region:massachusetts + - example:division:region:new_hampshire + - example:division:region:rhode_island + - example:division:region:vermont + population: 15116205 + wikidata: Q18389 + sources: + - property: "" + dataset: OpenStreetMap + record_id: relation/60759 diff --git a/examples/divisions/geographic_area/cultural_colloquial_south_florida.yaml b/examples/divisions/geographic_area/cultural_colloquial_south_florida.yaml new file mode 100644 index 000000000..4d08ad037 --- /dev/null +++ b/examples/divisions/geographic_area/cultural_colloquial_south_florida.yaml @@ -0,0 +1,41 @@ +--- +id: example:geography:cultural:south_florida +type: Feature +geometry: + type: Polygon + coordinates: [ + [ + [-81.5, 25.0], + [-79.8, 25.0], + [-79.8, 27.0], + [-81.5, 27.0], + [-81.5, 25.0] + ] + ] +bbox: [-81.5, 25.0, -79.8, 27.0] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: cultural + class: colloquial + names: + primary: South Florida + common: + en: South Florida + es: Sur de Florida + cartography: + prominence: 65 + min_zoom: 7 + max_zoom: 11 + associated_division_ids: + - example:division:county:miami_dade + - example:division:county:broward + - example:division:county:palm_beach + - example:division:county:monroe + population: 6198782 + wikidata: Q1352730 + sources: + - property: "" + dataset: OpenStreetMap + record_id: relation/234567 diff --git a/examples/divisions/geographic_area/cultural_colloquial_wine_country.yaml b/examples/divisions/geographic_area/cultural_colloquial_wine_country.yaml new file mode 100644 index 000000000..1d36209f2 --- /dev/null +++ b/examples/divisions/geographic_area/cultural_colloquial_wine_country.yaml @@ -0,0 +1,36 @@ +--- +id: example:geography:cultural:california_wine_country +type: Feature +geometry: + type: Polygon + coordinates: [ + [ + [-123.5, 38.0], + [-122.0, 38.0], + [-122.0, 39.0], + [-123.5, 39.0], + [-123.5, 38.0] + ] + ] +bbox: [-123.5, 38.0, -122.0, 39.0] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: cultural + class: colloquial + names: + primary: California Wine Country + common: + en: Wine Country + es: Región Vinícola de California + cartography: + prominence: 50 + min_zoom: 8 + max_zoom: 13 + wikidata: Q3303756 + sources: + - property: "" + dataset: OpenStreetMap + record_id: relation/123456 + update_time: "2023-09-10T08:15:00Z" diff --git a/examples/divisions/geographic_area/functional_postal_zip_code.yaml b/examples/divisions/geographic_area/functional_postal_zip_code.yaml new file mode 100644 index 000000000..45df1a5ea --- /dev/null +++ b/examples/divisions/geographic_area/functional_postal_zip_code.yaml @@ -0,0 +1,38 @@ +--- +id: example:geography:functional:us_zip_90210 +type: Feature +geometry: + type: Polygon + coordinates: [ + [ + [-118.416, 34.088], + [-118.396, 34.088], + [-118.396, 34.108], + [-118.416, 34.108], + [-118.416, 34.088] + ] + ] +bbox: [-118.416, 34.088, -118.396, 34.108] +properties: + theme: divisions + type: geographic_area + version: 0 + subtype: functional + class: postal + names: + primary: "90210" + common: + en: Beverly Hills ZIP Code + cartography: + prominence: 30 + min_zoom: 11 + max_zoom: 15 + associated_division_ids: + - example:division:locality:beverly_hills + population: 21733 + wikidata: Q3271856 + sources: + - property: "" + dataset: US Census Bureau + record_id: ZCTA5/90210 + update_time: "2023-08-15T12:00:00Z" diff --git a/packages/overture-schema-divisions-theme/pyproject.toml b/packages/overture-schema-divisions-theme/pyproject.toml index e56b1df6a..565e30ba4 100644 --- a/packages/overture-schema-divisions-theme/pyproject.toml +++ b/packages/overture-schema-divisions-theme/pyproject.toml @@ -4,7 +4,7 @@ dependencies = [ "overture-schema-system", "pydantic>=2.0", ] -description = "Overture Maps divisions theme shared structures, division, division area and division boundary types" +description = "Overture Maps divisions theme shared structures, division, division area, division boundary, and geographic area types" dynamic = ["version"] license = "MIT" name = "overture-schema-divisions-theme" @@ -29,3 +29,4 @@ packages = ["src/overture"] "overture:divisions:division" = "overture.schema.divisions:Division" "overture:divisions:division_area" = "overture.schema.divisions:DivisionArea" "overture:divisions:division_boundary" = "overture.schema.divisions:DivisionBoundary" +"overture:divisions:geographic_area" = "overture.schema.divisions:GeographicArea" diff --git a/packages/overture-schema-divisions-theme/src/overture/schema/divisions/__init__.py b/packages/overture-schema-divisions-theme/src/overture/schema/divisions/__init__.py index ea08ff2e5..7b3cc025a 100644 --- a/packages/overture-schema-divisions-theme/src/overture/schema/divisions/__init__.py +++ b/packages/overture-schema-divisions-theme/src/overture/schema/divisions/__init__.py @@ -9,5 +9,6 @@ from .division import Division from .division_area import DivisionArea from .division_boundary import DivisionBoundary +from .geographic_area import GeographicArea -__all__ = ["Division", "DivisionArea", "DivisionBoundary"] +__all__ = ["Division", "DivisionArea", "DivisionBoundary", "GeographicArea"] diff --git a/packages/overture-schema-divisions-theme/src/overture/schema/divisions/geographic_area/__init__.py b/packages/overture-schema-divisions-theme/src/overture/schema/divisions/geographic_area/__init__.py new file mode 100644 index 000000000..2a19485b6 --- /dev/null +++ b/packages/overture-schema-divisions-theme/src/overture/schema/divisions/geographic_area/__init__.py @@ -0,0 +1,6 @@ +"""Geographic area feature type.""" + +from .enums import GeographicAreaClass, GeographicAreaSubtype +from .models import GeographicArea + +__all__ = ["GeographicArea", "GeographicAreaClass", "GeographicAreaSubtype"] diff --git a/packages/overture-schema-divisions-theme/src/overture/schema/divisions/geographic_area/enums.py b/packages/overture-schema-divisions-theme/src/overture/schema/divisions/geographic_area/enums.py new file mode 100644 index 000000000..3c8b7ea33 --- /dev/null +++ b/packages/overture-schema-divisions-theme/src/overture/schema/divisions/geographic_area/enums.py @@ -0,0 +1,37 @@ +"""Geography enums for Overture Maps divisions theme.""" + +from enum import Enum + + +class GeographicAreaSubtype(str, Enum): + """ + The type of geographic area feature. + + - functional: Regions defined by functional characteristics or usage patterns + (e.g., postal codes, economic zones). + + - cultural: Regions defined by cultural identity, colloquial usage, or shared + cultural characteristics (e.g., "East Asia", "California Wine Country"). + """ + + FUNCTIONAL = "functional" + CULTURAL = "cultural" + + +class GeographicAreaClass(str, Enum): + """ + Classification of the geographic area feature. + """ + + # Colloquial regions are informal, culturally defined, or commonly referenced areas + # that do not correspond to official administrative boundaries. Unlike countries, + # states, counties, or cities—whose boundaries are legally defined—colloquial regions + # evolve from cultural, historical, economic, or linguistic identity. + # Examples include South Florida, East Asia, and California Wine Country. + # Only applicable to cultural subtype. + COLLOQUIAL = "colloquial" + + # Postal code regions used for mail delivery and routing. + # Examples include US ZIP codes, UK postcodes, and Canadian postal codes. + # Only applicable to functional subtype. + POSTAL = "postal" diff --git a/packages/overture-schema-divisions-theme/src/overture/schema/divisions/geographic_area/models.py b/packages/overture-schema-divisions-theme/src/overture/schema/divisions/geographic_area/models.py new file mode 100644 index 000000000..51096c94b --- /dev/null +++ b/packages/overture-schema-divisions-theme/src/overture/schema/divisions/geographic_area/models.py @@ -0,0 +1,108 @@ +"""Geography models for Overture Maps divisions theme.""" + +from typing import Annotated, Literal + +from pydantic import ConfigDict, Field, model_validator + +from overture.schema.core import OvertureFeature +from overture.schema.core.cartography import CartographicallyHinted +from overture.schema.core.names import Named, Names +from overture.schema.system.field_constraint import UniqueItemsConstraint +from overture.schema.system.primitive import ( + Geometry, + GeometryType, + GeometryTypeConstraint, + int32, +) +from overture.schema.system.ref import Id, Reference, Relationship + +from ..division.models import Division +from .enums import GeographicAreaClass, GeographicAreaSubtype + + +class GeographicArea( + OvertureFeature[Literal["divisions"], Literal["geographic_area"]], + Named, + CartographicallyHinted, +): + """Geographic area features represent functional or cultural regions that may span across + multiple administrative divisions. + + These regions capture areas defined by shared characteristics, usage patterns, or + cultural identity rather than formal administrative boundaries. + + Examples include postal code regions (functional) or colloquial regions like "East Asia" + or "California Wine Country" (cultural). + """ + + model_config = ConfigDict(title="geographic_area") + + # Core + geometry: Annotated[ + Geometry, + GeometryTypeConstraint(GeometryType.POLYGON, GeometryType.MULTI_POLYGON), + Field( + description="Geography geometry MUST be a Polygon or MultiPolygon as defined by GeoJSON schema. The geometry is constructed from associated divisions or available sources.", + ), + ] + + # Required + + names: Names + subtype: Annotated[ + GeographicAreaSubtype, + Field( + description="""The type of geography feature. + +- functional: Regions defined by functional characteristics or usage patterns (e.g., postal codes, economic zones). + +- cultural: Regions defined by cultural identity, colloquial usage, or shared cultural characteristics (e.g., "East Asia", "California Wine Country").""" + ), + ] + + class_: Annotated[ + GeographicAreaClass, + Field( + alias="class", + description="Classification of the geography feature. Colloquial class is only allowed for cultural subtype. Postal class is only allowed for functional subtype.", + ), + ] + + # Optional + + associated_division_ids: Annotated[ + list[Id] | None, + UniqueItemsConstraint(), + Field( + description="Optional list of division IDs representing the set of divisions that make up this geography region. This property links the geography to the underlying administrative divisions it encompasses or relates to. May be null if the region cannot be precisely mapped to specific administrative divisions.", + min_length=1, + ), + Reference(Relationship.BOUNDARY_OF, Division), + ] = None + + population: Annotated[ + int32 | None, + Field( + description="Optional population represented in the region, if inferable from associated divisions or available sources.", + ge=0, + ), + ] = None + + @model_validator(mode="after") + def validate_class_rules(self) -> "GeographicArea": + """Validate class field rules.""" + # Colloquial class only allowed for cultural subtype + if ( + self.class_ == GeographicAreaClass.COLLOQUIAL + and self.subtype != GeographicAreaSubtype.CULTURAL + ): + raise ValueError("colloquial class is only allowed for cultural subtype") + + # Postal class only allowed for functional subtype + if ( + self.class_ == GeographicAreaClass.POSTAL + and self.subtype != GeographicAreaSubtype.FUNCTIONAL + ): + raise ValueError("postal class is only allowed for functional subtype") + + return self diff --git a/packages/overture-schema-divisions-theme/tests/geographic_area_baseline_schema.json b/packages/overture-schema-divisions-theme/tests/geographic_area_baseline_schema.json new file mode 100644 index 000000000..d5b22bcb2 --- /dev/null +++ b/packages/overture-schema-divisions-theme/tests/geographic_area_baseline_schema.json @@ -0,0 +1,468 @@ +{ + "$defs": { + "CartographicHints": { + "additionalProperties": false, + "description": "Cartographic hints for optimal use of Overture features in map-making.", + "properties": { + "max_zoom": { + "description": "Recommended maximum tile zoom level in which this feature should be displayed.\n\nIt is recommended that the feature be hidden at zoom levels above this value.\n\nZoom levels follow the Slippy Maps convention, documented in the following\nreferences:\n- https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames\n- https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection", + "maximum": 23, + "minimum": 0, + "title": "Max Zoom", + "type": "integer" + }, + "min_zoom": { + "description": "Recommended minimum tile zoom level in which this feature should be displayed.\n\nIt is recommended that the feature be hidden at zoom levels below this value.\n\nZoom levels follow the Slippy Maps convention, documented in the following\nreferences:\n- https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames\n- https://www.maptiler.com/google-maps-coordinates-tile-bounds-projection", + "maximum": 23, + "minimum": 0, + "title": "Min Zoom", + "type": "integer" + }, + "prominence": { + "description": "Subjective scale of feature significance or importance, with 1 being the least, and\n100 being the most, significant.\n\nThis value can be used to help drive decisions about how and when to display a\nfeature, and how to treat it relative to neighboring features.\n\nWhen populated by Overture, this value is derived from various factors including,\nbut not limited to: feature and subtype, population, and capital status.", + "maximum": 100, + "minimum": 1, + "title": "Prominence", + "type": "integer" + }, + "sort_key": { + "description": "Integer indicating the recommended order in which to draw features.\n\nFeatures with a lower number should be drawn \"in front\" of features with a higher\nnumber.", + "maximum": 255, + "minimum": 0, + "title": "Sort Key", + "type": "integer" + } + }, + "title": "CartographicHints", + "type": "object" + }, + "GeographicAreaClass": { + "description": "Classification of the geographic area feature.", + "enum": [ + "colloquial", + "postal" + ], + "title": "GeographicAreaClass", + "type": "string" + }, + "GeographicAreaSubtype": { + "description": "The type of geographic area feature.\n\n- functional: Regions defined by functional characteristics or usage patterns\n (e.g., postal codes, economic zones).\n\n- cultural: Regions defined by cultural identity, colloquial usage, or shared\n cultural characteristics (e.g., \"East Asia\", \"California Wine Country\").", + "enum": [ + "functional", + "cultural" + ], + "title": "GeographicAreaSubtype", + "type": "string" + }, + "NameRule": { + "additionalProperties": false, + "description": "A rule that can be evaluated to determine the name in advanced scenarios.\n\nName rules are used for cases where the primary name is not sufficient; the common name is not\nthe right fit for the use case and another variant is needed; or where the name only applies in\ncertain specific circumstances.\n\nExamples might include:\n- An official, alternate, or short name.\n- A name that only applies to part of a linear path like a road segment (geometric range\n scoping).\n- A name that only applies to the left or right side of a linear path like a road segment (side\n scoping).\n- A name that is only accepted by some political perspectives.", + "properties": { + "between": { + "description": "The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing NameRule applies to.", + "items": { + "maximum": 1.0, + "minimum": 0.0, + "type": "number" + }, + "maxItems": 2, + "minItems": 2, + "title": "Between", + "type": "array" + }, + "language": { + "description": "The language in which the name `value` is specified, if known, as an IETF BCP 47\nlanguage tag.", + "pattern": "^(?:(?:[A-Za-z]{2,3}(?:-[A-Za-z]{3}){0,3}?)|(?:[A-Za-z]{4,8}))(?:-[A-Za-z]{4})?(?:-[A-Za-z]{2}|[0-9]{3})?(?:-(?:[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(?:-[A-WY-Za-wy-z0-9](?:-[A-Za-z0-9]{2,8})+)*$", + "title": "Language", + "type": "string" + }, + "perspectives": { + "$ref": "#/$defs/Perspectives", + "description": "Political perspectives from which a named feature is viewed." + }, + "side": { + "$ref": "#/$defs/Side", + "description": "The side, either left or right, that the containing NameRule applies to." + }, + "value": { + "description": "The actual name value.", + "minLength": 1, + "pattern": "^(\\S.*)?\\S$", + "title": "Value", + "type": "string" + }, + "variant": { + "$ref": "#/$defs/NameVariant", + "description": "The name variant for this name rule." + } + }, + "required": [ + "value", + "variant" + ], + "title": "NameRule", + "type": "object" + }, + "NameVariant": { + "description": "Name variant used in a `NameRule`.", + "enum": [ + "common", + "official", + "alternate", + "short" + ], + "title": "NameVariant", + "type": "string" + }, + "Names": { + "additionalProperties": false, + "description": "Multilingual names container.", + "properties": { + "common": { + "additionalProperties": false, + "patternProperties": { + "^(?:(?:[A-Za-z]{2,3}(?:-[A-Za-z]{3}){0,3}?)|(?:[A-Za-z]{4,8}))(?:-[A-Za-z]{4})?(?:-[A-Za-z]{2}|[0-9]{3})?(?:-(?:[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(?:-[A-WY-Za-wy-z0-9](?:-[A-Za-z0-9]{2,8})+)*$": { + "description": "String with no leading/trailing whitespace", + "pattern": "^(\\S.*)?\\S$", + "type": "string" + } + }, + "propertyNames": { + "description": "IETF BCP-47 language tag" + }, + "title": "Common", + "type": "object" + }, + "primary": { + "description": "The most commonly used name.", + "minLength": 1, + "pattern": "^(\\S.*)?\\S$", + "title": "Primary", + "type": "string" + }, + "rules": { + "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.", + "items": { + "$ref": "#/$defs/NameRule" + }, + "title": "Rules", + "type": "array" + } + }, + "required": [ + "primary" + ], + "title": "Names", + "type": "object" + }, + "PerspectiveMode": { + "description": "Perspective mode for disputed names.", + "enum": [ + "accepted_by", + "disputed_by" + ], + "title": "PerspectiveMode", + "type": "string" + }, + "Perspectives": { + "additionalProperties": false, + "description": "Political perspectives container.", + "properties": { + "countries": { + "description": "Countries holding the given mode of perspective.", + "items": { + "description": "ISO 3166-1 alpha-2 country code", + "maxLength": 2, + "minLength": 2, + "pattern": "^[A-Z]{2}$", + "type": "string" + }, + "minItems": 1, + "title": "Countries", + "type": "array", + "uniqueItems": true + }, + "mode": { + "$ref": "#/$defs/PerspectiveMode", + "description": "Whether the perspective holder accepts or disputes this name." + } + }, + "required": [ + "mode", + "countries" + ], + "title": "Perspectives", + "type": "object" + }, + "Side": { + "description": "The side, left or right, on which something appears relative to a facing or heading direction\n(*e.g.*, the side of a road relative to the road orientation), or relative to the direction of\ntravel of a person or vehicle.", + "enum": [ + "left", + "right" + ], + "title": "Side", + "type": "string" + }, + "SourceItem": { + "additionalProperties": false, + "description": "Specifies the source of the data used for a feature or one of its properties.", + "properties": { + "between": { + "description": "The linearly-referenced sub-segment of the geometry, specified as a range (pair) of percentage displacements from the start of the geometry, that the containing SourceItem applies to.", + "items": { + "maximum": 1.0, + "minimum": 0.0, + "type": "number" + }, + "maxItems": 2, + "minItems": 2, + "title": "Between", + "type": "array" + }, + "confidence": { + "description": "Confidence value from the source dataset.\n\nThis is a value between 0.0 and 1.0 and is particularly relevant for ML-derived data.", + "maximum": 1.0, + "minimum": 0.0, + "title": "Confidence", + "type": "number" + }, + "dataset": { + "description": "Name of the dataset where the source data can be found.", + "title": "Dataset", + "type": "string" + }, + "license": { + "description": "Source data license name.\n\nThis should be a valid SPDX license identifier when available.\n\nIf omitted, contact the data provider for more license information.", + "pattern": "^(\\S.*)?\\S$", + "title": "License", + "type": "string" + }, + "property": { + "description": "A JSON Pointer identifying the property (field) that this source information applies to.\n\nThe root document value `\"\"` indicates that this source information applies to the\nentire feature, excepting properties (fields) for which a dedicated source information\nrecord exists.\n\nAny other JSON Pointer apart from `\"\"` indicates that this source record provides\ndedicated source information for the property at the path in the JSON Pointer. As an\nexample, the value `\"/names/common/en\"` indicates that the source information applies to\nthe English common name of a named feature, while the value `\"/geometry\"` indicates that\nit applies to the feature geometry.", + "title": "Property", + "type": "string" + }, + "record_id": { + "description": "Identifies the specific record within the source dataset where the source data can\nbe found.\n\nThe format of record identifiers is dataset-specific.", + "title": "Record Id", + "type": "string" + }, + "update_time": { + "description": "Last update time of the source data record.", + "format": "date-time", + "title": "Update Time", + "type": "string" + } + }, + "required": [ + "property", + "dataset" + ], + "title": "SourceItem", + "type": "object" + } + }, + "additionalProperties": false, + "description": "Geographic area features represent functional or cultural regions that may span across\nmultiple administrative divisions.\n\nThese regions capture areas defined by shared characteristics, usage patterns, or\ncultural identity rather than formal administrative boundaries.\n\nExamples include postal code regions (functional) or colloquial regions like \"East Asia\"\nor \"California Wine Country\" (cultural).", + "properties": { + "bbox": { + "description": "An optional bounding box for the feature", + "items": { + "type": "number" + }, + "maxItems": 4, + "minItems": 4, + "title": "Bbox", + "type": "array" + }, + "geometry": { + "description": "Geography geometry MUST be a Polygon or MultiPolygon as defined by GeoJSON schema. The geometry is constructed from associated divisions or available sources.", + "oneOf": [ + { + "properties": { + "bbox": { + "items": { + "type": "number" + }, + "minItems": 4, + "type": "array" + }, + "coordinates": { + "items": { + "items": { + "items": { + "items": { + "type": "number" + }, + "maxItems": 3, + "minItems": 2, + "type": "array" + }, + "minItems": 4, + "type": "array" + }, + "minItems": 1, + "type": "array" + }, + "minItems": 1, + "type": "array" + }, + "type": { + "const": "MultiPolygon", + "type": "string" + } + }, + "required": [ + "type", + "coordinates" + ], + "type": "object" + }, + { + "properties": { + "bbox": { + "items": { + "type": "number" + }, + "minItems": 4, + "type": "array" + }, + "coordinates": { + "items": { + "items": { + "items": { + "type": "number" + }, + "maxItems": 3, + "minItems": 2, + "type": "array" + }, + "minItems": 4, + "type": "array" + }, + "minItems": 1, + "type": "array" + }, + "type": { + "const": "Polygon", + "type": "string" + } + }, + "required": [ + "type", + "coordinates" + ], + "type": "object" + } + ], + "title": "Geometry" + }, + "id": { + "description": "A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if\u2014and-only-if the feature represents an entity that is part of GERS.", + "minLength": 1, + "pattern": "^\\S+$", + "title": "Id", + "type": "string" + }, + "properties": { + "additionalProperties": false, + "not": { + "required": [ + "id", + "bbox", + "geometry" + ] + }, + "patternProperties": { + "^ext_.*$": { + "description": "Additional top-level properties are allowed if prefixed by `ext_`.\n\nThis feature is a on a deprecation path and will be removed once the schema is\nfully migrated to Pydantic." + } + }, + "properties": { + "associated_division_ids": { + "description": "Optional list of division IDs representing the set of divisions that make up this geography region. This property links the geography to the underlying administrative divisions it encompasses or relates to. May be null if the region cannot be precisely mapped to specific administrative divisions.", + "items": { + "description": "A unique identifier", + "minLength": 1, + "pattern": "^\\S+$", + "type": "string" + }, + "minLength": 1, + "title": "Associated Division Ids", + "type": "array", + "uniqueItems": true + }, + "cartography": { + "$ref": "#/$defs/CartographicHints", + "title": "cartography" + }, + "class": { + "$ref": "#/$defs/GeographicAreaClass", + "description": "Classification of the geography feature. Colloquial class is only allowed for cultural subtype. Postal class is only allowed for functional subtype." + }, + "names": { + "$ref": "#/$defs/Names" + }, + "population": { + "description": "Optional population represented in the region, if inferable from associated divisions or available sources.", + "maximum": 2147483647, + "minimum": 0, + "title": "Population", + "type": "integer" + }, + "sources": { + "description": "Information about the source data used to assemble the feature.", + "items": { + "$ref": "#/$defs/SourceItem" + }, + "minItems": 1, + "title": "Sources", + "type": "array", + "uniqueItems": true + }, + "subtype": { + "$ref": "#/$defs/GeographicAreaSubtype", + "description": "The type of geography feature.\n\n- functional: Regions defined by functional characteristics or usage patterns (e.g., postal codes, economic zones).\n\n- cultural: Regions defined by cultural identity, colloquial usage, or shared cultural characteristics (e.g., \"East Asia\", \"California Wine Country\")." + }, + "theme": { + "const": "divisions", + "title": "Theme", + "type": "string" + }, + "type": { + "const": "geographic_area", + "title": "Type", + "type": "string" + }, + "version": { + "description": "", + "maximum": 2147483647, + "minimum": 0, + "title": "Version", + "type": "integer" + } + }, + "required": [ + "names", + "theme", + "type", + "version", + "subtype", + "class" + ], + "type": "object" + }, + "type": { + "const": "Feature", + "type": "string" + } + }, + "required": [ + "type", + "id", + "geometry", + "properties" + ], + "title": "geographic_area", + "type": "object" +} \ No newline at end of file diff --git a/packages/overture-schema-divisions-theme/tests/test_geographic_area_json_schema_baseline.py b/packages/overture-schema-divisions-theme/tests/test_geographic_area_json_schema_baseline.py new file mode 100644 index 000000000..6687d9faf --- /dev/null +++ b/packages/overture-schema-divisions-theme/tests/test_geographic_area_json_schema_baseline.py @@ -0,0 +1,32 @@ +"""Baseline JSON Schema tests for geographic area type.""" + +import json +import os + +from overture.schema.divisions import GeographicArea +from overture.schema.system.json_schema import json_schema + + +def test_geographic_area_json_schema_baseline() -> None: + """Test that GeographicArea generates consistent JSON Schema (baseline comparison).""" + schema = json_schema(GeographicArea) + + # Path to baseline file + baseline_file = os.path.join( + os.path.dirname(__file__), "geographic_area_baseline_schema.json" + ) + + # If baseline doesn't exist, create it + if not os.path.exists(baseline_file): + with open(baseline_file, "w") as f: + json.dump(schema, f, indent=2, sort_keys=True) + + # Load baseline and compare + with open(baseline_file) as f: + baseline_schema = json.load(f) + + # Compare the generated schema with the baseline + assert schema == baseline_schema, ( + "Generated JSON Schema differs from baseline. " + "If this change is intentional, delete the baseline file to regenerate it." + ) diff --git a/schema/defs.yaml b/schema/defs.yaml index a20de9047..551aa59bd 100644 --- a/schema/defs.yaml +++ b/schema/defs.yaml @@ -90,6 +90,7 @@ description: Common schema definitions shared by all themes - division - division_area - division_boundary + - geographic_area - infrastructure - land - land_cover diff --git a/schema/divisions/geographic_area.yaml b/schema/divisions/geographic_area.yaml new file mode 100644 index 000000000..1b0447a1e --- /dev/null +++ b/schema/divisions/geographic_area.yaml @@ -0,0 +1,99 @@ +--- +"$schema": https://json-schema.org/draft/2020-12/schema +title: geographic_area +description: + Geographic area features represent functional or cultural regions that may + span across multiple administrative divisions. These regions capture + areas defined by shared characteristics, usage patterns, or cultural + identity rather than formal administrative boundaries. + + Examples include postal code regions (functional) or colloquial regions + like "East Asia" or "California Wine Country" (cultural). +type: object +properties: # JSON Schema: Top-level object properties. + id: { "$ref": ../defs.yaml#/$defs/propertyDefinitions/id } + geometry: + description: + Geography geometry MUST be a Polygon or MultiPolygon as defined + by GeoJSON schema. The geometry is constructed from associated + divisions or available sources. + unevaluatedProperties: false + oneOf: + - "$ref": https://geojson.org/schema/Polygon.json + - "$ref": https://geojson.org/schema/MultiPolygon.json + properties: # GeoJSON: top-level object 'properties' property. + unevaluatedProperties: false + required: [names, subtype, class] + allOf: + - "$ref": ../defs.yaml#/$defs/propertyContainers/overtureFeaturePropertiesContainer + - "$ref": ../defs.yaml#/$defs/propertyContainers/namesContainer + - "$ref": ../defs.yaml#/$defs/propertyContainers/cartographyContainer + - if: + properties: + class: { const: colloquial } + then: + properties: + subtype: { const: cultural } + - if: + properties: + class: { const: postal } + then: + properties: + subtype: { const: functional } + properties: # JSON Schema: properties within GeoJSON top-level object 'properties' property + subtype: + description: >- + The type of geography feature. + + functional: Regions defined by functional characteristics or + usage patterns (e.g., postal codes, economic zones). + + cultural: Regions defined by cultural identity, colloquial + usage, or shared cultural characteristics (e.g., "East Asia", + "California Wine Country"). + type: string + enum: + - functional # Region defined by functional characteristics + # or usage patterns. + + - cultural # Region defined by cultural identity or + # colloquial usage. + class: + description: >- + Classification of the geography feature. + + colloquial: Colloquial regions are informal, culturally defined, + or commonly referenced areas that do not correspond to official + administrative boundaries. Unlike countries, states, counties, or + cities—whose boundaries are legally defined—colloquial regions + evolve from cultural, historical, economic, or linguistic identity. + Examples include South Florida, East Asia, and California Wine Country. + Only applicable to cultural subtype. + + postal: Postal code regions used for mail delivery and routing. + Examples include US ZIP codes, UK postcodes, and Canadian postal codes. + Only applicable to functional subtype. + type: string + enum: + - colloquial # Informal, culturally defined regions without + # official administrative boundaries. + + - postal # Postal code regions for mail delivery. + associated_division_ids: + description: + Optional list of division IDs representing the set of divisions + that make up this geography region. This property links the + geography to the underlying administrative divisions it + encompasses or relates to. May be null if the region cannot be + precisely mapped to specific administrative divisions. + type: array + minItems: 1 + uniqueItems: true + items: { "$ref": "../defs.yaml#/$defs/propertyDefinitions/id" } + population: + description: + Optional population represented in the region, if inferable from + associated divisions or available sources. + type: integer + minimum: 0 + wikidata: { "$ref": "../defs.yaml#/$defs/propertyDefinitions/wikidata" } diff --git a/schema/schema.yaml b/schema/schema.yaml index df59e6529..b01e56649 100644 --- a/schema/schema.yaml +++ b/schema/schema.yaml @@ -106,6 +106,14 @@ oneOf: type: { enum: [division_area] } then: { "$ref": divisions/division_area.yaml } else: { propertyNames: false } + - if: + properties: + properties: + properties: + theme: { enum: [divisions] } + type: { enum: [geographic_area] } + then: { "$ref": divisions/geographic_area.yaml } + else: { propertyNames: false } - if: properties: properties: