Added Colloquial Areas - Supplemental Dataset Schema

.github/workflows/scripts/package-versions.py

@@ -63,7 +63,7 @@ def level(package: str) -> int:
             return 0
         elif package in ["overture-schema-core"]:
             return 1
-        elif re.fullmatch(r'overture-schema-.*-theme', package) or package in ["overture-schema", "overture-schema-cli", "overture-schema-codegen", "overture-schema-annex"]:
+        elif re.fullmatch(r'overture-schema-.*-theme', package) or package in ["overture-schema", "overture-schema-cli", "overture-schema-codegen", "overture-schema-annex", "overture-schema-supplemental-datasets"]:
             return 2
         else:
             raise ValueError(f"Unknown package for level computation: {package}")

Makefile

@@ -47,6 +47,7 @@ mypy-only:
 	@find packages -maxdepth 1 -type d -name "overture-schema*" \
 		| sort \
 		| sed 's|-theme$$||' \
+		| sed 's|-datasets$$||' \
 		| tr - . \
 		| sed 's|^packages/|-p |' \
 		| xargs uv run mypy --no-error-summary

counterexamples/supplemental-datasets/colloquial_area/bad_bbox.yaml

@@ -0,0 +1,24 @@
+---
+# Invalid: bbox property must have exactly 4 elements [west, south, east, north]
+id: example:colloquial_area:bad_bbox
+type: Feature
+geometry:
+  type: Polygon
+  coordinates:
+    - [
+        [-74.0100, 40.7100],
+        [-74.0000, 40.7100],
+        [-74.0000, 40.7200],
+        [-74.0100, 40.7200],
+        [-74.0100, 40.7100]
+      ]
+properties:
+  type: colloquial_area
+  version: 1
+  names:
+    primary: Bad BBox
+  bbox: [-74.0100, 40.7100]  # Only 2 elements instead of 4
+  sources:
+    - property: ""
+      dataset: example_dataset
+      license: MIT

counterexamples/supplemental-datasets/colloquial_area/bad_center_point.yaml

@@ -0,0 +1,26 @@
+---
+# Invalid: center_point must have type 'Point', not 'LineString'
+id: example:colloquial_area:bad_center_point
+type: Feature
+geometry:
+  type: Polygon
+  coordinates:
+    - [
+        [-74.0100, 40.7100],
+        [-74.0000, 40.7100],
+        [-74.0000, 40.7200],
+        [-74.0100, 40.7200],
+        [-74.0100, 40.7100]
+      ]
+properties:
+  type: colloquial_area
+  version: 1
+  names:
+    primary: Bad Center Point
+  center_point:
+    type: LineString
+    coordinates: [[-74.0100, 40.7100], [-74.0000, 40.7200]]
+  sources:
+    - property: ""
+      dataset: example_dataset
+      license: MIT

counterexamples/supplemental-datasets/colloquial_area/bad_geometry.yaml

@@ -0,0 +1,16 @@
+---
+# Invalid: Geometry must be Polygon or MultiPolygon, not Point
+id: example:colloquial_area:bad_geometry
+type: Feature
+geometry:
+  type: Point
+  coordinates: [-74.0050, 40.7150]
+properties:
+  type: colloquial_area
+  version: 1
+  names:
+    primary: Invalid Geometry Example
+  sources:
+    - property: ""
+      dataset: example_dataset
+      license: MIT

counterexamples/supplemental-datasets/colloquial_area/bad_wikipedia_url.yaml

@@ -0,0 +1,24 @@
+---
+# Invalid: wikipedia_url must be a valid URI with http/https scheme
+id: example:colloquial_area:bad_wikipedia_url
+type: Feature
+geometry:
+  type: Polygon
+  coordinates:
+    - [
+        [-74.0100, 40.7100],
+        [-74.0000, 40.7100],
+        [-74.0000, 40.7200],
+        [-74.0100, 40.7200],
+        [-74.0100, 40.7100]
+      ]
+properties:
+  type: colloquial_area
+  version: 1
+  names:
+    primary: Bad Wikipedia URL
+  wikipedia_url: not-a-valid-url
+  sources:
+    - property: ""
+      dataset: example_dataset
+      license: MIT

counterexamples/supplemental-datasets/colloquial_area/missing_names.yaml

