From d6801d789c25b53d68bb30a8e981230280605e9f Mon Sep 17 00:00:00 2001
From: Victor Schappert <schapper@amazon.com>
Date: Mon, 19 Jun 2023 10:23:37 -0700
Subject: [PATCH] Write thorough docs on travel mode scoping

---
 .../docs/themes/transportation/index.mdx      |  25 +-
 .../themes/transportation/scoping-rules.mdx   |   7 +-
 .../themes/transportation/travel-modes.mdx    | 270 ++++++++++++++++++
 docusaurus/sidebars.js                        |   1 +
 .../transportation/travel-modes-legend.svg    |   3 +
 .../transportation/travel-modes-taxonomy.svg  |   3 +
 6 files changed, 300 insertions(+), 9 deletions(-)
 create mode 100644 docusaurus/static/img/transportation/travel-modes-legend.svg
 create mode 100644 docusaurus/static/img/transportation/travel-modes-taxonomy.svg

diff --git a/docusaurus/docs/themes/transportation/index.mdx b/docusaurus/docs/themes/transportation/index.mdx
index 2a5e645f..8b68b028 100644
--- a/docusaurus/docs/themes/transportation/index.mdx
+++ b/docusaurus/docs/themes/transportation/index.mdx
@@ -75,12 +75,6 @@ page.
 
 </li>
 
-<!--
-
-TODO: A bullet for travel modes, and a page for travel modes.
-
--->
-
 <li>
 
 <p>
@@ -99,6 +93,25 @@ Read more about roads on the [Roads](roads) page.
 
 </li>
 
+<li>
+
+<p>
+
+**Travel Modes.** The Transportation theme supports a fuzzy concept called
+travel mode which can be used as a way of controlling the scope of scoped
+and rule-based properties.
+
+</p>
+
+<p>
+
+Read more about the travel modes concept and how travel modes interact
+with other scoping properties on the [Travel Modes](travel-modes) page.
+
+</p>
+
+</li>
+
 </ul>
 
 ## Schema Reference
diff --git a/docusaurus/docs/themes/transportation/scoping-rules.mdx b/docusaurus/docs/themes/transportation/scoping-rules.mdx
index a1b9fc66..5b5d3a0c 100644
--- a/docusaurus/docs/themes/transportation/scoping-rules.mdx
+++ b/docusaurus/docs/themes/transportation/scoping-rules.mdx
@@ -21,7 +21,7 @@ The Overture Transportation theme's schema model of the transportation
 network uses two related concepts to capture the partial application of
 facts and rules: Scoped values, and Rule-based properties.
 
-## Scoped values
+## 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
@@ -31,7 +31,7 @@ example a signpost 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.
+special child properties of the value known as *Scoping* properties.
 
 ### Geometric scoping (linear referencing)
 
@@ -174,7 +174,8 @@ listed travel modes. Conversely, the construct
 `when: { modeNot: [...] }` scopes the parent value to apply only when
 the traveller is *not* using one of the listed travel modes.
 
-To dive deeper into this topic, see the page on Travel Modes. **TODO: Link.**
+To dive deeper into this topic, see the page on
+[Travel Modes](travel-modes).
 
 <!--
 
diff --git a/docusaurus/docs/themes/transportation/travel-modes.mdx b/docusaurus/docs/themes/transportation/travel-modes.mdx
index 7c6c5a20..dd0b88ff 100644
--- a/docusaurus/docs/themes/transportation/travel-modes.mdx
+++ b/docusaurus/docs/themes/transportation/travel-modes.mdx
@@ -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" }}>
+
+![The Overture travel modes taxonomy](/img/transportation/travel-modes-taxonomy.svg)
+
+</div>
+
+<div style={{ width: "28%", float: "right", paddingLeft: "3px" }}>
+
+![Legend graphic for Overture travel modes taxonomy](/img/transportation/travel-modes-legend.svg)
+
+</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?
diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js
index 9258e663..76133fd9 100644
--- a/docusaurus/sidebars.js
+++ b/docusaurus/sidebars.js
@@ -68,6 +68,7 @@ const sidebars = {
             'themes/transportation/shape-connectivity',
             'themes/transportation/scoping-rules',
             'themes/transportation/roads',
+            'themes/transportation/travel-modes',
           ]
         }
       ]
