[WIP] New reference documentation

.gitignore

@@ -1,9 +1,4 @@
 .DS_Store
 .docusaurus
 node_modules/
-docs/_examples/
-docs/_schema/
-docs/schema/
-docs/schema
-static/_schema/
 build/

blog/2024-04-22-beta-release.mdx

@@ -89,7 +89,7 @@ WITH admins AS (
 We plan to [deprecate admins](https://docs.overturemaps.org/release-notes/) by the July release. In the meantime, both `admins` and `divisions` will be available to users. 
 
 ## Bridges, islands, waterfalls, and more!
-We added more rich detail to our `base` layer in this release, including an `infrastructure` type with familiar features from [Facebook’s Daylight map distribution](https://daylightmap.org/). We also added new subtypes and classes for the `land`, `land_use`, and `water` feature types. You'll find a comprehensive listing of the subtypes and classes for each feature type in our [schema reference docs](https://docs.overturemaps.org/schema/reference/base/infrastructure). Ready to make your own map? We have a [tutorial to help you get started](https://docs.overturemaps.org/examples/build-a-map/#13/47.6/-122.33/0/45).
+We added more rich detail to our `base` layer in this release, including an `infrastructure` type with familiar features from [Facebook’s Daylight map distribution](https://daylightmap.org/). We also added new subtypes and classes for the `land`, `land_use`, and `water` feature types. You'll find a comprehensive listing of the subtypes and classes for each feature type in our schema reference docs. Ready to make your own map? We have a [tutorial to help you get started](https://docs.overturemaps.org/examples/build-a-map/#13/47.6/-122.33/0/45).
 
 ## Stay tuned for more highlights
 We'll be back soon with more posts that explore our path from the beta release to production. In the meantime, we invite you to [get started with our data](https://docs.overturemaps.org/getting-data/) and share with us your [comments and feedback](https://github.com/OvertureMaps/data/discussions). 

blog/2024-05-16-land-cover.mdx

@@ -15,7 +15,7 @@ The [May release](https://docs.overturemaps.org/release/latest) of Overture Maps
 
 Our `land_cover` layer is vectorized data derived from the [European Space Agency’s 2020 WorldCover (10m) rasters](https://esa-worldcover.org/en). It's similar to the land cover layer in the [Daylight](https://daylightmap.org/2023/10/11/landcover.html) map distribution, but Overture Maps added higher-resolution data (zoom level 15) with more detail and land cover classes. You'll find 10 subtypes in the new data: snow, forest, urban, grass, crop, barren, wetland, moss, mangrove, and shrub. 
 
-Our May release also includes [schema properties](https://docs.overturemaps.org/schema/reference/base/land_cover/) that offer cartographic "hints" for optimal use of Overture Maps data in mapmaking. We added `min_zoom` and `max_zoom` to define the recommended zooms for each resolution of land cover, using the common “slippy maps” zoom level specification. This is a first step toward improving the user experience for mapmakers. We plan to expand these properties in future releases of Overture Maps data.
+Our May release also includes schema properties that offer cartographic "hints" for optimal use of Overture Maps data in mapmaking. We added `min_zoom` and `max_zoom` to define the recommended zooms for each resolution of land cover, using the common “slippy maps” zoom level specification. This is a first step toward improving the user experience for mapmakers. We plan to expand these properties in future releases of Overture Maps data.
 
 ## Exploring land cover
 

blog/2024-08-15-preview-august-release.mdx

@@ -46,7 +46,7 @@ information about roads from our data sources. For example, we’ve been able
 to move more than 30 million “unknown” road segments from OSM into the new subclasses, laying the groundwork
 for richer and more detailed map displays with Overture data.
 
-Here's how class, subclasses, and flags are modeled in the [Overture schema](https://github.com/OvertureMaps/schema/blob/main/schema/transportation/segment.yaml):
+Here's how class, subclasses, and flags are modeled in the Overture schema:
 
 ```yaml
 class: footway
@@ -75,7 +75,7 @@ subclass_rules:
 ### Connectors
 To better support routing use cases, we added to the segment feature type [a new property](https://github.com/OvertureMaps/schema/pull/257) called
 `connectors`: an array of IDs with pre-computed linear reference values that explicitly link segments and
-[connector features](https://docs.overturemaps.org/schema/reference/transportation/connector/) via coordinates. The `connectors` property contains a list of connector features to which a segment feature is physically connected and the relative location of those connector features along the segment. Each connector is a possible routing decision point, meaning it defines a place along the segment in which there is possibility to transition to other segments that share the same connector.
+connector features via coordinates. The `connectors` property contains a list of connector features to which a segment feature is physically connected and the relative location of those connector features along the segment. Each connector is a possible routing decision point, meaning it defines a place along the segment in which there is possibility to transition to other segments that share the same connector.
 
 This new property — a replacement for the existing `connector_ids`
 property — will reduce complexity and improve accuracy as we calculate the intersections between segment and connector features. We plan to deprecate the `connector_ids` property in the August release and remove it from the schema in the October release.

blog/2024-12-18-transportation-to-ga.mdx

@@ -22,7 +22,7 @@ We've had to break a few things in our schema to make way for improvements:
 
 - To better support routing use cases, we added to the segment feature type a new property called `connectors`: an array of IDs with pre-computed linear reference values that explicitly link segments and connector features via coordinates. Each connector is a possible routing decision point, meaning it defines a place along the segment in which there is possibility to transition to other segments that share the same connector. This new property — a replacement for the old `connector_ids` property — will reduce complexity and improve accuracy as we calculate the intersections between segment and connector features. You can read more about this improvement [here](https://docs.overturemaps.org/blog/2024/08/15/preview-august-release/#transportation-schema-changes).
 
-- In the [November release](https://docs.overturemaps.org/release/2024-11-13.0/), we removed `lanes` from the schema to eliminate a significant trust violation. The `lanes` property has existed in the schema for months but we never populated it with data in our releases, which is a poor experience for our community. We intend to redesign `lanes` in the coming months.
+- In the November release, we removed `lanes` from the schema to eliminate a significant trust violation. The `lanes` property has existed in the schema for months but we never populated it with data in our releases, which is a poor experience for our community. We intend to redesign `lanes` in the coming months.
 
 With these changes, we are confident we’ve met our requirements for general availability (GA). We'll continue refining our schema and improving our data throughout 2025. We encourage our community to keep the feedback coming, particularly around data quality and our core use cases of map display, routing, and matching data via GERS.
 

blog/2024/2024-07-22.0.mdx

@@ -36,7 +36,7 @@ You can access the datasets by following the process outlined [here](https://doc
 
 ## New theme: addresses
 
-In this release, we added a new theme called [addresses](/schema/reference/addresses/address) that includes over 200 million address features for 14 countries. We are releasing this theme in alpha and anticipate significant changes over the next several releases. We invite the Overture community to test the addresses schema and data and offer feedback via the [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repos.
+In this release, we added a new theme called addresses that includes over 200 million address features for 14 countries. We are releasing this theme in alpha and anticipate significant changes over the next several releases. We invite the Overture community to test the addresses schema and data and offer feedback via the [data](https://github.com/OvertureMaps/data/issues) and [schema](https://github.com/OvertureMaps/schema/issues) repos.
 
 
 ## Breaking changes

blog/2024/2024-12-18.0.mdx

@@ -10,7 +10,7 @@ import QueryBuilder from '@site/src/components/queryBuilder';
 
 ## Overview
 
-**The `2024-12-18.0` release of Overture data and `v1.4.0` of the Overture schema are now available.** This month [our transportation theme is going to GA](/blog), we're launching a [bathymetry feature type](/schema/reference/base/bathymetry) in our base theme, and we're at 400 million address records and counting in our [addresses theme](/guides/addresses). What a way to end the year!
+**The `2024-12-18.0` release of Overture data and `v1.4.0` of the Overture schema are now available.** This month [our transportation theme is going to GA](/blog), we're launching a bathymetry feature type in our base theme, and we're at 400 million address records and counting in our [addresses theme](/guides/addresses). What a way to end the year!
 
 The datasets are available as GeoParquet files stored on both AWS and Azure. The release paths are:
 

docs/_examples/addresses/address.yaml

@@ -0,0 +1,17 @@
+---
+id: overture:addresses:address:1
+type: Feature
+geometry:
+  type: Point
+  coordinates: [-71.2086153, 42.3373725]
+properties:
+  theme: addresses
+  type: address
+  version: 0
+  country: US
+  address_levels:
+    - value: MA
+    - value: NEWTON CENTRE
+  postcode: '02459'
+  street: COMMONWEALTH AVE
+  number: '1000'

docs/_examples/addresses/address_all_missing_address_levels.yaml

@@ -0,0 +1,17 @@
+---
+id: overture:addresses:addres:1
+type: Feature
+geometry:
+  type: Point
+  coordinates: [-71.2086153, 42.3373725]
+properties:
+  theme: addresses
+  type: address
+  version: 0
+  country: US
+  address_levels:
+    - {}
+    - {}
+  postcode: '02459'
+  street: COMMONWEALTH AVE
+  number: '1000'

docs/_examples/addresses/address_missing_address_level.yaml

@@ -0,0 +1,17 @@
+---
+id: overture:addresses:addres:1
+type: Feature
+geometry:
+  type: Point
+  coordinates: [-71.2086153, 42.3373725]
+properties:
+  theme: addresses
+  type: address
+  version: 0
+  country: US
+  address_levels:
+    - value: MA
+    - {}
+  postcode: '02459'
+  street: COMMONWEALTH AVE
+  number: '1000'

docs/_examples/addresses/address_postal_city.yaml

@@ -0,0 +1,18 @@
+---
+id: overture:addresses:address:1
+type: Feature
+geometry:
+  type: Point
+  coordinates: [-71.2086153, 42.3373725]
+properties:
+  theme: addresses
+  type: address
+  version: 0
+  country: US
+  address_levels:
+    - value: MA
+    - value: NEWTON CENTRE
+  postcode: '02459'
+  street: COMMONWEALTH AVE
+  number: '1000'
+  postal_city: Some City

docs/_examples/base/bathymetry-example.yaml

@@ -0,0 +1,19 @@
+---
+id: "overture:bathymetry:example:1"
+type: Feature
+geometry:
+  type: Polygon
+  coordinates: [[[-73.1902319,41.6678018],[-73.1896302,41.667817],[-73.1890448,41.6667723],[-73.1899188,41.6666994],[-73.1902319,41.6678018]]]
+properties:
+  theme: base
+  type: bathymetry
+  depth: 2500
+  cartography:
+    min_zoom: 0
+    max_zoom: 23
+    sort_key: 7
+  sources:
+    - record_id: x123
+      property: ""
+      dataset: some source
+  version: 0

docs/_examples/base/infrastructure-example.yaml

@@ -0,0 +1,21 @@
+---
+id: 08b2748cc1383fff0001b38438099b73
+type: Feature
+geometry:
+  type: Polygon
+  coordinates: [[[-85.6743541,42.9676009],[-85.6743623,42.9674649],[-85.6744114,42.9674803],[-85.6744559,42.9674919],[-85.6745302,42.9675058],[-85.6746036,42.9675151],[-85.6746959,42.9675171],[-85.675835,42.9674967],[-85.6758985,42.9674915],[-85.6759656,42.967483],[-85.6760399,42.9674711],[-85.676099,42.9674566],[-85.6761817,42.9674324],[-85.676227,42.9674184],[-85.6762149,42.9675911],[-85.6761726,42.9675857],[-85.676106,42.9675781],[-85.6760499,42.9675741],[-85.6759947,42.9675723],[-85.6743541,42.9676009]]]
+properties:
+  theme: base
+  type: infrastructure
+  subtype: bridge
+  class: bridge
+  names:
+    primary: Gillett Bridge
+    rules:
+      - variant: alternate
+        value: Interurban Bridge
+  sources:
+    - property: ""
+      record_id: w556368546@3
+      dataset: OpenStreetMap
+  version: 0

docs/_examples/base/infrastructure-height-example.yaml

@@ -0,0 +1,19 @@
+---
+id: 08b4035ac1518fff0001a9e45d5e1c9d
+type: Feature
+geometry:
+  type: Point
+  coordinates: [111.5341723, 25.1110193]
+properties:
+  theme: base
+  type: infrastructure
+  subtype: power
+  class: generator
+  height: 160.0
+  names:
+    primary: DEW-G5000-195
+  sources:
+    - property: ""
+      record_id: n10707323715@5
+      dataset: OpenStreetMap
+  version: 0

docs/_examples/base/land-cover-example.yaml

@@ -0,0 +1,19 @@
+---
+id: "overture:land_cover:example:1"
+type: Feature
+geometry:
+  type: Polygon
+  coordinates: [[[-73.1902319,41.6678018],[-73.1896302,41.667817],[-73.1890448,41.6667723],[-73.1899188,41.6666994],[-73.1902319,41.6678018]]]
+properties:
+  theme: base
+  type: land_cover
+  subtype: forest
+  cartography:
+    min_zoom: 11
+    max_zoom: 23
+    sort_key: 2
+  sources:
+    - record_id: x123
+      property: ""
+      dataset: some source
+  version: 0

docs/_examples/base/land-sand-example.yaml

@@ -0,0 +1,21 @@
+---
+id: "overture:land:example:1"
+type: Feature
+geometry:
+  type: Polygon
+  coordinates: [[[34.4379197, 28.7592689], [34.4380109, 28.7595816], [34.4380173, 28.7601587], [34.4380538, 28.7606186],[34.4381540, 28.7609863], [34.4380735, 28.7612459], [34.4377346, 28.7608396], [34.4377158, 28.7606139],[34.4377105, 28.7605527], [34.4376300, 28.7604258], [34.4376407, 28.7603599], [34.4376488, 28.7602494],[34.4376863, 28.7599673], [34.4376675, 28.7597980], [34.4376890, 28.7596216], [34.4379197, 28.7592689]]]
+properties:
+  theme: base
+  type: land
+  subtype: sand
+  class: dune
+  names:
+    primary: Hadeida
+  source_tags:
+    natural: dune
+    surface: sand
+  sources:
+    - record_id: w407753930@3
+      property: ""
+      dataset: OpenStreetMap
+  version: 0

docs/_examples/base/land-use-example.yaml

@@ -0,0 +1,22 @@
+---
+id: "overture:land_use:example:1"
+type: Feature
+geometry:
+  type: Polygon
+  coordinates: [[[-83.8710175, 10.3469578], [-83.8700924, 10.3470179], [-83.870043, 10.3462819], [-83.8709681, 10.3462218], [-83.8710175, 10.3469578]]]
+properties:
+  theme: base
+  type: land_use
+  subtype: recreation
+  class: pitch
+  surface: recreation_grass
+  source_tags:
+    leisure: pitch
+    sport: soccer
+  names:
+    primary: Plaza Deportes Finca Tres
+  sources:
+    - record_id: w509487233@1
+      property: ""
+      dataset: OpenStreetMap
+  version: 0

docs/_examples/base/water-body-disputed.yaml

@@ -0,0 +1,36 @@
+---
+id: "OXOXOXOXOX"
+type: Feature
+geometry:
+  type: Polygon
+  coordinates: [[
+    [-91.8307764, 43.7899936],
+    [-91.8309309, 43.7901326],
+    [-91.8315202, 43.7906232],
+    [-91.8320790, 43.7911798],
+    [-91.8325770, 43.7917638],
+    [-91.8328390, 43.7921615],
+    [-91.8307764, 43.7899936]
+    ]]
+properties:
+  theme: base
+  type: water
+  subtype: ocean
+  class: ocean
+  names:
+    primary: Gulf of Gerdaus Mercator
+    rules:
+      - variant: official
+        perspectives:
+          mode: accepted_by
+          countries: [US]
+        value: Gulf of Cartographer's Tears
+  source_tags:
+    water: ocean
+  sources:
+    - record_id: w1234567
+      property: ""
+      dataset: OpenStreetMap
+  is_salt: false
+  is_intermittent: false
+  version: 0

docs/_examples/base/water-river-example.yaml

@@ -0,0 +1,22 @@
+---
+id: overture:base:water:123
+type: Feature
+geometry:
+  type: LineString
+  coordinates: [[-91.8307764, 43.7899936], [-91.8309309, 43.7901326], [-91.8315202, 43.7906232], [-91.8320790, 43.7911798], [-91.8325770, 43.7917638], [-91.8328390, 43.7921615]  ]
+properties:
+  theme: base
+  type: water
+  subtype: river
+  class: river
+  names:
+    primary: Root River
+  source_tags:
+    waterway: river
+  sources:
+    - record_id: w54320702@1
+      property: ""
+      dataset: OpenStreetMap
+  is_salt: false
+  is_intermittent: false
+  version: 0