@@ -0,0 +1,21 @@
+---
+# Invalid: Missing required 'names' property
+id: example:colloquial_area:missing_names
+type: Feature
+geometry:
+  type: Polygon
+  coordinates:
+    - [
+        [-74.0100, 40.7100],
+        [-74.0000, 40.7100],
+        [-74.0000, 40.7200],
+        [-74.0100, 40.7200],
+        [-74.0100, 40.7100]
+      ]
+properties:
+  type: colloquial_area
+  version: 1
+  sources:
+    - property: ""
+      dataset: example_dataset
+      license: MIT

docs/schema/0-Schema.mdx

@@ -58,6 +58,16 @@ Most but not all of the feature types in the Overture schema require data for th
 ### Properties may be specific to a feature type
 Some properties in the Overture schema are only populated with data for specific feature types. For example, the `place` feature type must include data for the `categories` property, as required by the schema. The `division_area` and `address` feature types require the `country` property to be populated with ISO 3166-1 alpha-2 country codes. The `segment` feature type in the transportation theme is the only feature type that includes data for a complex set of properties that describe roads. The [schema concepts](concepts) section of this documentation describes these complexities in detail.
 
+### Supplemental datasets
+In addition to the core reference map themes, Overture provides **supplemental datasets** that extend the map with additional geographic data not part of the reference map corpus. Supplemental datasets differ from reference map themes in several important ways:
+
+- **Single-source**: Each supplemental dataset comes from a single data provider, not conflated from multiple sources
+- **No GERS IDs**: Features do not have Global Entity Reference System identifiers used for entity resolution
+- **Independent release cadence**: Updates follow their own schedule, not tied to monthly reference map releases
+- **No `theme` property**: Unlike reference map features, supplemental datasets do not include a `theme` property and are identified only by their `type`
+
+Supplemental datasets provide valuable geographic data that users recognize, reference, and search for—even when these features don't meet the strict criteria for inclusion in the multi-source, conflated reference map. Examples include colloquial areas like "South Florida," "East Asia," or "Northern Italy" that represent culturally recognized regions without official administrative boundaries.
+
 
 ## Schema conventions
 In addition to following the JSON and GeoJSON specifications, the Overture schema has its own style and conventions. The notations, nomenclatures, specifications, and standards we have adopted are described below. 

docs/schema/reference/index.mdx

@@ -3,7 +3,7 @@ title: Reference
 slug: /schema/reference
 ---
 
-This section includes the schema reference documentation for Overture's themes: addresses, base, buildings, divisions, places, and transportation. For guides to working with Overture data, including hand-on examples, head over to [docs.overturemaps.org](https://docs.overturemaps.org/guides).
+This section includes the schema reference documentation for Overture's themes: addresses, base, buildings, divisions, places, and transportation. It also includes supplemental datasets that extend Overture Maps with additional geographic data not part of the core reference map. For guides to working with Overture data, including hand-on examples, head over to [docs.overturemaps.org](https://docs.overturemaps.org/guides).
 
 
 

docs/schema/reference/supplemental-datasets/colloquial_area.mdx