diff --git a/docusaurus/static/img/transportation/travel-modes-legend.svg b/docusaurus/static/img/transportation/travel-modes-legend.svg
new file mode 100644
index 00000000..1f2073a5
--- /dev/null
+++ b/docusaurus/static/img/transportation/travel-modes-legend.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="323px" height="223px" viewBox="-0.5 -0.5 323 223" content="&lt;mxfile host=&quot;drawio.corp.amazon.com&quot; modified=&quot;2023-06-23T18:52:28.232Z&quot; agent=&quot;Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36&quot; version=&quot;12.4.8&quot; etag=&quot;UTU7oWFH7yU7n7w8qgss&quot; type=&quot;device&quot;&gt;&lt;diagram id=&quot;k6d5B8Ka0rXh_Skb5zrI&quot;&gt;7ZjLctsgFIafxtsOEpYdLxM7aRZNpzNeNF0SCUlMEagI+dKn70ECWTenHseebBzPZODnpsP3g0ATvMx2XxXJ0xcZUT7xUbSb4NXE9xczD/4bYV8LnodRrSSKRVY7CGv2l1rRVStZRItORS0l1yzviqEUgoa6oxGl5LZbLZa8O2pOEjoQ1iHhQ/Uni3TqwkDoUPBMWZLaoe8CW5ARV9kKRUoiuW1J+HGCl0pKXaey3ZJyM3luXup2T0dKmwdTVOhTGvh1gw3hpY1t4s84NH1gkEhMwgmlE77RhIrIydB32a8KWqt5Fafeu8lTshQRNeMjKN6mTNN1TkJTugW7gJbqjEPOg2ShlfxNl5JLVbXGqPprStz0Y1Bixnmr5lv1M7oU+olkjBu7PVO+oZqFxBZYc3mezY8NRThLBGicxiaiDVWmA35vZS3NQ0uIgWkzhI+asE1VujvKxmuIw1KhMqNa7aGKbXBnPWJXycy5a3uwHHY+Sltua8xFrM2TpuuDEyBhzTBuDDw0RvCQALt8EqzeYeqdwXQeIxTHpzCN48UCX4RpD5dDHAIbqlw/NkB8AZgemnZpToc0m/2jTXN6AZjTAcwM9uRPo4jxYlHV7FBcylIxmHsffafbK5FEVyA5H1mXVyMZDEgupQhprkvCq9clLFAmEkhKAbPqQ4dIwMsEAlS0MBFCX8JgD1OakYEFYFr0e5yFFLQH1Er/2SQzFkVmkFFbdV8Jl17bF2Du495ePLZ6gysxnw2Yr8s8lxBOZA4+imyq49Xokr7xPInn6Bq+Fs/5gOdwHd624tO24h7G2RDj9EoU7wYU324Uz6M4/zyKi+Extw8R7jr35s5opoCTomDhB7h9dCuEKVX7V7uxVplfJvMlcNnVrl242rvcjulX+8Am3WoFuUMjk3Ft6pmgUe8uXICtQtrZyjRRCXV33ZPxt/CObbVOU5QTzTbdhxhjbkf4IVl1zDnirgD1bFPHY1u1r8q9jpprle1oGvQ6qmdh0FFlwSbsk1zpvnO0bPlSvd2Ru2Ebf5gvF8SSmP0pzSeDh+6ab2R3GX9r3dDrLtwlHbGi/mCiCRPVwaI6JmYXGZYcHfZ2XDnruDKyQ17quALZw+en2ruHj3j48R8=&lt;/diagram&gt;&lt;/mxfile&gt;"><defs/><g><rect x="1" y="1" width="320" height="220" fill-opacity="0.2" fill="#b3b3b3" stroke="#000000" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(4.5,9.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="37" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 38px; white-space: nowrap; overflow-wrap: normal; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;"><i><u>Legend</u></i></div></div></foreignObject><text x="19" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Helvetica">[Not supported by viewer]</text></switch></g><rect x="25" y="41" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#ff9933" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(55.5,55.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="38" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 39px; white-space: nowrap; overflow-wrap: normal; font-weight: bold; font-style: italic; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">[group]</div></div></foreignObject><text x="19" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Helvetica" font-weight="bold" font-style="italic">[group]</text></switch></g><rect x="25" y="101" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(61.5,115.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="26" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 27px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">mode</div></div></foreignObject><text x="13" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">mode</text></switch></g><rect x="151" y="41" width="150" height="40" fill="none" stroke="none" pointer-events="all"/><g transform="translate(152.5,48.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="148" height="24" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 148px; white-space: nowrap; overflow-wrap: normal; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">Conceptual grouping only, not present in schema</div></div></foreignObject><text x="74" y="18" fill="#000000" text-anchor="middle" font-size="11px" font-family="Helvetica">Conceptual grouping only, not present in schema</text></switch></g><rect x="151" y="101" width="150" height="40" fill="none" stroke="none" pointer-events="all"/><g transform="translate(152.5,115.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="111" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 112px; white-space: nowrap; overflow-wrap: normal; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">Supported travel mode</div></div></foreignObject><text x="56" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Helvetica">Supported travel mode</text></switch></g><rect x="21" y="161" width="40" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(37.5,175.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="7" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 8px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">a</div></div></foreignObject><text x="4" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">a</text></switch></g><rect x="91" y="161" width="40" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(107.5,175.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="7" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 8px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">b</div></div></foreignObject><text x="4" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">b</text></switch></g><path d="M 61 181 L 80.9 181" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 87.65 181 L 78.65 185.5 L 80.9 181 L 78.65 176.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/><rect x="151" y="161" width="150" height="40" fill="none" stroke="none" pointer-events="all"/><g transform="translate(152.5,167.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="148" height="26" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 148px; white-space: nowrap; overflow-wrap: normal; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">Mode <font face="Courier New">b</font> is contained in mode <font face="Courier New">a</font></div></div></foreignObject><text x="74" y="19" fill="#000000" text-anchor="middle" font-size="11px" font-family="Helvetica">[Not supported by viewer]</text></switch></g></g></svg>
\ No newline at end of file
diff --git a/docusaurus/static/img/transportation/travel-modes-taxonomy.svg b/docusaurus/static/img/transportation/travel-modes-taxonomy.svg
new file mode 100644
index 00000000..0364bdb4
--- /dev/null
+++ b/docusaurus/static/img/transportation/travel-modes-taxonomy.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="583px" height="453px" viewBox="-0.5 -0.5 583 453" content="&lt;mxfile host=&quot;drawio.corp.amazon.com&quot; modified=&quot;2023-06-23T18:51:58.666Z&quot; agent=&quot;Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36&quot; version=&quot;12.4.8&quot; etag=&quot;5VC657lrlFpsmT2GrBwR&quot; type=&quot;device&quot;&gt;&lt;diagram id=&quot;I8SFaeOylH4FodX9NnlX&quot;&gt;7ZtLc5s6FMc/jbcdQAibZeMkt5vb6Uxm+liqIIPmCuQR8qufvsJINkhOQh2ZkjtkkUFHD6TzPz8ER8kMLIv9Pxyt839Ziuks8NL9DNzPgiCOfPm7Nhwag+8Dr7FknKTKdjY8kV9YGXWzDUlx1WkoGKOCrLvGhJUlTkTHhjhnu26zFaPdu65Rhi3DU4Kobf1GUpHrZXjeueITJlmubr2AqqJAurEyVDlK2a5lAg8zsOSMieaq2C8xrZ2n/dL0e3ym9jQxjkvRp0PQdNgiulFrm8E7VB5m8F5NUBz0qjnblCmuO/ozcLfLicBPa5TUtTups7TloqCquhKc/YeXjDJ+7A3mK89brU412m9AWlaE0lbL1SqOwdHOSvGICkLrOPmE6RYLkiBVoaLC91W5NYB3/JF2JqdHRN07qIuIkqyUhUQ6B3M9jlogUJ7AXOD9s970TxrJ4MaswIIfZBPVYaFUVXENtMq7VpDoGMlb8REqG1JxmZ1GPksnL5R6l5UElpKrOor+logAxPGxZUfEJdtwIl0feJ/x7kZCeg6EPCmin1BDKhlaSm5xThK5uElMF2KCaEAxoSXmT5IcJjGvFTP0umIG3oBiRpaYBROMf53wdKhoOKSi88uKToReryeMDEIXA+q5sPRMEJ+EdCIkAAMKGVtC5mw7CelEyHBIIfU3e1vJbFLSEZJDPlt9336X3VSTkm6YHFRJO+2DC8wzXCaHSU8nesJBn7F28seSEacZ1gvG9CfbPZwNd0eDrMgZJ7+kZxCtjWX6sU6W1m6jqKpI8gatXWiK90R8Vzevr3/U2n2AqnS/P0qpCgddKKUvv7cLrV518dztWNL9Gv/VTusERCWnniiT8rFAEhwlJugdNq2wgBeiQts4pkiQbXcSl0JF3eELI/LG59SH/8y7uB6iWY/q1c4TmwOZL/XAGKjxgjXQMXJPy+4XzHb+68VgrnBWSG93wnmK3D+N3HDkkQt9R5EbRv0iVwYQOrSaresGVf8Jg9B7eV5m+0WnvbxoZnA1Rnbm8f1jdDskQhsJODIkgJHHDuIrkQCxMZD5DuIICTB/McRfbW8cXr4dCTt/+/6RGNfOcgGjaGQYmae0cH4tRsAYKBgnRqFrjOyk+YSRW4wiG6P5yDAyoyzyrsRIh+cJI3gbjCB4EYtX2wPPMUb2WcWE0c0xWowMozB+Jfr7YgSNt0No8jgWjKBjjOyTogmjm2OkP17Hw5HxVheZ3zS9OTLf6syvrJFwFDrejvQuPHE0JEfx2DAysmWRmeftjZGZvzMzz2PByPF2FNiHpO8fI7dIdPaR/gdtwwAAzb9GMz/qewMAjYFGCgB0vY8E/0MARr+P6BP90XAUwlee/705MoCEPU8eB+fobRuJLJ7/66dpfv7fKfDwGw==&lt;/diagram&gt;&lt;/mxfile&gt;"><defs/><g><rect x="1" y="201" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#ff9933" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(37.5,215.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="26" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 27px; white-space: nowrap; overflow-wrap: normal; font-weight: bold; font-style: italic; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">[any]</div></div></foreignObject><text x="13" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Helvetica" font-weight="bold" font-style="italic">[any]</text></switch></g><rect x="161" y="1" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(197.5,15.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="26" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 27px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">foot</div></div></foreignObject><text x="13" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">foot</text></switch></g><rect x="161" y="241" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(187.5,255.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="46" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 47px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">vehicle</div></div></foreignObject><text x="23" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">vehicle</text></switch></g><rect x="321" y="81" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(347.5,95.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="46" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 47px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">bicycle</div></div></foreignObject><text x="23" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">bicycle</text></switch></g><rect x="321" y="281" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(331.5,295.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="79" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 80px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">motorVehicle</div></div></foreignObject><text x="40" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">motorVehicle</text></switch></g><rect x="481" y="161" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(497.5,175.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="66" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 67px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">motorcycle</div></div></foreignObject><text x="33" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">motorcycle</text></switch></g><rect x="481" y="211" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(520.5,225.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="20" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 21px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">car</div></div></foreignObject><text x="10" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">car</text></switch></g><rect x="481" y="311" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(520.5,325.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="20" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 21px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">hov</div></div></foreignObject><text x="10" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">hov</text></switch></g><rect x="481" y="261" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(520.5,275.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="20" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 21px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">hgv</div></div></foreignObject><text x="10" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">hgv</text></switch></g><rect x="481" y="361" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(520.5,375.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="20" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 21px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">bus</div></div></foreignObject><text x="10" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">bus</text></switch></g><rect x="481" y="411" width="100" height="40" rx="6" ry="6" fill-opacity="0.2" fill="#3399ff" stroke="#7f00ff" stroke-opacity="0.2" stroke-width="3" pointer-events="all"/><g transform="translate(501.5,425.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="59" height="11" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: &quot;Courier New&quot;; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 60px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;white-space:normal;">emergency</div></div></foreignObject><text x="30" y="11" fill="#000000" text-anchor="middle" font-size="11px" font-family="Courier New">emergency</text></switch></g><path d="M 101 221 L 121 221 Q 131 221 131 211 L 131 31 Q 131 21 140.95 21 L 150.9 21" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 157.65 21 L 148.65 25.5 L 150.9 21 L 148.65 16.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/><path d="M 101 221 L 121 221 Q 131 221 131 231 L 131 251 Q 131 261 140.95 261 L 150.9 261" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 157.65 261 L 148.65 265.5 L 150.9 261 L 148.65 256.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/><path d="M 261 261 L 281 261 Q 291 261 291 251 L 291 111 Q 291 101 300.95 101 L 310.9 101" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 317.65 101 L 308.65 105.5 L 310.9 101 L 308.65 96.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/><path d="M 261 261 L 281 261 Q 291 261 291 271 L 291 291 Q 291 301 300.95 301 L 310.9 301" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 317.65 301 L 308.65 305.5 L 310.9 301 L 308.65 296.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/><path d="M 421 301 L 441 301 Q 451 301 451 291 L 451 191 Q 451 181 460.95 181 L 470.9 181" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 477.65 181 L 468.65 185.5 L 470.9 181 L 468.65 176.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/><path d="M 421 301 L 441 301 Q 451 301 451 291 L 451 241 Q 451 231 460.95 231 L 470.9 231" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 477.65 231 L 468.65 235.5 L 470.9 231 L 468.65 226.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/><path d="M 421 301 L 441 301 Q 451 301 451 291 L 451 286 Q 451 281 460.95 281 L 470.9 281" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 477.65 281 L 468.65 285.5 L 470.9 281 L 468.65 276.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/><path d="M 421 301 L 441 301 Q 451 301 451 311 L 451 321 Q 451 331 460.95 331 L 470.9 331" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 477.65 331 L 468.65 335.5 L 470.9 331 L 468.65 326.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/><path d="M 421 301 L 441 301 Q 451 301 451 311 L 451 371 Q 451 381 460.95 381 L 470.9 381" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 477.65 381 L 468.65 385.5 L 470.9 381 L 468.65 376.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/><path d="M 421 301 L 441 301 Q 451 301 451 311 L 451 421 Q 451 431 460.95 431 L 470.9 431" fill="none" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 477.65 431 L 468.65 435.5 L 470.9 431 L 468.65 426.5 Z" fill="#7f00ff" stroke="#7f00ff" stroke-width="3" stroke-miterlimit="10" pointer-events="all"/></g></svg>
\ No newline at end of file