Merge pull request usdot-jpo-ode#163 from sknick-iastate/updated-exam…

…ples-spring-2021

Add comprehensive, real-world examples

README.md

@@ -18,8 +18,22 @@ Two additional directories, [`images`](/images) and [`documents`](/documents), c
 ### Contents
 - [**Creating a WZDx Feed**](/create-feed)
     - [**Example Feed GeoJSON Files**](/create-feed/examples)   
-        - [LineString Example](/create-feed/examples/linestring_example.geojson)
-        - [MultiPoint Example](/create-feed/examples/multipoint_example.geojson)
+        - [LineString Examples](/create-feed/examples/linestring_examples)
+            - [Comprehensive](/create-feed/examples/linestring-examples/comprehensive_linestring_example.geojson)
+            - [Local Access Only (bidirectional)](/create-feed/examples/linestring-examples/local_access_only_bidirectional_linestring_example.geojson)
+            - [Simple Work Zone](/create-feed/examples/linestring-examples/scenario1_simple_linestring_example.geojson)
+            - [Lane Shift](/create-feed/examples/linestring-examples/scenario2_laneshift_linestring_example.geojson)
+            - [Shoulder Closure (bidirectional)](/create-feed/examples/linestring-examples/scenario3_shoulder_bidrectional_linestring_example.geojson)
+            - [Detour](/create-feed/examples/linestring-examples/scenario4_detour_linestring_example.geojson)
+            - [Recurring Work](/create-feed/examples/linestring-examples/scenario5_recurring_linestring_example.geojson)
+        - [MultiPoint Examples](/create-feed/examples/multipoint_examples)
+            - [Comprehensive](/create-feed/examples/multipoint-examples/comprehensive_multipoint_example.geojson)
+            - [Local Access Only (bidirectional)](/create-feed/examples/multipoint-examples/local_access_only_bidirectional_multipoint_example.geojson)
+            - [Simple Work Zone](/create-feed/examples/multipoint-examples/scenario1_simple_multipoint_example.geojson)
+            - [Lane Shift](/create-feed/examples/multipoint-examples/scenario2_laneshift_multipoint_example.geojson)
+            - [Shoulder Closure (bidirectional)](/create-feed/examples/multipoint-examples/scenario3_shoulder_bidrectional_multipoint_example.geojson)
+            - [Detour](/create-feed/examples/multipoint-examples/scenario4_detour_multipoint_example.geojson)
+            - [Recurring Work](/create-feed/examples/multipoint-examples/scenario5_recurring_multipoint_example.geojson)
     - [**JSON Schemas**](/create-feed/schemas)
         - [WZDx v2.0 Feed](/create-feed/schemas/wzdx_v2.0_feed.json)
         - [WZDx v3.0 Feed](/create-feed/schemas/wzdx_v3.0_feed.json)

create-feed/README.md

@@ -37,10 +37,57 @@ The figure below models the tables and their relationships.
 ![WZDx Object Diagram](/images/wzdx_object_diagram.jpg)
 
 ## Feed Examples
