Skip to main content

Overture Maps Schema

Overture Maps data is structured by three components: the schema, the data model, and GERS. The schema describes the shape of the data and devises the constraints applied to that data. The data model specifies what types of features exist, their geometries, how the features relate to each other, and what kind of attributes they have. Every feature in Overture Maps has a unique ID, and for some feature types that unique ID is part of the Global Entity Reference System, a system of encoding map data to a shared universal reference. You can see all three components in this description of one feature, the Empire State Building:

{
"id": "08b2a100d2d4bfff02006354283c153f",
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [[[-73.9865012, 40.748491],[-73.9851602, 40.7479255],[-73.9848166, 40.7483931],[-73.9861574, 40.7489585],[-73.9863252, 40.7487301],[-73.9863554, 40.748689],[-73.9864839, 40.7485145],[-73.9865012, 40.748491]]]
},
"properties": {
"theme": "buildings",
"type": "building",
"subtype": "commercial",
"class": "office",
"height": 443.2,
"num_floors": 102,
"has_parts": true,
"names": {
"primary": "Empire State Buiding"
},
"sources": [
{
"property": "dataset",
"dataset": "OpenStreetMap",
"record_id": "w34633854@71"
}
],
"version": 0,
"update_time": "2023-06-06T10:30:00Z"
}
}

GeoJSON mental model

The Overture Maps schema is defined by the JSON schema, and GeoJSON is used as the canonical geospatial format. GeoJSON provides us with a mental model and language to express data constructions in the schema.

Features represent entities

Overture Maps uses the simple feature model specified by the Open Geospatial Consortium to describe each feature. Features in Overture Maps represent entities in the real world. An entity is a physical thing or concept: a segment of road, a city boundary, a building, or a park. In most cases it's helpful to think of an entity and a feature as the same thing, but in practice it can be more complicated. An entity could be represented by multiple features in a geospatial dataset, and a feature in a dataset might be a representation of multiple entities. For example, a school building and its entrances and exits might be considered a single entity in the real world but could be represented as multiple features in a dataset, each feature with a unique ID.

Global Entity Reference System (GERS)

All features in Overture Maps have unique IDs. For some feature types, the unique ID is registered with the Global Entity Reference System (GERS). GERS is a framework for structuring, encoding, and matching map data to a shared universal reference. It provides a mechanism to conflate datasets, matching one or more features via those unique IDs. For example, two geospatial datasets each containing a polygon that represents the footprint of the Empire State Building in New York City can be easily matched because both polygons will reference the same ID in GERS. A conflated dataset will then have a single polygon feature with one ID that represents the real-world entity known as "New York's Empire State Building."

Schema characteristics

Core schema properties

Every feature in Overture Maps has a core set of properties that are described in the schema. Overture Maps features:

  • have a type
  • have geometry, where the type of geometry is constrained by the feature type.
  • are strongly-typed, i.e. the feature type constrains the geometry and properties.
  • have properties, which may include a core set of "flat" properties and additional properties with a nested structure.
  • have an ID property which is globally unique within the ID-space of the entire Overture Maps data distribution version. For some feature types, the ID is registered with GERS and is a GERS ID.
  • may have custom user extension properties.

Schema notation conventions

  • snake_case is used for all property names, string enumeration members, and string-valued enumeration equivalents
  • boolean properties have a prefix verb "is" or "has" in a way that grammatically makes sense e.g.
    • has_street_lights=true
    • is_accessible=false

Measurements

Measurements of real-world objects and features follow The International System of Units (SI): heights, widths, lengths, etc. In the Overture Maps schema, these values are provided as scalar numeric value without units such as feet or meters. Overture does this to maximize consistency and predictability.

Quantities specified in regulatory rules, norms and customs follow local specifications wherever possible. In the schema, these values are provided as two-element arrays where the first element is the scalar numeric value and the second value is the units. Overture uses local units of measurement -- feet in the United States and meters in the EU, for example. The exact unit is confirmed in the specification of the property but is not repeated in the data.

Relations

Low-cardinality directed relations are stored as ID references on the source feature.

Regulations and restrictions

All quantities that related to posted or ordenance regulations and restrictions are expressed in the same units as as used in the regulation. The unit is explicitly included with the property in the data.

Opening hours/validity periods

Opening hours and the time frame during which time dependent properties are applicable are indicated following the OSM Opening Hours specification.

Extensions

Overture allows for add hoc extensions beyond what is described in the schema. All extensions are prefixed with ext. Extensions can be provided at the theme level, the type level, or the property level.

Data formats

While Overture Maps describes data using a GeoJSON mental model it distributes data as GeoParquet, a column-oriented format that is ideally suited for large geospatial datasets. This documentation includes many examples of how to work with data stored in GeoParquet files.