v1.2.0

What's Changed

Read the full release notes here: https://docs.overturemaps.org/release/latest/. Below is a list of changes to the schema since the last release.

Schema-Wide Changes

Fixed a minor validation bug in the names property schema: the variant property in name rules under names.rules is now required. (#277) While technically a "breaking" change, we don't expect this to break anything in practice because all Overture-released data already provides the variant in name rules.

Theme-Specific Schema Changes

Addresses (Status: Alpha)

🏗 The addresses theme is in alpha status. Schema changes with potential backward-incompatibility are likely from month to month until the addresses schema increases in maturity. When these changes occur, we will try to provide some notice and a "bridge" period where the old schema is also supported.

Removed value as a required sub-property of items in the address_level array. (#283) The motivation for this change is that we want to allow {} elements to be used as "placeholder values" within address_level so that the length of the address_level array can be consistent within geographic areas (e.g. United States).

Base (Status: GA)

🟢 The base theme is in GA status. We are striving to avoid backwardly-incompatible schema changes and to deliver adequate notice should they occur.

No changes.

Buildings (Status: GA)

🟢 The buildings theme is in GA status. We are striving to avoid backwardly-incompatible schema changes and to deliver adequate notice should they occur.

No changes.

Divisions (Status: GA)

🟢 The divisions theme is in GA status. We are striving to avoid backwardly-incompatible schema changes and to deliver adequate notice should they occur.

No changes.

Places (Status: GA)

🟢 The places theme is in GA status. We are striving to avoid backwardly-incompatible schema changes and to deliver adequate notice should they occur.

No changes.

Transportation (Status: Beta)

🏗 The transportation theme is in beta status. The transportation schema is nearing maturity, but backwardly-incompatible schema changes may occur from month to month until GA status is achieved. When these changes occur, we will try to provide some notice and a "bridge" period where the old schema is also supported.

Dropped the deprecated connector_ids top-level property/column from transportation segments. (#284) The deprecation schedule for this property was announced in August in the What to expect in Overture’s August release blog, and this change merely completes the announced change. Data enjoyers should consume the connectors property going forward.

Full Changelog

Full Changelog: v1.1.0...v1.2.0

v1.1.0

What's Changed

Read the full release notes here: https://docs.overturemaps.org/release/latest/. Below is a list of changes to the schema since the last release.

Schema-Wide Changes

No changes.

Theme-Specific Schema Changes

Addresses (Status: Alpha)

🏗 The addresses theme is in alpha status. Schema changes with potential backward-incompatibility are likely from month to month until the addresses schema increases in maturity. When these changes occur, we will try to provide some notice and a "bridge" period where the old schema is also supported.

No changes.

Base (Status: GA)

🟢 The base theme is in GA status. We are striving to avoid backwardly-incompatible schema changes and to deliver adequate notice should they occur.

No changes.

Buildings (Status: GA)

🟢 The buildings theme is in GA status. We are striving to avoid backwardly-incompatible schema changes and to deliver adequate notice should they occur.

Minor changes to some SQL mappings from OpenStreetMap tags to Overture schema property values. PR #258.

Divisions (Status: GA)

🟢 The divisions theme is in GA status. We are striving to avoid backwardly-incompatible schema changes and to deliver adequate notice should they occur.

No changes.

Places (Status: GA)

🟢 The places theme is in GA status. We are striving to avoid backwardly-incompatible schema changes and to deliver adequate notice should they occur.

No changes.

Transportation (Status: Beta)

🏗 The transportation theme is in beta status. The transportation schema is nearing maturity, but backwardly-incompatible schema changes may occur from month to month until GA status is achieved. When these changes occur, we will try to provide some notice and a "bridge" period where the old schema is also supported.

The following changes were made to the transportation schema. These changes are also discussed extensively in the August 15, 2024 blog What to expect in Overture’s August release.

1. Destinations are added to segment features via the destination property.
   • Destinations allow functionality such as "follow signs for downtown" to be added in routing engines.
   • This is a purely additive feature and does not introduce any backward-incompatibility issues.
   • PR #176
2. The connector_ids property of a segment feature, which only included the feature ID of the target connector, is replaced by a more general connectors property which includes both the target connector ID and its LR offset on the segment.
   • The connector_ids property will remain supported in the August 2024 and September 2024 data releases but will be permanently removed from the schema in the October 2024 release.
   • Transportation data users should migrate to connectors by October.
   • PR #257
3. More granular information is now available on the real-world role of segment features via the subclass_rules and subclass properties.
   • The subclass_rules property contains linear referencing rules that assign a more granular role information to linearly-referenced ranges of the segment. For example, a segment with class footway may be refined to sidewalk or crosswalk via subclass_rules.
   • If the whole segment has the same subclass (it is not different for different LR ranges), this is captured in the subclass property. Otherwise, subclass captures the "most dominant" subclass from subclass_rules.
   • This change is almost fully backwardly-compatible. However, a few members of the roadClass enumeration used to populate class have been migrated to subclass_rules/subclass. Also, the is_link member of the segment flags has been deprecated and will be deleted in a future release because link status is now captured in subclass_rules/subclass.
   • PR #180
   • There is some additional information on segment subtypes on the docs website here.

Full Changelog

Full Changelog: v1.0.0...v1.1.0

New Contributors

• @stepps00 made his first contribution in #263

v1.0.0

What's Changed

Read the full release notes here: https://docs.overturemaps.org/release/latest/. Below is a list of changes to the schema since the last release.

Schema-wide changes

• added update_time to each source, removing it from the top-level properties.

Theme Specific Schema Changes

Addresses

• A completely new theme, see the schema here

Base

• Additional classes in infrastructure, land, land_use, and water types.

Buildings

• capped height and roof_height at 850 meters and discarded values over that limit
• added classification for bridge structures to schema
• added is_underground to all buildings

Divisions

• added the dependency subtype in division and division_area
• added the microhood subtype in division

Places

• Allow for NULL categories

Transportation

• removed deprecated road column

New Contributors

• @thesteve0 made their first contribution in #187
• @atiannicelli made their first contribution in #224
• @skmoore made their first contribution in #217
• @Dritte made their first contribution in #231

Full Changelog: v0.12.0-beta...v1.0.0

v0.12.0-beta

What's Changed

A. Theme-specific changes

1. Base
   • Fix issue where level property was not correctly populated for infrastructure, land_use, and water features.
   • Add sort_key as an optional cartography property, which is populated for land_cover features
   • Add surface property for infrastructure, land, and land_use features.
   • Improve source_tags pass-through for land features.
   • Improve subtype mapping for infrastructure.
   • Improve class mapping for land_use.
   • Other minor OpenStreetMap tag mapping improvements.
2. Buildings
   • Rename eave_height property to roof_height to simplify and make the schema easier to understand.
   • Spelling corrections and other tweaks to available building classes, building subtypes, and their OSM mappings
   • Add building classes: library and post_office
3. Divisions
   • division features:
     • Fix conceptual issue with perspectives property on division features, switching to an acceptance/inclusion versus dispute/exclusion model.
     • Add multiple capital division IDs on division features to handle multi-capital cases like the Kuyavian–Pomeranian Voivodeship (Województwo kujawsko-pomorskie), Bolivia, and South Africa.
   • boundary features:
     • Allow MultiLineString as a possible geometry type for boundary features. This allows simplifying all boundaries between two adjacent divisions into a single feature with a single GERS ID/Overture ID.
     • Align dispute modeling with division perspectives: add perspectives and is_disputed properties and drop the system of only being able to mark boundaries disputed from the perspective of the divisions to either side via the divisions[*].is_disputing property.
4. Places
   • Fix typo in categories mapping CSV (very minor).
5. Transportation
   • Add top-level routes property to segment feature to contain routes the segment belongs to (i.e. highway network).
     • This is analogous to, and today is generally sourced from, OpenStreetMap relations of type route.
   • Restructure the segment feature's properties as described in #203. We hope this is one of the last, if not the last, major breaking change for transportation.
     • Lifting properties that had previously been nested under the road property up to top level. The purpose of this change is to reduce nesting to a more manageable level and to make the Parquet schemas for segment properties manageable. The property changes here are:
       • road.restrictions.speed_limits becomes speed_limits
       • road.restrictions.access becomes access_restrictions
       • road.restrictions.prohibited_transitions becomes prohibited_transitions
       • road.surface becomes road_surface
       • road.flags becomes road_flags
       • road.width becomes width_rules
       • road.lanes becomes lanes
       • road.level becomes level_rules
     • Slightly simplifying the frequently-used when: vehicle: scoping structure.
     • Deprecating the road property. The road property will still be available in the June 2024 data release, so Overture users can temporarily ignore the restructuring change and continue to use road, but this property will be removed in the coming months. We expect users will prefer the new top-level properties because they will have structured Parquet schemas in the data release from day 1, unlike the road property which is an unwieldy JSON string, which is inconsistent with the rest of the Overture schema and also difficult to use.
   • Limit speed limit maximum value to 350 units (previously there was no maximum).
   • Reduce speed limit minimum value to 1 unit. The previous minimum of 20 units did not make sense and disagreed with the real world ground truth in many places, e.g. narrow pedestrian paths.

B. Documentation changes

• Return feature model, naming, scoping, and transportation pages to schema reference website.
• Build changes to maintain tight integration between schema documentation and the remainder of docs.overturemaps.org.
• Housekeeping changes.

Full Changelog

Full Changelog: v0.11.0-beta...v0.12.0-beta

New Contributors

• @jeffdefacto made his first contribution in #189

Schema v0.11.0-beta release

What's Changed

A. Theme-specific changes

1. Base
   • Add new land_cover feature type which is useful for generating natural-looking backgrounds for vectored map tiles.
   • Update OSM SQL to allow sport=* tags for land features.
   • Tweaks to classes and subtypes, mainly new additions.
2. Buildings
   • Promote building class to subtype and introduce new class property that is subordinate to subtype.
   • Update roof_direction validation rules to include 0 degrees so that perfectly north-facing buildings are valid.
3. Transportation:
   • Add vehicle as a supported travel mode. This had already been present in the data releases, but was missing in the schema.
   • Add is_covered flag for road segment features.

B. Pan-schema changes

• Update the BCP-47 language tag regular expression to be sufficiently permissive. (First step in our process of eliminating all language tag validation issues between the schema and data.)

C. Documentation changes

• Add additional detail to reference docs for divisions theme, particularly division and division_area.
• Enable search within reference docs.
• Add link to engineering blog.

D. Other changes

• Fix bug where special characters broke test script error matching.

Full Changelog

Full Changelog: v0.10.0-beta...v0.11.0-beta

Schema v0.10.0-beta release

What's Changed

A. Theme-specific changes

1. Base
   • Add new infrastructure feature type.
   • Numerous updates to documentary SQL to update OpenStreetMap to Overture class mappings.
   • Update documentary SQL query to rename class → subtype and subclass → class, to keep them aligned with recent schema structural changes.
   • Add new subtype for land feature type: desert.
   • Add new classes for land feature type: cave_entrance, desert, island, islet, mountain_range, plateau, peninsula, saddle, stone.
   • Add new subtypes for land_use feature type: grass, pedestrian
   • Add new classes for land_use feature type: beach_resort, graveyard, pedestrian, plaza.
   • Add new subtypes for water feature type: spring
   • Add new classes for water feature type: bay, blowhole, geyser, hot_spring, sea, spring, waterfall.
   • Rename water class fish_pond to fishpond.
2. Buildings
   • Rename part feature type to building_part. This is to responsive to a recent decision that feature type names (e.g. land, building, connector, etc.) will be globally unique. While part was already globally unique, we felt it was so generic it stood a high probability of generating a naming conflict in the future, so we qualified it.
   • Add min_floor property for buildings and building parts.
   • Update documentary SQL to improve some OpenStreetMap to Overture building class mappings. OSM tag building=parking is now classed as transportation.
   • Tidy up obsolete class mapping files.
3. Divisions
   • Add reference documentation for divisions theme schema. Note that divisions is replacing the now-deprecated admins theme.
4. Transportation
   • Lift road segment class up from road property to be a top level property. This is to increase consistency across the theme schemas.
   • Rename at property for geometric scoping/linearly referenced ranges to between. This is to allow at to be used later to indicate point LR, rather than range LR.
   • Push during property for temporal scoping down under when clause. This is to unblock future addition of an except scoping clause at the same level as when that allows further refinement of scopes.
   • Correct issues with scoping schema. This is a big structural change that should fix remaining Parquet-blocking mixed type issues and also conceptual issues within the transportation schema, including:
     1. Adding temporal scoping support to lane block model.
     2. Removing the option to have a flat lane block that's not participating in an array of lane block rules.
     3. Fixing scoping support for speed limit rules, including adding support for heading (forward/backward) and vehicle scoping to speed limits, and generally aligning ensuring the schema is aligned with generated data.
     4. Fixing a conceptual issue where vehicle properties (length/width/height/weight) within vehicle scopes did not have units.
   • Fix a small bug where road width rules did not require a value.
   • Push segment level down into the segment's road property and add linear referencing support for level. This unblocks the addition of a large amount of level data in the Overture April 2024 data release.
   • Simplify speed_limits property so that max_speed and min_speed sub-properties use {value:, unit:} objects instead of arrays. The array method was tidy, but unsupported in programming environments that aren't as flexible as JSON. In particular, it was impossible to convert the transportation schema to Parquet accurately when arrays could contain mixed types. This simplification fixes that.
   • Remove reason property from prohibited transition rules. The types of things contemplated by the reason property (e.g. gates) will be covered by separate schema updates, coming soon, that will cover features like barriers.
   • Fix min_occupancy conceptually to be a simple scalar number attached to the lane. Previously, this property was defined in a confused/nonsensical and redundant manner.
   • Add path road class.

B. Documentation changes

1. To decouple iteration on the documentation from iteration on the schema, we have migrated the bulk of the narrative documentation out of this (schema) repo and into a separate repo. Reference docs will remain in the schema repo.
2. Add JSON Schema title property in various places to improve rendering of reference documentation.

Full Changelog

Full Changelog: v0.9.0...v0.10.0-beta

Schema v0.9.0 release

What's Changed

A. Structural changes.

1. snake_case. We changed over all property names and enumeration member names from camelCase to snake_case. This is a big one-time churn to improve SQL compatibility. We don't expect another churn of this magnitude.
   • #127
   • #129
2. The transportation segment's connectors property is renamed to connector_ids for consistency with our agreed direction on relationship modeling. #137
3. Various changes in the transportation theme have been made to eliminate cases where JSON Schema types can be mixed, i.e. like a property that can be either an array or an object. The purpose is to improve Parquet compatibility by bringing us to a point where 100% of the JSON Schema can be converted to strongly-typed Parquet schema. We are almost there.
   • #85
   • #135

B. New themes.

1. Divisions. We have re-imagined the schema for administrative data. The re-imagined schema is in theme divisions and is quietly included in this schema release, although not the documentation yet. In the April, 2024 data release we will populate data in the divisions theme and will begin the process of deprecating the admins theme.
   • #130
   • #139

C. Transportation theme improvements.

1. Road width is pushed down to road.width and now supports linear referencing. #121. (Starting with the 2024-03-12 data release we are also now generating road width data.)
2. Alley class is supported. OvertureMaps/tf-transportation#122
3. Abandoned/disused segments are now flagged. #132

D. Other

1, Documentation improvements.
2. Validation improvements: #112
3. OpenStreetMap mappings have been documented:

• For the base theme: #133
• For the buildings theme: #89

Full Changelog

Full Changelog: v0.8.0...v0.9.0

Schema v0.8.0 release

What's Changed

• Documentation improved, see at https://docs.overturemaps.org
• Admins schema: adminLevel simplified to use ordinal numbers 1, 2, 3, ...
• Admins schema: adminLevel=1 is now used for countries
• Admins schema: population property added
• Admins schema: wikidata property added
• Base theme: elevation property added
• For all features types, names property updated to a new "unified" format that is simpler in most cases and also supports linearly-referenced and "side-of-street" road names. The road.roadName property is dropped as names now always appear in the top-level names property
• Bug fixed: updateTime regular expression validation corrected
• Bug fixed: road.surface default value corrected
• Bug fixed: level property dropped from connector
• Bug fixed: temporal scoping removed from road flags
• Bug fixed: isPrivate flag dropped from road flags, as that is handled via access restrictions scoped to private

Full Changelog: v0.7.0...v0.8.0

Schema v0.7.0 release

What's Changed

• Add footway to road class enum by @brad-richardson in #93
• Improve Transportation diagrams with dark/light theme and Overture color palette by @vcschapp in #94
• fix: spelling of cafeteria by @JanCallewaert-TomTom in #86
• Fix type maxiumum->maximum on linearlyReferencedPosition by @DavidKarlas in #73
• December Schema Update by @jenningsanderson in #90

New Contributors

• @JanCallewaert-TomTom made their first contribution in #86

Full Changelog: v0.6.0...v0.7.0

Schema v0.6.0 release

November 14th, schema release.

What's Changed

• update turn restriction documentation to reflect by @jenningsanderson in #65
• Fix charity_organization taxonomy by @Cj-Malone in #66
• [Admins] Add Area type and allow only Point on Locality by @DavidKarlas in #72
• Base theme updates by @jenningsanderson in #75
• Fix lane scoping example by @brad-richardson in #77
• M2 Release by @jenningsanderson in #71

New Contributors

• @Cj-Malone made their first contribution in #66
• @brad-richardson made their first contribution in #77

Full Changelog: v0.5.0...v0.6.0