-The following WZDx feed examples include all optional fields. An example file is included for both the `LineString` and `MultiPoint` geometry types.
+The following WZDx feed examples represent a variety of scenarios common when creating road events. Most of the examples are modeled after work zone scenarios used in [previous WZDx discussion](https://github.com/usdot-jpo-ode/jpo-wzdx/discussions/131). Optional fields are not included in all examples but represented at least once across the various examples. Each scenario is provided as a single GeoJSON file which may contain multiple work zones documenting differences in representing road events at varying levels of complexity. A comprehensive example contains all of the scenarios in a single file. All example scenarios are provided for both the `LineString` and `MultiPoint` geometry types.
 
-* [MultiPoint GeoJSON Example](/create-feed/examples/multipoint_example.geojson)
-* [LineString GeoJSON Example](/create-feed/examples/linestring_example.geojson)
+* [All LineString GeoJSON Examples](/create-feed/examples/linestring-examples)
+* [All MultiPoint GeoJSON Examples](/create-feed/examples/multipoint-examples)
+
+Below is a summary of each of the example WZDx feeds and detailed differences for each of the road events:
+
+### Scenario 1  - Simple Work Zone
+Scenario 1 ([Linestring](/create-feed/examples/linestring-examples/scenario1_simple_linestring_example.geojson) or [MultiPoint](/create-feed/examples/multipoint-examples/scenario1_simple_multipoint_example.geojson)) is based on the same numbered annotated work zones in [Discussion Topic 131](https://github.com/usdot-jpo-ode/jpo-wzdx/discussions/131) with a single lane closed on a multi-lane facility.
+
+- First work zone is single direction, single event, with no lane-level information (ID: `71234`).
+- Second work zone is single direction, single event, with detailed lane information (ID: `WDM-58493-NB`).
+- Third work zone is single direction, three sequential events, with detailed lane information. This work zone demonstrates the use of the `relationship` property, both `first` and `next` to indiciate the order of the road events and `parents` to indicate all road events are related (they all have `parents` as `65773`). (IDs: `65773-1`, `65773-2`, `65773-3`).
+
+### Scenario 2 - Lane Shift (simple scenario)
+Scenario 2 ([Linestring](/create-feed/examples/linestring-examples/scenario2_laneshift_linestring_example.geojson) or [MultiPoint](/create-feed/examples/multipoint-examples/scenario2_laneshift_multipoint_example.geojson)) is based on the same numbered annotated work zones in [Discussion Topic 131](https://github.com/usdot-jpo-ode/jpo-wzdx/discussions/131) which keeps all lanes open but shifts them resulting in both shoulders being closed on a multi-lane facility.
+
+- Single work zone with lane shift in the detailed lane information showing us of verified location and start time. ("id": `7733`).
+
+### Scenario 3 - Shoulder Closure (bidirectional work zone)
+Scenario 3 ([Linestring](/create-feed/examples/linestring-examples/scenario3_shoulder_bidirectional_linestring_example.geojson) or [MultiPoint](/create-feed/examples/multipoint-examples/scenario3_shoulder_bidrectional_multipoint_example.geojson)) is based on the same numbered annotated work zones in [Discussion Topic 131](https://github.com/usdot-jpo-ode/jpo-wzdx/discussions/131) which closes the shoulder in a single direction on an undivided roadway.
+
+- Single work zone represented by two road events (IDs: `121388-EB`, `121388-WB`), one in direction of shoulder closure and second in opposite direction.
+- Demonstrates the use of `restrictions` for the event as well as individual lanes
+- Demonstrates the use of `relationship` to show the road events in each direction are related to a common parent (`121388`)
+
+### Scenario 4 - Road Closure with Detour on Arterial
+Scenario 4 ([Linestring](/create-feed/examples/linestring-examples/scenario4_detour_linestring_example.geojson) or [MultiPoint](/create-feed/examples/multipoint-examples/scenario4_detour_multipoint_example.geojson) is based on the same numbered annotated work zones in [Discussion Topic 131](https://github.com/usdot-jpo-ode/jpo-wzdx/discussions/131) which has an associated detour for a road closure.  The example is slightly modified for use on a multi-lane facility.
+
+- Single work zone in one direction represented by a single road event (ID: `67890`), with a detour.
+- Showing use of `relationship` `parents` and `children` to connect the detour road events (IDs: `67890-detour1`, `67890-detour2`, `67890-detour3`) to the work zone.
+- Also uses `relationship` to represent the sequence of the three detour road events.
+- Does not use `parents` to connect the work zone and all detour road events to a common parent (e.g. a project), but that approach is acceptable.
+
+### Scenario 5 - Recurring Work Zone
+Scenario 5 ([Linestring](/create-feed/examples/linestring-examples/scenario5_recurring_linestring_example.geojson) or [MultiPoint](/create-feed/examples/multipoint-examples/scenario5_recurring_multipoint_example.geojson)) is based on the same numbered annotated work zones in [Discussion Topic 131](https://github.com/usdot-jpo-ode/jpo-wzdx/discussions/131) assuming that it is just a single lane closure but is recurring over multiple days.
+
+- Simple work zone but with a recurring component.
+- Five road events: an `active` (day 1, ID: `PLK01012016-Day1`) event and four additional events (IDs: `PLK01012016-Day2`, `PLK01012016-Day3`, `PLK01012016-Day4`, `PLK01012016-Day5`) for later dates with a pending status.
+- The `active` work zone event demonstrates value of verified location and time.
+- The `relationship` property is used to show all road events are related (they have the same parent of `PLK01012016`).
+
+### Local Access Only (bidirectional work zone)
+The local access only example ([Linestring](/create-feed/examples/linestring-examples/local_access_only_bidirectional_linestring_example.geojson) or [MultiPoint](/create-feed/examples/multipoint-examples/local_access_only_bidirectional_multipoint_example.geojson)) shows a basic work zone that keeps all lanes open but places restrictions to only local traffic.
+
+- Single work zone on a bidirectional roadwith with impact to both directions, represented by two road events (IDs: `WZ389-NB`, `WZ389-SB`), one for each direction.
+- Uses `local-access-only` [RoadRestriction](/spec-content/enumerated-types/RoadRestriction.md).
+- One road event shows basic details (not lane-level), while the opposite direction road event shows detailed lane information. The detailed lane information also includes a bike lane for reference.
+
+### Comprehensive Example
+- The comprehensive example ([Linestring](/create-feed/examples/linestring-examples/comprehensive_linestring_example.geojson) or [MultiPoint](/create-feed/examples/multipoint-examples/comprehensive_multipoint_example.geojson)) contains all of the examples listed above in a single GeoJSON file showing how the various road events across multiple organizations and data sources can be represented in a single WZDx feed.
 
 ## JSON Schemas
 The [schemas](/create-feed/schemas) directory includes a JSON Schema for the following WZDx feed versions: