[ENHANCEMENT] Added Colloquial Areas - Supplemental Dataset Schema

[Pradeep Kumar (pradeepbkkumar)]

B. Related MINOR change steps

• Add a new supplemental dataset feature type: colloquial_area

C. Public documentation and messaging plan

TODO.

Description

Supplemental Datasets

Supplemental datasets extend Overture Maps with additional geographic data that is not part of the core reference map. They provide valuable map data from single sources that complement—but remain separate from—the multi-source, conflated reference map.

Characteristics

• Not part of the reference map corpus - Supplemental datasets add new rows of map data rather than new properties to existing features
• 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 (GERS) identifiers used for entity resolution
• Independent release cadence - Updates follow their own schedule, not tied to monthly reference map releases
• No reference map links - Features do not link to reference map features via GERS IDs
• No theme property - Unlike reference map features, supplemental datasets do not include a theme property

Colloquial Areas as Supplemental

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. They are nonetheless highly important for search, mapping, analytics, and user experience, particularly when users expect them to behave like meaningful geographic entities.

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.

Properties:

• type (required) - Always colloquial_area
• version (required) - Feature version number
• names (required) - Multi-language names with primary and common translations
• sources (required) - Source attribution
• bbox (optional) - Bounding box as [west, south, east, north]
• center_point (optional) - Representative point for labeling/geocoding
• parent_name (optional) - Name of containing geographic area
• wikipedia_url (optional) - Wikipedia article URL
• wikidata (optional) - Wikidata identifier

Geometry: Polygon or MultiPolygon

Reference

• https://github.com/OvertureMaps/rfd/discussions/57

Testing

• Added examples and counterexamples with appropriate validations
• Tested those examples by running the below commands
  • ./test.sh -m examples "supplemental-datasets/colloquial_area/.*"
  • ./test.sh -m counterexamples "supplemental-datasets/colloquial_area/.*"
• Tested the corresponding pydantic schema too
  • uv run pytest packages

Checklist

Checklist of tasks commonly-associated with schema pull requests. Please review the relevant checklists and ensure you do all the tasks that are required for the change you made.

1. Add relevant examples.
2. Add relevant counterexamples.
3. Update any counterexamples that became obsolete. For example, if a counterexample uses property A but is not intended to test property A's validity, and you made a schema change that invalidates property A in that counterexample, fix the counterexample to align it with your schema change.
4. Update in-schema documentation using plain English written in complete sentences, if an update is required.
5. Update Docusaurus documentation, if an update is required.
6. Review change with Overture technical writer to ensure any advanced documentation needs will be taken care of, unless the change is trivial and would not affect the documentation.

Documentation website

Docs preview for this PR.

[github-actions]

🗺️ Schema reference docs preview is live!

🌍 Preview	https://staging.overturemaps.org/schema/pr/497/schema/index.html
🕐 Updated	Apr 30, 2026 17:08 UTC
📝 Commit	ebefca8
🔧 env SCHEMA_PREVIEW	true

Note

♻️ This preview updates automatically with each push to this PR.

[Victor Schappert (vcschapp)]

My understanding of where the RFD #87 conversation is developing is that:

1. Until we have the extensions structure fully in-place we would publish supplemental datasets without any formal schema in the schema repo.
2. Once we have the extensions mechanism ready to go, supplemental datasets can optional extension schemas if they want.

Until we get that extensions mechanism over the line I don't think we'd want to merge this, but not doing so shouldn't be a blocker for launching colloquial regions as a supplemental dataset.

[github-actions]

❌ PR Title Validation Failed

Error: No release type found in pull request title "Added Colloquial Areas - Supplemental Dataset Schema". Add a prefix to indicate what kind of release this pull request corresponds to. For reference, see https://www.conventionalcommits.org/

Available types:

• BUG
• FEATURE
• ENHANCEMENT
• DOCS
• REFACTOR
• TEST
• CHORE
• PERFORMANCE
• SECURITY
• INVESTIGATION

---

Examples:

• [BUG] Fix null pointer exception in geometry validator
• [REFACTOR](schema) Consolidate validation logic

See the Overture Maps Foundation GitHub usage guidelines for full documentation.

[Victor Schappert (vcschapp)]

Dana Bauer (@danabauer) Pradeep Kumar (@pradeepbkkumar) What's the status of this effort? Nothing's happened here since April. It would be good to close it if we aren't actively trying to advance it.