diff --git a/docs/guides/index.mdx b/docs/guides/index.mdx
index 2b488f8e4..29408ede5 100644
--- a/docs/guides/index.mdx
+++ b/docs/guides/index.mdx
@@ -4,6 +4,7 @@ slug: /guides/
title: Guides
sidebar_label: Overview
description: Overture Maps guides
+pagination_label: Guides
---
import useBaseUrl from '@docusaurus/useBaseUrl';
diff --git a/docs/guides/transportation/linear-referencing.mdx b/docs/guides/transportation/linear-referencing.mdx
new file mode 100644
index 000000000..f4f2d1991
--- /dev/null
+++ b/docs/guides/transportation/linear-referencing.mdx
@@ -0,0 +1,71 @@
+---
+title: Linear Referencing
+description: How Overture uses linear references to describe properties that vary along a segment
+pagination_label: Linear Referencing
+---
+
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+Linear referencing allows properties to apply to portions of a [segment](../segments-and-connectors#segments) without splitting the geometry. This promotes shape stability and reduces versioning when only part of a road changes.
+
+To avoid splitting road segments at any and every property change, linear referencing defines how properties that apply to portions of a segment can vary along that segment while it is generally understood to be the same "road." Segment splits are then reserved for more significant intersections so that we don't have to version the entire road any time any piece of the road changes.
+
+## Linear reference values
+
+A linear reference is a **normalized position** from `0.0` (start of segment) to `1.0` (end of segment).
+
+## `at` vs `between`
+
+| Property | Purpose | Example |
+|----------|---------|---------|
+| `at` | Single point location | `at: 0.3` — 30% along segment |
+| `between` | Range along segment | `between: [0.2, 0.7]` — 20% to 70% |
+
+When `between` is not provided (or is null), the attribute applies to the full segment.
+
+## Calculation method
+
+Overture computes linear references using **WGS84 geodetic distance** in meters:
+
+```
+linear_ref = geodetic_distance_along_segment_from_start / total_geodetic_length
+```
+
+Both distances must be computed on the WGS84 ellipsoid, not planar distance on raw lon/lat coordinates. Other approaches exist (e.g., projected coordinates), but geodetic distance provides consistent accuracy globally.
+
+### Examples
+
+**Apache Sedona (SQL):**
+
+```sql
+SELECT ST_LENGTHSPHEROID(ST_GEOMFROMWKB(geometry)) AS segment_length_m
+FROM segments;
+```
+
+**pyproj (Python):**
+
+```python
+from pyproj import Geod
+from shapely import wkb
+
+geod = Geod(ellps="WGS84")
+line_geometry = wkb.loads(geometry) # geometry is WKB bytes
+segment_length = geod.geometry_length(line_geometry) # meters
+```
+
+See the [transportation-splitter](https://github.com/OvertureMaps/transportation-splitter) for a complete implementation.
+
+:::warning
+Functions like `ST_LINELOCATEPOINT` can produce incorrect results on geometries that cross over or near themselves in 2D (curved on-ramps, mountain switchbacks, cul-de-sacs). These functions may pick the wrong location when the line passes over or close to itself, even though the geometry is valid because crossings occur at different elevations or positions along the segment. Note that Overture [disallows self-intersecting segments](../segments-and-connectors#loops) in its own data.
+:::
+
+## Why geodetic distance matters
+
+Using planar distance (treating lon/lat as Cartesian x/y) can produce incorrect linear references, especially at high latitudes or for long segments. For a 10 km east-west segment at 60°N latitude, planar calculations can underestimate length by ~50%. Some map projections (e.g., EPSG:3857) yield reasonable results for short, straight segments, but accuracy degrades with segment length and curvature.
+
+If a consumer calculates linear references differently than Overture, attribution or connector positions may be misaligned, potentially causing visual discrepancies on rendered maps or routing failures.
+
+## Edge cases
+
+For very short segments (under 1 meter), floating-point precision may be limited. Treat `at` values near `0.0` or `1.0` as equivalent to endpoints. When a connector does not fall exactly on the geometry, the linear reference corresponds to the closest point on the segment.
diff --git a/docs/guides/transportation/overview.mdx b/docs/guides/transportation/overview.mdx
index bbeb36059..627579a58 100644
--- a/docs/guides/transportation/overview.mdx
+++ b/docs/guides/transportation/overview.mdx
@@ -18,81 +18,32 @@ import ConnectingSegments from '!!raw-loader!@site/src/queries/athena/transporta
import DocCardList from '@theme/DocCardList';
-The Overture transportation theme is the collection of LineString and Point features that describe the infrastructure and conventions of how people and objects travel around the world. The dataset contains two features types: `connector` and `segment`. The three subtypes within `segment` -- `road`, `rail`, and `water` -- contain familiar categories of transportation data: highways, footways, cycleways, railways, ferry routes, and public transportation.
+Every time you ask for directions, hail a ride, or check a map, you're relying on a model of how the world's roads, rails, and waterways connect. The Overture transportation theme is such a model: a global, open dataset of paths people and vehicles travel, built from OpenStreetMap and enhanced with data from TomTom and other local and regional authoritative data sources.
-Most of the data in the transportation theme is sourced from OpenStreetMap. In the `2024-09-18.0` release, we began adding data from TomTom to improve coverage in key areas.
+The dataset is simple at its core — just two feature types, `segment` and `connector` — but expressive enough to capture highway speed limits that change by time of day, one-way streets that allow buses to go the wrong way, and weight-restricted bridges with axle limits. Three subtypes within `segment` cover `road`, `rail`, and `water` transportation.
-You might use the Overture transportation data for:
+The rest of this page covers the feature types and subtypes, describes the dataset and how to access it, and points to tools and libraries for working with the data. The deeper topics are covered in the rest of the guide:
-- **mapping:** rendering a map of connected roads and paths.
-- **routing:** calculating optimal routes from place to place.
-- **navigation:** generating granular instructions on the maneuvers needed to
- follow a route.
-- **analytics:** transportation-related analysis including traffic safety
- analysis and disaster planning.
-- **geocoding:** getting the coordinates of street intersections (geocodes) or
- the street intersection near specific coordinates (reverse geocodes).
+- **[Segments and connectors](./segments-and-connectors):** The building blocks of the network. Segments are the paths; connectors are the junctions where they meet. This page covers how they combine to form a routable graph, along with orientation, heading, and how Overture decides where to split a road.
+- **[Linear referencing](./linear-referencing):** How properties can apply to just *part* of a segment — say, the first 500 meters — without chopping the geometry in two. Includes calculation methods and code examples.
+- **[Scoping and travel modes](./scoping-and-travel-modes):** The rule system that makes properties conditional. A speed limit might apply only to trucks, only on weekdays, or only in the forward direction. Scoping is how all of that gets expressed.
+- **[Roads](./roads):** The details specific to road segments — access restrictions, turn restrictions, speed limits, and more.
-This guide is an overview of the transportation data. To dig into the details of the schema, see the reference documentation for the [segment](/schema/reference/transportation/segment) and [connector](/schema/reference/transportation/connector) feature types.
+You might use Overture transportation data for mapping, routing, navigation, or geocoding street intersections. For the full schema details, see the reference documentation.
-## Dataset description
-All Overture data, including transportation data, is distributed as GeoParquet, a column-based data structure. Below you'll find a table with column-by-column descriptions of the properties in the transportation feature type.
+## Feature types
-
- Schema for GeoParquet files in the transportation theme
-
-
-
+The Overture transportation schema defines two feature types:
-| column | type | description |
-| --- | --- | --- |
-| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
-| geometry | binary | The line representation of the segment's location. Segment's geometry which MUST be a LineSting as defined by GeoJSON schema. |
-| bbox | struct | 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. |
-| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
-| sources | struct | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
-| subtype | string | The broad category of transportation segment. |
-| class | string | Captures the kind of road and its position in the road network hierarchy. |
-| names | struct | Properties defining the names of a feature. |
-| connectors | struct | Array of connector IDs identifying the connectors this segment is physically connected to linearly referenced with their location. 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 which share the same connector. |
-| routes | struct | Routes this segment belongs to. |
-| subclass_rules | struct | Defines the portion of a road that the subclass applies to. |
-| access_restrictions | struct | Rules governing access to this road segment or lane. |
-| level_rules | struct | Defines the Z-order, i.e. stacking order, of the road segment. |
-| destinations | struct | Describes objects that can be reached by following a transportation segment in the same way those objects are described on signposts or ground writing that a traveller following the segment would observe in the real world. This allows navigation systems to refer to signs and observable writing that a traveller actually sees. |
-| prohibited_transitions | struct | Defines where traveling from the segment to another is disallowed for navigation. This covers things situations prohibited turns or a transition from road to bike lane disallowing cars. |
-| road_surface | struct | Defines the surface material on a road such as paved, asphalt, or unpaved. |
-| road_flags | struct | Additional properties relevant to roads such as is_bridge or is_under_construction. |
-| speed_limits | struct | Defines the speed limit of the road segment. |
-| width_rules | struct | Defines the width of the road segment for rendering. |
-| subclass | string | Specifies the usage of a length of road. |
-| rail_flags | struct | Additional properties relevant to rail such as is_tunnel or is_freight. |
-| filename | string | Name of the file being queried. |
-| theme | string | Name of the Overture theme being queried. |
-| type | string | Name of the Overture feature type being queried. |
+- The **segment** type has a LineString geometry that represents the center-line of a path repeatedly traversed by people or objects. Segment properties describe both the physical properties (e.g. road surface and width) and non-physical properties (e.g. access restriction rules) of that path.
+- The **connector** type has a Point geometry that defines the topology of the transportation network by representing the physical connection between two or more segments. Connectors do not have properties beyond geometry and the common properties required for all Overture features.
-
-
-
-| column | type | description |
-| --- | --- | --- |
-| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
-| geometry | binary | The line representation of the segment's location. Segment's geometry which MUST be a LineSting as defined by GeoJSON schema. |
-| bbox | struct | 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. |
-| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
-| sources | struct | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
-| filename | string | Name of the file being queried. |
-| theme | string | Name of the Overture theme being queried. |
-| type | string | Name of the Overture feature type being queried. |
+A more detailed overview of these feature types can be found in [segments and connectors](./segments-and-connectors).
-
-
-
-
+## Subtypes, classes, and subclasses
-### Subtypes
-Transportation segments are divided into three subtypes: **rail**, **water**, and **road**. The road subtype is then further divided into a variety of different classes based on usage captured in the table below.
+Transportation segments are divided into three subtypes: **rail**, **water**, and **road**. These subtypes are further divided into a variety of different classes based on usage captured in the table below.
Class and subclass feature counts
@@ -145,6 +96,62 @@ Transportation segments are divided into three subtypes: **rail**, **water**, an
+## Data dictionary
+
+All Overture data, including transportation data, is distributed as GeoParquet, a column-based data structure. Below you'll find tables with column-by-column descriptions of the properties for the segment and connector feature types.
+
+
+ Data dictionary for the GeoParquet files in the transportation theme
+
+
+
+
+| column | type | description |
+| --- | --- | --- |
+| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
+| geometry | binary | The line representation of the segment's location. Segment's geometry which MUST be a LineSting as defined by GeoJSON schema. |
+| bbox | struct | 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. |
+| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
+| sources | struct | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
+| subtype | string | The broad category of transportation segment. |
+| class | string | Captures the kind of road and its position in the road network hierarchy. |
+| names | struct | Properties defining the names of a feature. |
+| connectors | struct | Array of connector IDs identifying the connectors this segment is physically connected to linearly referenced with their location. 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 which share the same connector. |
+| routes | struct | Routes this segment belongs to. |
+| subclass_rules | struct | Defines the portion of a road that the subclass applies to. |
+| access_restrictions | struct | Rules governing access to this road segment or lane. |
+| level_rules | struct | Defines the Z-order, i.e. stacking order, of the road segment. |
+| destinations | struct | Describes objects that can be reached by following a transportation segment in the same way those objects are described on signposts or ground writing that a traveller following the segment would observe in the real world. This allows navigation systems to refer to signs and observable writing that a traveller actually sees. |
+| prohibited_transitions | struct | Defines where traveling from the segment to another is disallowed for navigation. This covers things situations prohibited turns or a transition from road to bike lane disallowing cars. |
+| road_surface | struct | Defines the surface material on a road such as paved, asphalt, or unpaved. |
+| road_flags | struct | Additional properties relevant to roads such as is_bridge or is_under_construction. |
+| speed_limits | struct | Defines the speed limit of the road segment. |
+| width_rules | struct | Defines the width of the road segment for rendering. |
+| subclass | string | Specifies the usage of a length of road. |
+| rail_flags | struct | Additional properties relevant to rail such as is_tunnel or is_freight. |
+| filename | string | Name of the file being queried. |
+| theme | string | Name of the Overture theme being queried. |
+| type | string | Name of the Overture feature type being queried. |
+
+
+
+
+| column | type | description |
+| --- | --- | --- |
+| id | string | A feature ID. This may be an ID associated with the Global Entity Reference System (GERS) if—and-only-if the feature represents an entity that is part of GERS. |
+| geometry | binary | The line representation of the segment's location. Segment's geometry which MUST be a LineSting as defined by GeoJSON schema. |
+| bbox | struct | 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. |
+| version | integer | Version number of the feature, incremented in each Overture release where the geometry or attributes of this feature changed. |
+| sources | struct | The array of source information for the properties of a given feature, with each entry being a source object which lists the property in JSON Pointer notation and the dataset that specific value came from. All features must have a root level source which is the default source if a specific property's source is not specified. |
+| filename | string | Name of the file being queried. |
+| theme | string | Name of the Overture theme being queried. |
+| type | string | Name of the Overture feature type being queried. |
+
+
+
+
+
+
## Data access and retrieval
Overture's transportation theme data is freely available on both Amazon S3 and Microsoft Azure Blob Storage at these locations:
@@ -164,9 +171,7 @@ Overture's transportation theme data is freely available on both Amazon S3 and M
-## Data usage guidelines
-
-We recommend downloading only the Overture data you need. If you have a particular geographic area of interest, there are several options for using a simple bounding box to extract places data and output a GeoJSON file.
+We recommend downloading only the Overture data you need. If you have a particular geographic area of interest, there are several options for using a simple bounding box to extract data and output a GeoJSON file.
@@ -175,7 +180,7 @@ First, follow the [setup guide for the Python Command-line Tool](/getting-data/o
Set type to either `segment` or `connector` and simply alter the `bbox` value to download a particular area.
```
overturemaps download --bbox=12.46,41.89,12.48,41.91 -f geojson --type=segment -o rome_segments.geojson
-```
+```
First, follow the [setup guide for DuckDB](/getting-data/duckdb/).
@@ -187,7 +192,7 @@ Replace the `bbox.xmin` and `bbox.ymin` values with a new bounding box to run th
-## Data manipulation and analysis
+## Querying transportation data
### Querying by properties in DuckDB
@@ -223,44 +228,41 @@ This example selects all the segments that that connect to the example id.
-
## Tools and libraries
### transportation-splitter
-|  |
-|:--:|
-| *Conceptual diagram of the splitter tool output. The numbers following 1234@ represent start_lr and end_lr values.* |
+|  |
+|:--|
+| *Conceptual diagram of the splitter tool output. The numbers following 1234@ represent start_lr and end_lr values.* |
-The [transportation-spitter tool](https://github.com/OvertureMaps/transportation-splitter) transforms Overture road data into simpler sub segments. It will optionally divide features at each connector point and at each change of a [scoped based property](/schema/reference/core/scoping/linearly_referenced_range), depending on configuration. Depending on your needs and map stack, the resulting dataset may be easier to manipulate than the original Overture data as each segment will only have connections at either end and have one set of properties for its entire length.
+The [transportation-spitter tool](https://github.com/OvertureMaps/transportation-splitter) transforms Overture road data into simpler sub-segments. It will optionally divide features at each connector point and at each change of a [scoped based property](/schema/reference/core/scoping/linearly_referenced_range), depending on configuration. Depending on your needs and map stack, the resulting dataset may be easier to manipulate than the original Overture data as each segment will only have connections at either end and have one set of properties for its entire length.
-Since a GERS ID will no longer be unique with this output, the resulting data will have two additional columns: `start_lr` and `end_lr` which are linear references describing which section of the orginal feature this new segment comes from.
+Since a GERS ID will no longer be unique with this output, the resulting data will have two additional columns: `start_lr` and `end_lr` which are linear references describing which section of the original feature this new segment comes from.
-#### Splitter Example
-To help visualize this process better, here is a real world example of a residential street in OpenStreetMap, Overture, and after being run through the splitter tool.
+#### Splitter example
+To help visualize this process better, here is a real-world example of a residential street in OpenStreetMap, Overture, and after being run through the splitter tool.
|  |
-|:--:|
+|:--|
| In OpenStreetMap this residential road is represented by two different features with the same tags with feature 1 having an additional restricted access tag. |
|  |
-|:--:|
-| In Overture the two segments have been combined into one feature and the restricted access tag has been stored as this linear reference in **access_restrictions**:
-`[{'access_type': allowed, 'when': {'during': , 'heading': , 'using': , 'recognized': [as_private], 'mode': , 'vehicle': }, 'between': [0.521962729, 1.0]}]` |
+|:--|
+| In Overture the two segments have been combined into one feature and the restricted access tag has been stored as this linear reference in **access_restrictions**:
+`[{'access_type': allowed, 'when': {'during': , 'heading': , 'using': , 'recognized': [as_private], 'mode': , 'vehicle': }, 'between': [0.521962729, 1.0]}]` |
-|:--:|
+|:--|
| The splitter has sliced the Overture feature at each connector point for the driveways as well as at the point where the access restriction begins. This results in six unique features in the output all still sharing the same GERS ID. |
-#### More Information and Feedback
+#### More information and feedback
-The tool requires a Spark environment to run and has been tested using Azure Databricks and AWS Glue. For set up information the [transportation-spitter GitHub](https://github.com/OvertureMaps/transportation-splitter) will contain the most up to date information as the tool is in active development still.
+The tool requires a Spark environment to run and has been tested using Azure Databricks and AWS Glue. For setup information the [transportation-spitter GitHub](https://github.com/OvertureMaps/transportation-splitter) will contain the most up-to-date information as the tool is in active development still.
If you have feedback, questions, etc. on the tool you can create an [issue](https://github.com/OvertureMaps/transportation-splitter/issues) on the GitHub.
-
-
diff --git a/docs/guides/transportation/roads.mdx b/docs/guides/transportation/roads.mdx
new file mode 100644
index 000000000..2a0400a04
--- /dev/null
+++ b/docs/guides/transportation/roads.mdx
@@ -0,0 +1,606 @@
+---
+title: Roads
+description: Road-specific properties in the Overture transportation schema
+pagination_label: Roads
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+In the Overture transportation theme, a road is any kind of road, street, or path, including a dedicated path for walking or cycling. (Railways and waterways are separate subtypes in the transportation schema.) Road segments comprise the majority of ground-based transportation segments. Roads are modeled using [segment](/schema/reference/transportation/segment) features with the `subtype` property value set to `road`.
+
+This document describes properties specific to the `road` subtype. For more general information regarding segments, please refer to [segments and connectors](../segments-and-connectors).
+
+## Subclass
+
+The subclass property refines the descriptions of segments by:
+
+- clearly specifying the usage of a length of road, and using linear referencing instead of further segmentation to pinpoint a change in how the road is used
+- properly classifying detailed information from OpenStreetMap
+
+Subclasses require non-overlapping geometries, which will make it easier for routing engines to consume our road data and generate turn-by-turn directions. The class and subclass structures allow us to capture more 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 subclasses, laying the groundwork for richer and more detailed map displays with Overture data.
+
+## Surface
+
+The `road_surface` property of a road indicates its physical surface. If omitted, a reasonable default value should be assumed based on the `class` and `subclass`.
+
+Like many road segment properties, the `road_surface` property supports [geometric scoping](../scoping-and-travel-modes#geometric-scoping-linear-referencing) (linear referencing). Consequently, the effective road surface may vary along different sub-ranges of a road segment's geometry.
+
+
+## Restrictions
+
+### Access restrictions
+
+Access restrictions on a road segment specify who is allowed to use the road, and under what circumstances.
+
+Every road segment has an *implied* set of access restrictions defined by its road class and local rules, norms, and customs. (The Overture transportation schema does not specify these implied access restrictions, which are left to the specific application to resolve.)
+
+The implied access restrictions may be modified for the road segment as a whole by providing an explicit value for the property `access_restrictions`.
+
+It is technically possible to specify a blanket access grant or refusal of access applying to everyone and everything; but where, as is typical, a more precise outcome is needed, one or more [rules](../scoping-and-travel-modes#rules-and-rule-based-properties) will be used to specify access restrictions. As with all rule-based properties, if no rule matches the specific facts, then the default restrictions for the road class govern.
+
+
+
+
+```yaml
+id: access-restrictions-segment-blanket
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [0, 0]
+ - [0, 1]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: residential
+ access_restrictions:
+ - access_type: denied
+```
+
+
+
+
+
+```yaml
+id: access-restrictions-segment-private-with-deliveries
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [0, 0]
+ - [0, 1]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: residential
+ access_restrictions:
+ - access_type: denied
+ - access_type: allowed
+ when: { recognized: [as_private] }
+ - access_type: allowed
+ when:
+ using: [to_deliver]
+ during: Mo-Fr 08:30-16:30
+```
+
+
+
+
+
+```yaml
+id: access-restrictions-segment-motor-vehicles-destination-only
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [0, 0]
+ - [0, 1]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: residential
+ access_restrictions:
+ - access_type: denied
+ when: { mode: [motor_vehicle] }
+ - access_type: allowed
+ when: { using: [at_destination] }
+```
+
+
+
+
+
+```yaml
+id: access-restrictions-segment-axle-limit
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [0, 0]
+ - [0, 1]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: motorway
+ access_restrictions:
+ - access_type: denied
+ when:
+ mode: [hgv]
+ vehicle:
+ - dimension: axle_count
+ comparison: greater_than_equal
+ value: 5
+```
+
+
+
+
+### Turn restrictions
+
+Turn restrictions on a road segment limit the transitions which are allowed from that segment into other [physically connected](../segments-and-connectors#physical-connectivity) segments.
+
+Every road segment has an implied set of allowed transitions defined by its [access restrictions](#access-restrictions) as well as local rules, norms, and customs. An example of a transition restriction implied by an access restriction: if the segment can only be used along the `forward` [heading](../segments-and-connectors#heading), then it is implied that no transitions are allowed to any connected segments if travelling along the `backward` heading. An example of a transition restriction implied by a local rule or norm would be a blanket prohibition on U-turns in a given jurisdiction.
+
+Overture takes a permissive-by-default approach to transition restrictions. By default, all implied transitions are allowed. The set of allowed transitions may be reduced by adding explicit transition restrictions in the `prohibited_transitions` property.
+
+Turn restrictions come in two flavors: **simple** and **via**. A simple turn restriction allows a simple regulation to be stated, such as "No right turn onto Elm Street"; a via restriction covers more elaborate cases where the sequence of maneuvers is important.
+
+
+
+
+
+
+
+
+
+
+
+
+*Prohibited right turn from "source" to "target" segment at connector 2.*
+
+
+
+
+
+
+
+
+
+
+Source segment
+```yaml
+id: overture:transportation:example:simple-turn-restriction-source
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [-113.57822030759499, 50.01868388494378]
+ - [-113.57831482025354, 50.018860947117304]
+ - [-113.57851814418316, 50.01923724443006]
+properties:
+ theme: transportation
+ type: segment
+ version: 5
+ subtype: road
+ class: secondary
+ connectors:
+ - connector_id: overture:transportation:example:via-turn-restriction-connector1
+ at: 0
+ - connector_id: overture:transportation:example:via-turn-restriction-connector2
+ at: 1
+ prohibited_transitions:
+ - sequence:
+ - segment_id: overture:transportation:example:simple-turn-restriction-target
+ connector_id: overture:transportation:example:simple-turn-restriction-connector2
+ final_heading: forward
+ when: {heading: forward}
+```
+
+
+
+Connector 1
+
+*This connector is not an important part of the example, since it does
+not participate in the turn restriction, but it is included to bring
+real-world context to the example.*
+
+```yaml
+id: overture:transportation:example:simple-turn-restriction-connector1
+type: Feature
+geometry:
+ type: Point
+ coordinates: [-113.57831482025354, 50.018860947117304]
+properties:
+ theme: transportation
+ type: connector
+ version: 0
+```
+
+
+
+Exit segment
+
+*This segment is not an important part of the example, since all implied
+transitions are allowed on it. We include it to bring real-world context
+to the example.*
+
+```yaml
+id: overture:transportation:example:simple-turn-restriction-exit
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [-113.57831482025354, 50.018860947117304]
+ - [-113.5783121688577, 50.019016827708754]
+ - [-113.57829228338763, 50.019079861246865]
+ - [-113.57826444373009, 50.019121599625294]
+ - [-113.57816369068271, 50.01919400284882]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: secondary
+ connectors:
+ - connector_id: overture:transportation:example:via-turn-restriction-connector1
+ at: 0
+ - connector_id: overture:transportation:example:via-turn-restriction-connector2
+ at: 1
+```
+
+
+
+
+Connector 2
+
+*The right turn from the source segment (`forward` heading) to the
+target segment (`forward` heading) is prohibited at this connector.*
+
+```yaml
+id: overture:transportation:example:simple-turn-restriction-connector2
+type: Feature
+geometry:
+ type: Point
+ coordinates: [-113.57851814418316, 50.01923724443006]
+properties:
+ theme: transportation
+ type: connector
+ version: 1
+```
+
+
+
+Target segment
+
+*Traffic heading `forward` on the source segment may not enter this
+segment heading `forward`, i.e. the right turn from the source segment
+to this segment is prohibited.*
+
+```yaml
+id: overture:transportation:example:simple-turn-restriction-target
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [-113.57851814418316, 50.01923724443006]
+ - [-113.57837460847787, 50.01919574268962]
+ - [-113.57812342099429, 50.01919343703648]
+ - [-113.57803729957116, 50.01923263312719]
+ - [-113.57766410673773, 50.01923263312719]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: secondary
+ connectors:
+ - connector_id: overture:transportation:example:via-turn-restriction-connector1
+ at: 0
+ - connector_id: overture:transportation:example:via-turn-restriction-connector2
+ at: 1
+```
+
+
+
+Connector 3
+
+*This connector is not an important part of the example, since it does
+not participate in the turn restriction, but it is included to bring
+real-world context to the example.*
+
+```yaml
+id: overture:transportation:example:simple-turn-restriction-connector3
+type: Feature
+geometry:
+ type: Point
+ coordinates: [-113.57816369068271, 50.01919400284882]
+properties:
+ theme: transportation
+ type: connector
+ version: 1
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+*Prohibited transition from "source" to "target" through `via` segment.*
+
+
+
+
+
+
+
+
+
+
+
+
+### Speed limits
+
+Speed limits restrict the speed at which travel is permitted on a road. Typically speed limits specify maximum allowed speeds, but the Overture schema also allows minimum speed limits to be set and variable speed corridors to be indicated.
+
+Every road segment has an implied speed limit or set of speed limits defined by its road class and local rules, norms, and customs. As with access and turn restrictions, the Overture transportation schema does not attempt to specify these implied speed limits.
+
+The implied speed limits may be configured for the whole road segment by providing an explicit value for the property `speed_limits`.
+
+As with access restrictions and turn restrictions, speed limits can be specified using [rules](../scoping-and-travel-modes#rules-and-rule-based-properties).
+
+
+
+
+```yaml
+id: speed-limits-simple
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [-123.09348187774302, 49.280278741717865]
+ - [-123.0895720621171, 49.280195795155265]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: residential
+ speed_limits:
+ - max_speed:
+ value: 30
+ unit: km/h
+```
+
+
+
+
+
+```yaml
+id: speed-limits-variable-max
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [0, 0]
+ - [0, 1]
+properties:
+ theme: transportation
+ type: segment
+ version: 2
+ subtype: road
+ class: secondary
+ speed_limits:
+ - max_speed: {value: 70, unit: "mph"}
+ - when:
+ mode: [hgv]
+ heading: forward
+ max_speed: {value: 65, unit: "mph"}
+```
+
+
+
+
+
+```yaml
+id: speed-limits-variable-max
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [-123.12895930023527, 50.007761789070344]
+ - [-123.12637500433082, 50.00945836227345]
+ - [-123.12506896231434, 50.011762034223324]
+ - [-123.12415195409014, 50.01351203677902]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: motorway
+ speed_limits:
+ - max_speed:
+ value: 100
+ unit: km/h
+ is_max_speed_variable: true
+```
+
+
+
diff --git a/docs/guides/transportation/scoping-and-travel-modes.mdx b/docs/guides/transportation/scoping-and-travel-modes.mdx
new file mode 100644
index 000000000..2d9ce2980
--- /dev/null
+++ b/docs/guides/transportation/scoping-and-travel-modes.mdx
@@ -0,0 +1,406 @@
+---
+title: Scoping Rules and Travel Modes
+description: How property values are constrained by location, time, and subject in the transportation schema
+pagination_label: Scoping Rules and Travel Modes
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+In the real world, many facts and rules affecting entities have only a partial application, meaning they don't apply everywhere, or they don't apply at all times, or to everyone, or to all sets of external conditions. For example, access restrictions on a road segment might not apply to all people or all kinds of vehicles, or they might vary according to the day of the week.
+
+The Overture schema uses two related concepts to capture the partial application of facts and rules: **scoped values** and **rule-based properties**.
+
+## Scoped values and scoping properties
+
+A *scoped* value is a value which only applies within a limited scope. Most scoped values are rules in the rule lists of [rule-based properties](#rules-and-rule-based-properties). However, scoped values also exist outside of rule-based properties. For example, a `destinations` property belonging to a road segment might be geometrically scoped to its position along the road.
+
+The scope in which a scoped value applies is controlled by one or more special child properties of the value known as *scoping* properties.
+
+### Geometric scoping (linear referencing)
+
+
+
+
+The geometric scoping properties `at` and `between` limit the scope of their parent value to a position or range of positions, respectively, along a segment's geometry. When the parent value is a rule object, the rule only matches the position or range of positions specified in the `at` or `between` property.
+
+The value of the `at` property is a single real number `a` where `0` ≤ `a`
+≤ `1`. It represents a discrete position along the segment's geometry. The
+value of the `between` property is a pair of numbers `[a, b]` where `0` ≤
+`a` < `b` ≤ `1`. It represents a range of positions along the segment's
+geometry. The numbers `a` and `b` are interpreted as percentage displacements
+along the parent segment's geometry starting from the start of the segment.
+(*The terms "start" and "end" are explained in
+[segments and connectors](../segments-and-connectors#start-end-and-orientation).*)
+
+So, for example, the scoping property `"at": 0.15` scopes its parent value
+to the position on the segment that is displaced 15% of the segment length from
+the start.
+
+
+
+
+
+
+
+*The position along the segment geometry described by `"at": 0.15`.*
+
+
+
+
+The scoping property `"between": [0.35, 0.75]` scopes its parent value to the range of positions on the segment beginning at 35% and extending to 75% of the segment length from the start.
+
+
+
+
+ *The range on the segment geometry described by `"between": [0.35, 0.75]`.*
+
+
+
+
+
+ The example below shows a road segment whose speed limit is defined by two geometrically-scoped speed limit rules:
+ ```yaml
+id: overture:transportation:example:geometric-scoping
+type: Feature
+geometry:
+ type: LineString
+ coordinates: [[0, 0], [1, 1]]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: primary
+ speed_limits:
+ - between: [0, 0.15]
+ max_speed:
+ value: 100
+ unit: km/h
+ - between: [0.15, 1]
+ max_speed:
+ value: 60
+ unit: km/h
+```
+
+
+
+For details on how linear references are calculated, see the [linear referencing](../linear-referencing) guide.
+
+### Temporal scoping (opening hours)
+
+
+
+
+The temporal, or time-based, scoping construct `when: { during: "..." }` limits the scope of its parent value to one or more recurring time ranges. When the parent value is a rule object, the rule only matches the time range or time ranges specified in the `during` property.
+
+The `during` property must contain a string expressed in the OpenStreetMap
+[opening hours specification](https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification).
+
+
+
+
+The example below shows a road segment with a temporally-scoped access restriction rule. The rule states that non-bus travellers are prohibited from access to the segment on weekdays between 3PM and 6PM.
+
+```yaml
+id: overture:transportation:example:temporal-scoping
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [-122.90019762265949, 49.20784664905824]
+ - [-122.9003738558948, 49.207833436710956]
+ - [-122.90052986564378, 49.207871186265805]
+properties:
+ theme: transportation
+ type: segment
+ version: 2
+ subtype: road
+ class: unknown
+ access_restrictions:
+ - access_type: denied
+ when:
+ mode: [bus]
+ during: "Mo-Fr 15:00-18:00"
+```
+
+
+
+
+### Subjective scoping
+
+Subjective scoping means that the scope of a property can be constrained based on subjective factors like *who* or *what* is travelling on the transportation network, or *how* they are doing it.
+
+The Overture transportation schema supports several subjective factors:
+
+#### Travel-mode scoping
+
+A travel mode is a way of moving about the transportation network, for example driving in a motor vehicle, or, more specifically, driving in a high-occupancy vehicle.
+
+The property construct `when: { mode: [...] }` limits the scope of its parent value to apply only to people or things travelling using the listed travel modes. See [travel modes](#travel-modes) below for more detail.
+
+#### Heading
+
+
+
+
+Heading scoping limits the scope of a parent value to apply only when the traveller is proceeding along the segment geometry in the named direction, either `forward` or `backward`. (*The directions `forward` and `backward` are defined in [segments and connectors](../segments-and-connectors#heading).*)
+
+The property construct `when: { heading: forward|backward }` applies heading scoping to a parent value.
+
+
+
+
+The example below shows a road segment with multiple heading-scoped access restriction rules. The rules allow all standard travel modes for the segment class to travel in the forward direction, but only allow buses to travel in the backward direction.
+
+```yaml
+id: overture:transportation:example:subjective-heading-scoping
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [-1.3023158, 54.5579329]
+ - [-1.3020090, 54.5577898]
+ - [-1.3014511, 54.5575155]
+ - [-1.3009618, 54.5572737]
+ - [-1.3004518, 54.5570288]
+ - [-1.3003009, 54.5569580]
+properties:
+ theme: transportation
+ type: segment
+ version: 2
+ subtype: road
+ class: primary
+ access_restrictions:
+ - access_type: denied
+ when: { heading: backward }
+ - access_type: allowed
+ when:
+ heading: backward
+ mode: [bus]
+```
+
+
+
+
+#### Purpose of use scoping
+
+
+
+
+Usage purpose scoping limits the scope of a parent value to apply only when the user is using the feature for one of the listed purposes. This type of scoping is common when it matters that a person is in the process of doing something like making a delivery or acting as the customer of a business.
+
+The property construct `when: { using: [...] }` applies usage purpose scoping to a parent value.
+
+
+
+
+The example below shows a road segment representing a hotel driveway where through traffic is not permitted (only usage by hotel customers or as a final destination is allowed):
+
+ ```yaml
+id: overture:transportation:example:subjective-usage-purpose-scoping
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [-123.12700676422021, 49.279826628301635]
+ - [-123.12680748254229, 49.27995121574301]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: tertiary
+ access_restrictions:
+ - access_type: denied
+ - access_type: allowed
+ when: { using: [as_customer, at_destination] }
+```
+
+
+
+
+#### Status scoping (membership in a recognized group)
+
+
+
+
+Status scoping limits the scope of a parent value to apply only when the user has a certain recognized status or is a member of a recognized group. This type of scoping is useful when it matters whether a person or thing has a recognized characteristic, such as holding a permit or being an employee of a business or student at an academic institution.
+
+The property construct `when: { recognized: [...] }` applies status scoping to a parent value.
+
+
+
+
+The example below shows a road segment modeling a private condominium tower driveway where access is denied to the general public, but allowed to privately-authorized individuals, such as condo unit owners:
+
+```yaml
+id: overture:transportation:example:subjective-status-scoping
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [-123.12791513926058, 49.287502049554945]
+ - [-123.12795068403449, 49.287522915661725]
+ - [-123.12797769806272, 49.28756882106529]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: tertiary
+ access_restrictions:
+ - access_type: denied
+ - access_type: allowed
+ when: { recognized: [as_private] }
+```
+
+
+
+
+### Vehicle attributes scoping
+
+
+
+
+Vehicle attribute scoping limits the scope of a parent value to apply only when the vehicle in use meets certain criteria.
+
+The property construct `when: { vehicle: [{ dimension: ..., comparison: ..., value: ... }] }` applies vehicle attributes scoping to a parent value.
+
+Note that vehicle attribute scoping can overlap to some degree with [travel mode scoping](#travel-mode-scoping). For example, some access rules may be scoped to the travel mode "heavy goods vehicle", while another equivalent access rule could be scoped to the vehicle attribute "gross vehicle weight."
+
+
+
+
+```yaml
+id: overture:transportation:example:subjective-vehicle-attributes-scoping
+type: Feature
+geometry:
+ type: LineString
+ coordinates:
+ - [-123.12791513926058, 49.287502049554945]
+ - [-123.12795068403449, 49.287522915661725]
+ - [-123.12797769806272, 49.28756882106529]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: residential
+ access_restrictions:
+ - access_type: denied
+ when:
+ vehicle:
+ - dimension: weight
+ comparison: greater_than
+ value: 23
+ unit: 't'
+```
+
+
+
+
+
+## Rules and rule-based properties
+
+A *rule-based* property is a property whose value in a given situation is determined by evaluating a list of rules against the facts applicable to that situation. Each individual rule in the list of rules is itself a scoped value, and the assessment of which rule applies to a given set of facts is done by the rule evaluation algorithm.
+
+### Absolute form
+
+There are cases when specifying a property value using rules makes sense, and cases where doing so is unnecessarily complicated because the real-world entity being modeled has a single unchanging state which is the same in all fact situations. In these cases, most rule-based properties support a simpler absolute form without a list of rules.
+
+### Rule evaluation algorithm
+
+Given a rule-based property, the actual value of the property in a given fact pattern is determined by a three-step process: first, all matching rules are identified; second, the single determining rule is chosen if possible; lastly, if there is no applicable rule, an appropriate default value may be assumed.
+
+1. **Matching rules.** For a given rule and a given set of facts, the rule *matches* the facts if the scope of the rule contains all the facts, *i.e.* the facts fit within all of the scoping properties expressed in the rule. The matching criteria for a rule can be thought of as the logical AND of all the scoping properties expressed in the rule.
+2. **Determining rule.** For a given rule-based property and a given set of facts, *at most* one rule can *determine* the property value. If only one rule matches, that rule determines the property value. If more than one rule matches, the last matching rule in the list determines the value. (This is similar to how OpenStreetMap [conditional restrictions](https://wiki.openstreetmap.org/wiki/Conditional_restrictions) are evaluated.) Therefore it is important to write more general rules before more specific ones in a rule list.
+3. **Fallback to default.** If there are no matching rules, an appropriate default value may apply, depending on the property being evaluated.
+
+## Travel modes
+
+In the real world, a travel mode can be thought of intuitively as a way of getting from point A to point B. Travel modes can include non-vehicle modes (foot), vehicle modes (a bicycle or motor vehicle), and occasionally more granular details, e.g. a motor vehicle classified as a high occupancy vehicle or a heavy goods vehicle.
+
+Within the Overture transportation theme schema model, a travel mode is a recognized mode by which a person or thing may use a [segment](/schema/reference/transportation/segment) feature.
+
+### Implied travel modes
+
+Every segment has an *implied* set of travel modes that are allowed to use the segment. For [road](../roads) segments, this implied set derives from the road class, as well as local rules, norms, and customs operative where the road segment is situated.
+
+Since this implied set depends on locality or jurisdiction, and is susceptible of varying over time, the Overture transportation schema does not try to specify the implied set. Resolution of the implied set is done by the specific application in the case where this level of detail is important for its proper functioning. An accurate routing engine may need this information, whereas a 2D map render or a geocoder likely do not.
+
+### General definitions
+
+Overture's recognized travel modes are defined in general terms that are broadly applicable. For example, `hov` is a high-occupancy vehicle and `hgv` is a heavy goods vehicle. In most jurisdictions, these general terms map to a concept that is in use within the jurisdiction, even though the local name for the concept may vary.
+
+Despite being broadly applicable, travel modes may have different definitions in different places and at different times:
+
+- in one jurisdiction, an `hgv` might mean any vehicle with a gross vehicle weight in excess of 3.5 tonnes (3,500 kg). In another place, an `hgv` might have a gross vehicle weight of at least 10,001 lbs.
+- in one jurisdiction, an `hov` might require a minimum of 2 passengers while in another place it might have a higher minimum passenger count, or include battery-electric vehicles, or exclude certain classes of vehicle or usage.
+
+As a consequence of the variance in definition across place and time, Overture gives only general definitions for travel modes, leaving precise definition to those applications that require them.
+
+### Travel mode scoping in the schema
+
+#### The `mode` scoping property
+
+The scoping property `mode` controls whether a given scoped property applies when a given travel mode is being used for traveling along a road segment.
+
+If `mode` is provided, it must be a non-empty array of string values identifying travel modes, and is interpreted as a set. Values must be unique, but order is not important.
+
+#### Vehicle attribute scoping: `vehicle`
+
+Because travel modes are a fuzzy concept, there are inevitably areas of overlap with the more precise, but more limited, `vehicle` scoping property which is used for [vehicle attributes scoping](#vehicle-attributes-scoping). Where there is potential overlap, the method of scoping used in Overture data releases will depend on how the upstream data source has expressed the equivalent concept. Where there is choice, it is preferable to select the scoping method that most accurately reflects the intention expressed on local signage.
+
+#### Similar scoping properties: `using` and `recognized`
+
+The scoping properties `using` and `recognized` express concepts that are meant to be orthogonal to (completely separate from) travel modes:
+
+- The `using` property indicates [purpose of use](#purpose-of-use-scoping) scoping, which relates to the purpose for which the person or thing travelling is using a given segment of the transportation network. Travel modes should ideally not embed a purpose of use.
+- The `recognized` property indicates [status scoping](#status-scoping-membership-in-a-recognized-group), which relates to a recognized status given to the person or thing traveling, where the recognized status is distinct from the mode of travel itself. Travel modes should ideally not embed a status.
+
+### The travel modes taxonomy
+
+Travel modes in Overture form a shallow taxonomy. Some travel modes are more general, while others are more specific, and a more general travel mode may contain a more specific one. For example, the general travel mode `vehicle` contains the more specific mode `motor_vehicle`.
+
+
+
+
+
+
+
+
+
+
+
+
+
+*The Overture travel modes taxonomy.*
+
+
+
+
+
+
+
+As many of the above travel modes draw on the body of knowledge accumulated in relation to OpenStreetMap [transport mode access restrictions](https://wiki.openstreetmap.org/wiki/Key:access#Transport_mode_restrictions), Overture Maps would like acknowledge an intellectual debt to the OSM community in relation to travel modes as well as to other aspects of the transportation schema.
diff --git a/docs/guides/transportation/segments-and-connectors.mdx b/docs/guides/transportation/segments-and-connectors.mdx
new file mode 100644
index 000000000..d367271ba
--- /dev/null
+++ b/docs/guides/transportation/segments-and-connectors.mdx
@@ -0,0 +1,469 @@
+---
+title: Segments and Connectors
+description: Shape, connectivity, and linear referencing in the transportation schema
+pagination_label: Segments and Connectors
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import ThemedImage from '@theme/ThemedImage';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+In the Overture transportation theme, features with their `type` property set to `segment` represent **paths repeatedly traversed by people or objects**. For example, a segment may represent a major highway, an abandoned subway line, or a ferry route. The `connector` feature type carries point geometry which describes a location where a physical connection between two or more segments occurs.
+
+Together, segments and connectors capture the shape and connectivity of the transportation network.
+
+
+
+## Connectors
+
+The [connector](/schema/reference/transportation/connector) feature type carries point geometry representing a location where a physical connection between two or more segments occurs (or may occur in the future). Connectors have no properties apart from geometry and standard Overture feature properties. All other aspects of the transportation theme are modeled on segments.
+
+To better support routing use cases, the `segment` feature type has a 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 where there is a possibility to transition to other segments that share the same connector.
+
+Here's an example of how the connectors property is modeled in the schema:
+
+```yaml
+id: overture:transportation:segment:123
+type: Feature
+geometry:
+ type: LineString
+ coordinates: [[0, 0], [0.03, 0], [0.10, 0]]
+properties:
+ theme: transportation
+ type: segment
+ version: 1
+ subtype: road
+ class: secondary
+ connectors:
+ - connector_id: fooConnector
+ at: 0
+ - connector_id: barConnector
+ at: 0.3
+ - connector_id: bazConnector
+ at: 1
+ road_surface:
+ - value: paved
+```
+
+### Physical connectivity
+
+Two or more segments are physically connected at a given connector if each segment's connectors property contains a reference to the connector.
+
+The connector geometry's coordinates should preferably be contained within the segment geometry's coordinates, in which case the connector coordinates define the point of physical connection. This constraint will always be met by official Overture data releases. Where this is not possible, the point of physical connection is the closest point to the connector coordinates which intersects the segment geometry.
+
+Conversely, two segments are **not** physically connected if their connectors properties do not reference a shared connector, even if their geometries overlap or even share a coordinate in common.
+
+Travel from a point on one segment to a point on another physically-connected segment is allowed, unless limited by an explicit restriction such as an access or turn restriction.
+
+All segments in official Overture transportation data releases have a minimum of two connectors, one at each end of the geometry, even if those endpoint connectors are not attached to any other segment. This is done to allow new segments to connect into the existing network without needing to change the properties of existing segments.
+
+## Segments
+
+The [segment](/schema/reference/transportation/segment) feature type carries `LineString` geometry which describes the physical shape of a section of the transportation network. A segment may represent an entity with a tangible real-world existence, such as a paved road, or it may represent an intangible entity, such as a ferry route, which has a well-known shape but no observable presence in the real world.
+
+### Subtypes
+
+Because of their many possible uses, the segment `type` is further organized by its `subtype`, `class`, and `subclass` properties. Currently, the Overture transportation theme supports three segment subtypes:
+
+| Subtype | Description | % of total segment length |
+|---------|-------------|---------------------------|
+| [`road`](../roads) | Roads and footpaths | ~97% |
+| `rail` | Any transit system in which vehicles ride on metal rails | ~3% |
+| `water` | Shipping lanes and ferry routes | <1% |
+
+### Geometry
+
+A segment's geometry approximates the physical centerline of the section of path it models. For roads, information regarding the width of this path is captured in the `width_rules` road-specific property.
+
+### Class
+
+The `class` property of a segment specifies its general purpose of use within its subtype. Unlike many segment properties, a segment's `class` property does not support [geometric scoping](../scoping-and-travel-modes#geometric-scoping-linear-referencing) (linear referencing). Consequently, whenever a linear range of real-world road or rail makes a class transition (for example, between secondary and residential roads), the Overture transportation segmentation algorithm will generate a segment split.
+
+Currently, **only roads and railways have the `class` property**. Within these subtypes, every segment has a class. If the `class` property is missing from a segment's source dataset, the `class` for that segment will be given default value `unknown`, indicating the class is undetermined and may be updated in a later release.
+
+### Flags
+
+A segment's flags (`road_flags` for roads, `rail_flags` for rails) are a set of named flag values indicating the presence or absence of simple physical characteristics. For example, a road segment with `road_flags = [is_link, is_under_construction]` is a link segment that is physically under construction.
+
+Like many segment properties, the `road_flags`/`rail_flags` property supports [geometric scoping](../scoping-and-travel-modes#geometric-scoping-linear-referencing). Consequently, the applicable flags may vary along different sub-ranges of a road segment's geometry.
+
+**Here's an example of how classes, subclasses, and flags are modeled in the Overture schema:**
+
+```yaml
+class: footway
+subclass_rules:
+ - value: sidewalk
+ between: [0, 0.6]
+ - value: crosswalk
+ between: [0.6, 1.0]
+road_flags:
+ - values: [is_bridge]
+ between: [0.2, 0.3]
+ - values: [is_under_construction]
+ between: [0.3, 0.5]
+
+class: service
+subclass_rules:
+ - value: driveway
+ between: [0, 0.5]
+
+class: primary
+subclass: link
+subclass_rules:
+ - value: link
+```
+
+### Granularity
+
+Occasionally, a real-world feature admits different representations at different granularities. For example, a dual carriageway may be modeled as one segment, or two parallel segments. Segments support modeling the transportation network at a range of granularities. A single segment can represent a bidirectional street including all of its sidewalks, a single sidewalk, two parallel subway tracks, a one-way street, or one direction of a dual carriageway.
+
+### Start, end, and orientation
+
+The first coordinate in a segment's geometry is the **start** of the segment and the last coordinate is the **end**. A segment is oriented away from the start and toward the end.
+
+
+
+*This segment geometry is oriented due east.*
+
+
+
+
+
+
+
+
+
+
+### Heading
+
+Travel along a segment's geometry can follow one of two possible headings: **forward** or **backward**. The forward heading proceeds toward the end of the segment; while the backward heading proceeds back toward the start of the segment.
+
+
+
+
+
+
+
+
+
+*Travel heading along a segment.*
+
+
+
+
+
+
+### Level (Z-order)
+
+Segment geometry is two-dimensional. In the real, 3D, world, however the entities represented by segments can be above or below each other, as may happen with tunnels, bridges, overpasses, and stacked multi-level highway interchanges. To accurately render top-down 2D maps, it is important to know the relative stacking order, or Z-order, of segments.
+
+Segment Z-order is given by the `level` property. A `level` value of `0` indicates visual level, with positive numbers indicating above visual level, negative numbers indicating below visual level, and in general, a lesser number indicating a lower position in the stacking order than a greater number.
+
+
+
+Note that two segments with different `level` values may be physically connected, since `level` is an approximation for rendering and is not meant be a precise indication of elevation at different points along the segment.
+
+### Destinations
+
+The `destinations` property in the segment feature type supports routing use cases. It describes the transitions from one segment to another on the way to a specified location. In turn-by-turn routing applications, this is what is known as "follow signs for" — the human-readable directions and signposts along a road, highway, or interstate that get us from point A to point Z, by way of any number of paths in between. The `destinations` property has a flexible schema that will allow us to capture and model navigation data from many different sources.
+
+## Linear referencing
+
+Properties on a segment can vary along its length using normalized positions from `0.0` (start) to `1.0` (end), a technique called linear referencing. For full details on how linear references work, including calculation methods, code examples, and edge cases, see the [linear referencing](../linear-referencing) guide.
+
+## Segmentation
+
+The term segmentation describes the process of converting upstream source data into Overture transportation shape and connectivity data modeled as segments and connectors.
+
+### Shape stability
+
+A primary goal of Overture's segmentation process is to promote stability of segment shape across Overture data releases. For example, if a certain real-world stretch of Main Street is represented by a single segment with particular geometry in release 1, we will strive to avoid slicing the exact same geometry up into two, three, or four segments in release 2.
+
+Aiming for segment shape stability categorically does not mean that Overture aims for a stable transportation dataset. On the contrary, we aim to continuously improve data accuracy and coverage, and expect the transportation network dataset to constantly evolve and grow as a result. Our goal is simply to minimize unnecessary, semantically meaningless, changes in how the geometry is sliced into segments across data releases.
+
+Several features of the transportation theme schema were designed to allow the segmentation process to achieve its segment stability goal. These features include:
+
+- [interior connectors](#interior-connectors)
+- [geometrically scoped](#geometric-scoping) segment properties
+
+### ID stability
+
+Overture pursues shape stability to improve the ability to assess whether two segments from different points in time (or from different upstream data sources) represent the same real-world entity. Overture's success at this assessment directly feeds into the stability and precision of [GERS IDs](https://docs.overturemaps.org/gers) assigned to segments. In turn, higher GERS ID stability and precision makes transportation theme data more useful for conflation.
+
+### Interior connectors
+
+A key feature of the Overture transportation schema which enables shape stability is the ability of segments to support connectors at interior positions along their geometry, not only at their endpoints. The ability to add internal connectors prevents the segmentation process from having to blindly follow every split or join introduced in upstream source data.
+
+For example, imagine a square city block bordered by road on all four sides has been mapped in the source data, but a back alley dividing the block along the east-west axis has not. If the back alley is subsequently mapped in the source data, the Overture segmentation process can connect to the transportation network without having to subdivide any existing segments by simply introducing internal connectors on the north-south road segments bordering the block to the east and west. As a result, the [Overture IDs](https://docs.overturemaps.org/gers) of the north-south road segments remain as they were and no data needs to be re-conflated.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+*A square city block bordered by four roads before (left) and after (right) mapping the back alley using internal connectors.*
+
+
+
+
+
+
+
+Note that in the above example, an official Overture data release would insert coordinates in the middle of the north-south segments, if they did not already exist, because Overture data releases will always ensure that every segment's geometry includes all of its connectors.
+
+### Geometric scoping
+
+Many segment properties may include a linear reference so that they apply only to a part of the segment geometry. We refer to these linearly-referenced property values as being geometrically scoped and discuss geometric scoping at greater length in the page on [scoped properties](../scoping-and-travel-modes).
+
+Geometric scoping allows the segmentation algorithm to avoid introducing segment splits simply because a certain property has different values along different parts of the geometry. Like interior connectors, geometrically-scoped properties enable the segmentation process to make decisions that promote shape stability, ultimately resulting in more precise and stable [Overture IDs](https://docs.overturemaps.org/gers) and less churn in conflated data.
+
+
+
+### Loops
+
+Although it is technically possible to use the Overture schema to express a segment forming a connected loop, such loops are considered invalid and will never be produced by the segmentation algorithm.
+
+An illegal loop where one end of a segment connects to the other end can be corrected by splitting the segment and introducing a second connector to maintain physical connectivity. An illegal self-crossing loop of degree *N* can be corrected by splitting the segment into N pieces.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+*An illegal loop connected at its endpoints (left) and a possible correction (right).*
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+*An illegal self-crossing loop (left) and a possible correction (right).*
+
+
+
+
+
+
+
+
+
diff --git a/sidebars.js b/sidebars.js
index bfb976b36..dff2578f5 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -99,6 +99,10 @@ const sidebars = {
collapsed: true,
items: [
'guides/transportation/overview',
+ 'guides/transportation/segments-and-connectors',
+ 'guides/transportation/scoping-and-travel-modes',
+ 'guides/transportation/linear-referencing',
+ 'guides/transportation/roads',
],
},
],
diff --git a/static/img/transportation/geometric-scoping-position-dark.png b/static/img/transportation/geometric-scoping-position-dark.png
new file mode 100644
index 000000000..1000351ea
Binary files /dev/null and b/static/img/transportation/geometric-scoping-position-dark.png differ
diff --git a/static/img/transportation/geometric-scoping-position-dark.svg b/static/img/transportation/geometric-scoping-position-dark.svg
deleted file mode 100644
index 2bd5a8c0c..000000000
--- a/static/img/transportation/geometric-scoping-position-dark.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/static/img/transportation/geometric-scoping-position-light.png b/static/img/transportation/geometric-scoping-position-light.png
new file mode 100644
index 000000000..afcd94460
Binary files /dev/null and b/static/img/transportation/geometric-scoping-position-light.png differ
diff --git a/static/img/transportation/geometric-scoping-position-light.svg b/static/img/transportation/geometric-scoping-position-light.svg
deleted file mode 100644
index e38dabb85..000000000
--- a/static/img/transportation/geometric-scoping-position-light.svg
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/static/img/transportation/geometric-scoping-range-dark.png b/static/img/transportation/geometric-scoping-range-dark.png
new file mode 100644
index 000000000..bf29bcc09
Binary files /dev/null and b/static/img/transportation/geometric-scoping-range-dark.png differ
diff --git a/static/img/transportation/geometric-scoping-range-dark.svg b/static/img/transportation/geometric-scoping-range-dark.svg
deleted file mode 100644
index da7be3df1..000000000
--- a/static/img/transportation/geometric-scoping-range-dark.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/static/img/transportation/geometric-scoping-range-light.png b/static/img/transportation/geometric-scoping-range-light.png
new file mode 100644
index 000000000..9c1499598
Binary files /dev/null and b/static/img/transportation/geometric-scoping-range-light.png differ
diff --git a/static/img/transportation/geometric-scoping-range-light.svg b/static/img/transportation/geometric-scoping-range-light.svg
deleted file mode 100644
index b125d400f..000000000
--- a/static/img/transportation/geometric-scoping-range-light.svg
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/static/img/transportation/heading-dark.png b/static/img/transportation/heading-dark.png
new file mode 100644
index 000000000..597788cc1
Binary files /dev/null and b/static/img/transportation/heading-dark.png differ
diff --git a/static/img/transportation/heading-dark.svg b/static/img/transportation/heading-dark.svg
deleted file mode 100644
index 0c51c2feb..000000000
--- a/static/img/transportation/heading-dark.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/static/img/transportation/heading-light.png b/static/img/transportation/heading-light.png
new file mode 100644
index 000000000..fac3845c0
Binary files /dev/null and b/static/img/transportation/heading-light.png differ
diff --git a/static/img/transportation/heading-light.svg b/static/img/transportation/heading-light.svg
deleted file mode 100644
index 5342146c8..000000000
--- a/static/img/transportation/heading-light.svg
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/static/img/transportation/oriented-east-dark.png b/static/img/transportation/oriented-east-dark.png
new file mode 100644
index 000000000..a206f3234
Binary files /dev/null and b/static/img/transportation/oriented-east-dark.png differ
diff --git a/static/img/transportation/oriented-east-dark.svg b/static/img/transportation/oriented-east-dark.svg
deleted file mode 100644
index 5a2bc4490..000000000
--- a/static/img/transportation/oriented-east-dark.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/static/img/transportation/oriented-east-light.png b/static/img/transportation/oriented-east-light.png
new file mode 100644
index 000000000..eefd53ba4
Binary files /dev/null and b/static/img/transportation/oriented-east-light.png differ
diff --git a/static/img/transportation/oriented-east-light.svg b/static/img/transportation/oriented-east-light.svg
deleted file mode 100644
index 27c0fd210..000000000
--- a/static/img/transportation/oriented-east-light.svg
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/static/img/transportation/oriented-west-dark.png b/static/img/transportation/oriented-west-dark.png
new file mode 100644
index 000000000..bb5c8fdf3
Binary files /dev/null and b/static/img/transportation/oriented-west-dark.png differ
diff --git a/static/img/transportation/oriented-west-dark.svg b/static/img/transportation/oriented-west-dark.svg
deleted file mode 100644
index f59ecfd2c..000000000
--- a/static/img/transportation/oriented-west-dark.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file
diff --git a/static/img/transportation/oriented-west-light.png b/static/img/transportation/oriented-west-light.png
new file mode 100644
index 000000000..c1121b3fa
Binary files /dev/null and b/static/img/transportation/oriented-west-light.png differ
diff --git a/static/img/transportation/oriented-west-light.svg b/static/img/transportation/oriented-west-light.svg
deleted file mode 100644
index 7d2d3760f..000000000
--- a/static/img/transportation/oriented-west-light.svg
+++ /dev/null
@@ -1,3 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/static/img/transportation/splitter_concept.png b/static/img/transportation/splitter_concept.png
new file mode 100644
index 000000000..2bd33a42b
Binary files /dev/null and b/static/img/transportation/splitter_concept.png differ
diff --git a/static/img/transportation/splitter_concept.svg b/static/img/transportation/splitter_concept.svg
deleted file mode 100644
index 11d2eb0ab..000000000
--- a/static/img/transportation/splitter_concept.svg
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
\ No newline at end of file