@@ -0,0 +1,79 @@
+---
+title: colloquial_area
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import JSONSchemaViewer from "@theme/JSONSchemaViewer";
+import generateResolverOptions from "@site/src/components/shared-libs/generateResolverOptions"
+import StringifyObject from "@site/src/components/shared-libs/stringifyObject"
+import yamlLoad from "@site/src/components/yamlLoad"
+import ColloquialAreaSchema from "!!raw-loader!@site/docs/_schema/supplemental-datasets/colloquial_area.yaml";
+import ColloquialAreaExampleEastAsia from "!!raw-loader!@site/docs/_examples/supplemental-datasets/colloquial_area/east_asia.yaml";
+import ColloquialAreaExampleSouthFlorida from "!!raw-loader!@site/docs/_examples/supplemental-datasets/colloquial_area/south_florida.yaml";
+import ColloquialAreaExampleMinimal from "!!raw-loader!@site/docs/_examples/supplemental-datasets/colloquial_area/minimal.yaml";
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Colloquial Area
+
+A colloquial area represents an informal, culturally defined, or commonly referenced area that does not correspond to official administrative boundaries. Unlike countries, states, counties, or cities whose boundaries are legally defined, colloquial areas evolve from cultural, historical, economic, or linguistic identity. These areas have no official ISO codes, no fixed administrative definitions, and frequently overlap existing divisions.
+
+<table>
+  <tbody>
+  <tr>
+    <th>Geometry Type</th>
+    <td><code>Polygon</code>, <code>MultiPolygon</code></td>
+  </tr>
+  <tr>
+    <th>Supplemental Dataset</th>
+    <td>Yes (not part of reference map)</td>
+  </tr>
+  <tr>
+    <th>Type</th>
+    <td><code>colloquial_area</code></td>
+  </tr>
+  </tbody>
+</table>
+
+:::info Supplemental Dataset
+Colloquial areas are part of a **supplemental dataset**, not a reference map theme. Supplemental datasets:
+- Are single-source (not conflated from multiple sources)
+- Do not have GERS IDs for entity resolution
+- Follow an independent release cadence
+- Do not include a `theme` property
+:::
+
+## Schema
+
+<Tabs>
+  <TabItem value="browsable" label="Browsable" default>
+    <JSONSchemaViewer schema={ yamlLoad(ColloquialAreaSchema) } resolverOptions={ generateResolverOptions({remote: true, yamlBasePath: '/supplemental-datasets'})}/>
+  </TabItem>
+  <TabItem value="yaml" label="YAML" default>
+    <CodeBlock language="jsx">{ColloquialAreaSchema}</CodeBlock>
+  </TabItem>
+</Tabs>
+
+## Examples
+
+<Tabs>
+  <TabItem value="1" label="East Asia" default>
+    <CodeBlock language="json">{ JSON.stringify(yamlLoad(ColloquialAreaExampleEastAsia), null, 2) }</CodeBlock>
+  </TabItem>
+  <TabItem value="2" label="South Florida">
+    <CodeBlock language="json">{ JSON.stringify(yamlLoad(ColloquialAreaExampleSouthFlorida), null, 2) }</CodeBlock>
+  </TabItem>
+  <TabItem value="3" label="Minimal">
+    <CodeBlock language="json">{ JSON.stringify(yamlLoad(ColloquialAreaExampleMinimal), null, 2) }</CodeBlock>
+  </TabItem>
+</Tabs>
+
+## Use Cases
+
+Colloquial areas fill gaps in the reference map by providing recognized geographic data that doesn't fit standard entity-based themes:
+
+- **vs. divisions**: Lack official administrative boundaries or legal status—they are culturally or socially recognized regions
+- **vs. places**: Represent regions and areas (polygons), not point-based business or venue locations  
+- **vs. addresses/buildings/transportation**: Informal geographic regions, not physical infrastructure or postal entities
+
+Examples include South Florida (cultural and economic region), East Asia (macro-region), and Northern Italy (climate, economic, and tourism context).

examples/supplemental-datasets/colloquial_area/east_asia.yaml

@@ -0,0 +1,36 @@
+---
+id: example:colloquial_area:east_asia
+type: Feature
+geometry:
+  type: Polygon
+  coordinates:
+    - [
+        [100.0, 10.0],
+        [145.0, 10.0],
+        [145.0, 50.0],
+        [100.0, 50.0],
+        [100.0, 10.0]
+      ]
+properties:
+  type: colloquial_area
+  version: 1
+  names:
+    primary: East Asia
+    common:
+      en: East Asia
+      zh-CN: 东亚
+      ja: 東アジア
+      ko: 동아시아
+      es: Asia Oriental
+      fr: Asie de l'Est
+  bbox: [100.0, 10.0, 145.0, 50.0]
+  center_point:
+    type: Point
+    coordinates: [122.5, 30.0]
+  wikipedia_url: https://en.wikipedia.org/wiki/East_Asia
+  wikidata: Q27231
+  sources:
+    - property: ""
+      dataset: example_dataset
+      license: ODbL-1.0
+      update_time: "2024-03-15T10:30:00Z"

examples/supplemental-datasets/colloquial_area/minimal.yaml

