-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Write thorough docs on travel mode scoping
- Loading branch information
Showing
6 changed files
with
300 additions
and
9 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,271 @@ | ||
| # 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 (that motor vehicle might be | ||
| classified as a "high occupancy vehicle" or a "heavy goods vehicle"). | ||
|
|
||
| Within the Overture Transportation theme's schema model, the real world | ||
| intuition translates to the following definition: a travel mode is a | ||
| recognized mode by which a person or thing may use a | ||
| [Segment](/reference/transportation/segment) feature. | ||
|
|
||
| ## Understanding travel modes | ||
|
|
||
| ### 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](roads#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, for example one | ||
| jurisdiction may say "heavy goods vehicle" and another may say | ||
| "large goods vehicle". | ||
|
|
||
| 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. | ||
|
|
||
| ### When is a travel mode recognized? | ||
|
|
||
| A travel mode is recognized by the Overture Transportation schema when | ||
| it becomes part of the [`mode`](https://github.com/OvertureMaps/schema/blob/5f82f1d6a916031cb32730e1fac7e1a353f10c60/schema/transportation/segment.yaml#L103) | ||
| enumeration. As of our draft schema release `v0.4.0`, this enumeration | ||
| is relatively small and contains only travel modes which we some | ||
| confidence will be generally-applicable both across jurisdictions and | ||
| over time. We expect the list to change in future schema updates, to be | ||
| larger once we reach a table `v1.0.0` schema, and to continue to expand | ||
| as the world changes and new information arises. | ||
|
|
||
| Our criteria for recognizing a proposed new travel mode are: | ||
|
|
||
| 1. The proposed new travel mode should represent a *generally-accepted* | ||
| concept meaning that the concept exists in many places with roughly | ||
| the same definition. | ||
| 2. The proposed new travel mode should be referred to with well-known | ||
| sign iconography or sign text in those jurisdictions where the | ||
| concept exists; and this iconography or sign text is preferably | ||
| somewhat consistent across many jurisdictions and over time. | ||
| 3. It must be possible to give a relatively precise *definition* to the | ||
| proposed new travel mode and explain how it *differs* from, or | ||
| *intersects* with, other similar travel modes which are already | ||
| recognized in the Overture schema. | ||
| 4. The proposed new travel mode should preferably not be trivially | ||
| expressible using another existing | ||
| [Scoping Property](scoping-rules#scoped-values-and-scoping-properties). | ||
| (*An example of such a trivially-expressible concept might be a | ||
| "three-axle vehicle" which is more appropriately phrased as | ||
| `vehicle: { axleCount: { isEqualTo: 3 } }`.*) | ||
| 5. The proposed new travel mode must be supported by existing data in at | ||
| least one of Overture's upstream data sources. | ||
|
|
||
| There is a risk that the above-described approach will be too slow to | ||
| adapt to our users' needs in a vast, ever-changing world. One possible | ||
| avenue to mitigate this risk is supporting | ||
| [custom extensions](#should-we-support-extension-travel-modes) to the | ||
| built-in list of recognized travel modes. | ||
|
|
||
| ## Travel mode schema | ||
|
|
||
| ### Scoping to travel modes | ||
|
|
||
| Travel modes can used to change the scope of scoped and rule-based | ||
| properties within the schema. For example, they can affect the scope of | ||
| access restrictions, turn restrictions, or speed limits on [road](roads) | ||
| segments. Since travel modes are expressed via scoping properties, it | ||
| is recommended to read the section on | ||
| [Scoped and Rule-Based Properties](scoping-rules) before proceeding | ||
| further. | ||
|
|
||
| #### Travel mode scoping: `mode` and `modeNot` | ||
|
|
||
| Two scoping properties control whether a given scoped property applies | ||
| to a given travel mode: `mode` and `modeNot`. | ||
|
|
||
| If either `mode` or `modeNot` property is specified, the property value | ||
| must be a non-empty, array of travel modes, and is interpreted as a set. | ||
| Values must be unique, but order is not important. | ||
|
|
||
| The `mode` and `modeNot` properties are not mutually exclusive: in | ||
| places where scoping by travel mode is allowed, either `mode` or | ||
| `modeNot`, or both, may be provided. | ||
|
|
||
| 1. **Neither**. When *neither* `mode` nor `modeNot` is provided, the | ||
| parent property's scope includes all possible travel modes. | ||
| 2. **Only `mode`**. When `mode` is provided by itself, the parent | ||
| property is scoped to include only those travel modes that included | ||
| in the `mode` set. | ||
| 3. **Only `modeNot`**. When `modeNot` is provided by itself, the parent | ||
| property is scoped to include all those travel modes that are not | ||
| included in the `modeNot` set. | ||
| 4. **Both**. When both `mode` and `modeNot` are provided, the parent | ||
| property is scoped to include all those travel modes that are | ||
| included in the `mode` set *except* those that are included in the | ||
| `modeNot` set. (*For example, | ||
| `mode: [motorVehicle], modeNot: [motorcycle]` expresses the travel | ||
| mode scope "all motor vehicles except motorcycles".*) | ||
|
|
||
| #### Vehicle attribute scoping: `vehicle` | ||
|
|
||
| Because travel modes are an "fuzzy" concept, there are inevitably areas | ||
| of overlap between with the more precise, but more limited, `vehicle` | ||
| scoping property which is used for | ||
| [vehicle attributes scoping](scoping-rules#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](scoping-rules#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](scoping-rules#status-scoping-membership-in-a-recognized-group), | ||
| which relates to a recognized status given to the person or thing | ||
| travelling, where the recognized status is distinct from the mode of | ||
| travel itself. Travel modes should ideally not embed a status. | ||
|
|
||
| ### The travel modes taxonomy | ||
|
|
||
| Overture travel modes 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 `motorVehicle`. | ||
|
|
||
| The taxonomy supported in our draft schema `v0.4.0` can be visualized | ||
| in the diagram below. | ||
|
|
||
| <figure> | ||
|
|
||
| <div style={{ display: "flex", alignItems: "center" }}> | ||
|
|
||
| <div style={{ width: "72%", float: "left", paddingRight: "3px" }}> | ||
|
|
||
|  | ||
|
|
||
| </div> | ||
|
|
||
| <div style={{ width: "28%", float: "right", paddingLeft: "3px" }}> | ||
|
|
||
|  | ||
|
|
||
| </div> | ||
|
|
||
| <div style={{ clear: "both" }}/> | ||
|
|
||
| </div> | ||
|
|
||
| <figcaption> | ||
|
|
||
| <div style={{ textAlign: "center" }}> | ||
|
|
||
| *The Overture travel modes taxonomy.* | ||
|
|
||
| </div> | ||
|
|
||
| </figcaption> | ||
|
|
||
| </figure> | ||
|
|
||
|
|
||
| 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), | ||
| we would like acknowledge a intellectual debt to the OSM community in | ||
| relation to travel modes as well as to other aspects of the | ||
| Transportation schema. | ||
|
|
||
| ## Open questions | ||
|
|
||
| This section discusses some open questions are debating internally with | ||
| regard to travel modes. We would love to hear | ||
| [your feedback](https://github.com/OvertureMaps/schema/discussions) on | ||
| these questions (and any others that you may have). | ||
|
|
||
| ### Minimum required travel modes | ||
|
|
||
| We're not yet certain on the minimum set of recognized travel modes is | ||
| that will make the Overture Transportation schema as usable as possible | ||
| to as broad an audience as possible. What do you think we are missing? | ||
|
|
||
| ### Should we support extension travel modes? | ||
|
|
||
| <!-- | ||
| TODO: This open question relates to the feature request | ||
| https://github.com/OvertureMaps/schema-wg/issues/157. | ||
|
|
||
| We should update or delete the content of this documentation based | ||
| on what happens with that feature request. | ||
| --> | ||
|
|
||
| We live in a time of rapid technological and regulatory iteration in | ||
| the transportation space. The speed of change raises the possibility | ||
| that no matter how quickly we extend the travel modes recognized in the | ||
| Overture schema, the schema will always be behind the real world, at | ||
| least in some local areas and with regard to some technologies, customs, | ||
| or local rules. | ||
|
|
||
| One possibility to keep the Overture schema maximally usable for users | ||
| who are mapping at the cutting edge is to allow custom extensions to | ||
| the list of travel modes. If we did this consistently with how extension | ||
| properties <!-- TODO: This should be a link to a heading in the main | ||
| schema documentation, but that heading needs to be written first. --> | ||
| work for features, we could, for example, allow travel mode names with | ||
| the `ext*` to be ignored by the schema validation rules. | ||
|
|
||
| What do you think? | ||
|
|
||
| ### Internal consistency | ||
|
|
||
| As alluded to [above](#vehicle-attribute-scoping-vehicle), there is some | ||
| overlap between the fuzzy concept of travel modes and vehicle attribute | ||
| scoping. We're aware of this overlap and view it as limited but | ||
| inevitable. | ||
|
|
||
| Our intention is, however, to reduce or eliminate the overlap between | ||
| travel modes and the other | ||
| [similar scoping properties](#similar-scoping-properties-using-and-recognized) | ||
| (`using` and `recognized`). One area where we may have been unsuccessful | ||
| is the `emergency` travel mode in the [current taxonomy](#the-travel-modes-taxonomy). | ||
| Arguably, `emergency` should be removed from the taxonomy, and an | ||
| `asEmergencyResponder` should be included in the status values | ||
| enumeration for the `recognized` property. | ||
|
|
||
| What are your suggestions relating to keeping the travel modes and other | ||
| scoping properties internally consistent and minimally overlapping? |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.