|
| 1 | +--- |
| 2 | +title: Overview |
| 3 | +slug: /schema |
| 4 | + |
| 5 | +# This page is available at docs.overturemaps.org/schema |
| 6 | +--- |
| 7 | +import CodeBlock from '@theme/CodeBlock'; |
| 8 | +import Tabs from '@theme/Tabs'; |
| 9 | +import TabItem from '@theme/TabItem'; |
| 10 | + |
| 11 | +### Top-level properties |
| 12 | + |
| 13 | +In the Overture schema, all features have a unique `id` called a [GERS ID](https://docs.overturemaps.org/gers/), a `geometry` object that follows the OGC geometry specification, and other top-level properties. |
| 14 | + |
| 15 | +<details> |
| 16 | +<summary>**GeoParquet columns for top-level Overture properties**</summary> |
| 17 | +| column_name | column_type | description | |
| 18 | +| --- | --- | --- | |
| 19 | +| **id** | *string* | an Overture feature's unique id, part of the Global Entity Reference System (GERS) | |
| 20 | +| **geometry** | *binary* | well-known binary (WKB) representation of the feature geometry | |
| 21 | +| **bbox** | *struct\<xmin: float, xmax: float, ymin: float, ymax: float\>* | area defined by two longitudes and two latitudes: latitude is a decimal number between -90.0 and 90.0; longitude is a decimal number between -180.0 and 180.0. | |
| 22 | +| **theme** | *string* | one of six Overture data themes | |
| 23 | +| **type** | *string* | one of 14 Overture feature types | |
| 24 | +| **version** | *int32* | version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed | |
| 25 | +| **sources** | *list\<element: struct\<property: string, dataset: string, record_id: string, update_time: string, confidence: double, between: list\<double\>\>\>* | array of source information for the properties of a given feature | |
| 26 | +</details> |
| 27 | + |
| 28 | +### Other key schema properties |
| 29 | + |
| 30 | +Most but not all of the feature types in the Overture schema require data for the `names`, `subtype`, and `class` properties. The `names` property is complex enough to have its own schema. |
| 31 | + |
| 32 | +### Properties may be specific to a feature type |
| 33 | + |
| 34 | +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 reference section of this documentation digs into the details of these complexities. |
| 35 | + |
| 36 | +## Schema conventions |
| 37 | + |
| 38 | +### Notations |
| 39 | + |
| 40 | +#### Snake case |
| 41 | + |
| 42 | +We use snake case instead of camel case for all property names, string enumeration members, and string-valued enumeration equivalents. We do this because of case sensitivity and transformation issues in different databases and query engines. For example, Athena/Trino downcases everything, so text string splits in camel case property names get lost; in contrast, snake case passes through without issues. |
| 43 | + |
| 44 | +#### Booleans |
| 45 | + |
| 46 | +Boolean properties have a prefix verb "is" or "has" in a way that grammatically makes sense, e.g. `has_street_lights=true` and `is_accessible=false`. |
| 47 | + |
| 48 | +### Measurements |
| 49 | + |
| 50 | +<!-- add to the docs: if we're using both feet and meters in measurements, what's the best way to determine the unit of measure? the schema, presumably, but also the bounding box of the data? |
| 51 | +--> |
| 52 | + |
| 53 | +Measurements of real-world objects and features follow [The International System of Units (SI)](https://www.bipm.org/en/publications/si-brochure): heights, widths, lengths, etc. In the Overture schema, these values are provided as scalar numeric value without units such as feet or meters. Overture does this to maximize consistency and predictability. |
| 54 | + |
| 55 | +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. |
| 56 | + |
| 57 | +### Regulations and restrictions |
| 58 | + |
| 59 | +All quantities that relate to posted or ordinance regulations and restrictions are expressed in the same units as used in the regulation. The unit is explicitly included with the property in the data. |
| 60 | + |
| 61 | +### Opening hours and validity periods |
| 62 | + |
| 63 | +Opening hours and the time frame during which time dependent properties are applicable are indicated following the [OSM Opening Hours specification](https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification). |
| 64 | + |
| 65 | +<!-- This is not yet true |
| 66 | +### Extensions |
| 67 | +
|
| 68 | +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. |
| 69 | +--> |
0 commit comments