Overturemaps

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. (https://github.com/OvertureMaps/schema/pull/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. (https://github.com/OvertureMaps/schema/pull/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. (https://github.com/OvertureMaps/schema/pull/284) The deprecation schedule for this property was announced in August in the [What to expect in Overture’s August release](https://docs.overturemaps.org/blog/2024/08/15/preview-august-release/) blog, and this change merely completes the announced change. Data enjoyers should consume the `connectors` property going forward.

Full Changelog

**Full Changelog**: https://github.com/OvertureMaps/schema/compare/v1.1.0...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

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](https://docs.overturemaps.org/blog/2024/08/15/preview-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](https://docs.overturemaps.org/guides/transportation/#subtypes).

Full Changelog

**Full Changelog**: https://github.com/OvertureMaps/schema/compare/v1.0.0...v1.1.0

New Contributors
* stepps00 made his first contribution in https://github.com/OvertureMaps/schema/pull/263

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](https://docs.overturemaps.org/schema/reference/addresses/address/)

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 https://github.com/OvertureMaps/schema/pull/187
* atiannicelli made their first contribution in https://github.com/OvertureMaps/schema/pull/224
* skmoore made their first contribution in https://github.com/OvertureMaps/schema/pull/217
* Dritte made their first contribution in https://github.com/OvertureMaps/schema/pull/231

**Full Changelog**: https://github.com/OvertureMaps/schema/compare/v0.12.0-beta...v1.0.0

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](https://en.wikipedia.org/wiki/Kuyavian%E2%80%93Pomeranian_Voivodeship) (Województwo kujawsko-pomorskie), [Bolivia](https://en.wikipedia.org/wiki/Bolivia), and [South Africa](https://en.wikipedia.org/wiki/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](https://wiki.openstreetmap.org/wiki/Relation:route).
- Restructure the `segment` feature's properties as described in https://github.com/OvertureMaps/schema/pull/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**: https://github.com/OvertureMaps/schema/compare/v0.11.0-beta...v0.12.0-beta

New Contributors
* jeffdefacto made his first contribution in https://github.com/OvertureMaps/schema/pull/189

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**: https://github.com/OvertureMaps/schema/compare/v0.10.0-beta...v0.11.0-beta

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`.
3. 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.
4. Divisions
- Add reference documentation for *divisions* theme schema. Note that *divisions* is replacing the now-deprecated *admins* theme.
5. 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.
4. 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.
6. 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**: https://github.com/OvertureMaps/schema/compare/v0.9.0...v0.10.0-beta