@@ -0,0 +1,22 @@
+---
+id: example:colloquial_area:minimal
+type: Feature
+geometry:
+  type: Polygon
+  coordinates:
+    - [
+        [-74.0100, 40.7100],
+        [-74.0000, 40.7100],
+        [-74.0000, 40.7200],
+        [-74.0100, 40.7200],
+        [-74.0100, 40.7100]
+      ]
+properties:
+  type: colloquial_area
+  version: 1
+  names:
+    primary: Example Neighborhood
+  sources:
+    - property: ""
+      dataset: example_dataset
+      license: MIT

examples/supplemental-datasets/colloquial_area/south_florida.yaml

@@ -0,0 +1,33 @@
+---
+id: example:colloquial_area:south_florida
+type: Feature
+geometry:
+  type: Polygon
+  coordinates:
+    - [
+        [-82.0, 24.5],
+        [-80.0, 24.5],
+        [-80.0, 27.0],
+        [-82.0, 27.0],
+        [-82.0, 24.5]
+      ]
+properties:
+  type: colloquial_area
+  version: 1
+  names:
+    primary: South Florida
+    common:
+      en: South Florida
+      es: Sur de Florida
+  bbox: [-82.0, 24.5, -80.0, 27.0]
+  center_point:
+    type: Point
+    coordinates: [-81.0, 25.75]
+  parent_name: Florida
+  wikipedia_url: https://en.wikipedia.org/wiki/South_Florida
+  wikidata: Q618897
+  sources:
+    - property: ""
+      dataset: example_dataset
+      license: CC-BY-4.0
+      update_time: "2024-03-20T14:22:00Z"

packages/overture-schema-supplemental-datasets/README.md

@@ -0,0 +1,61 @@
+# Overture Schema Supplemental Datasets
+
+Supplemental datasets for Overture Maps that extend the core schema with
+additional community-recognized geographic features not part of the reference map.
+
+## What are Supplemental Datasets?
+
+Supplemental datasets are **not part of the reference map**. They differ from
+the core Overture themes (addresses, base, buildings, divisions, places,
+transportation) in several key ways:
+
+- **Single-source** - Each supplemental dataset comes from one data provider, not conflated from multiple sources
+- **No GERS IDs** - Features don't have Global Entity Reference System identifiers used for entity resolution
+- **Independent release cadence** - Not tied to monthly reference map updates
+- **Additive data** - New rows of map data, not new properties on existing features
+- **No reference links** - Don't link to reference map features via GERS IDs
+- **No theme property** - Unlike reference map features, supplemental datasets do not include a `theme` property
+
+Supplemental datasets are identified only by their `type` property, not by theme.
+
+## Available Datasets
+
+### Colloquial Areas
+
+Represents 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 areas evolve from cultural,
+historical, economic, or linguistic identity. These areas have no official ISO codes,
+no fixed administrative definitions, and frequently overlap existing divisions.
+
+**Examples:**
+
+- **South Florida**: A cultural and economic region typically understood to include Miami, Fort Lauderdale, and West Palm Beach. It does not match any administrative boundary.
+- **East Asia**: A macro-region defined primarily by cultural and geographic context, comprising countries such as Japan, South Korea, China, Mongolia, etc.
+- **Northern Italy**: Often used to refer to Italian regions north of the Po River; widely used in climate, economic, and tourism contexts.
+
+**Colloquial areas vs. reference map themes:**
+- **vs. divisions**: Lack official administrative boundaries, legal status, or government recognition—they are culturally or socially recognized regions
+- **vs. places**: Represent regions and areas (polygons), not point-based business or venue locations
+- **vs. addresses/buildings/transportation**: Informal geographic regions, not physical infrastructure or postal entities
+
+## Usage
+
+```python
+from overture.schema.supplemental import ColloquialArea
+
+# Validate and work with colloquial area features
+area = ColloquialArea.model_validate(geojson_feature)
+print(f"Area: {area.properties.names.primary}")
+print(f"Parent: {area.properties.parent_name}")
+```
+
+## Data Model
+
+Each colloquial area includes:
+- **Required**: id, geometry (Polygon or MultiPolygon), type, version, names, sources
+- **Optional**: bbox, center_point, parent_name, wikipedia_url, wikidata
+
+Multi-language names support primary and common translations following BCP-47 language tags.
+
+**Note:** Supplemental datasets do not have a `theme` property, distinguishing them from reference map features.