Merge pull request #168 from usdot-jpo-ode/spring-2021-release

WZDx v3.1 — Spring 2021 Release

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - name: Start a Discussion
-    url: https://github.com/usdot-jpo-ode/jpo-wzdx/discussions/category_choices
+    url: https://github.com/usdot-jpo-ode/wzdx/discussions/category_choices
     about: Ask the WZDx community for input on a question or idea you have.

RELEASES.md

@@ -1,7 +1,28 @@
+# WZDx Specification v3.1
+Released April 2021
+
+Following the major v3.0 release, the changes for the v3.1 release were developed with the goal enhancing and cleaning up the specification without making major changes or breaking backwards compatibility. Thus, in v3.1 many enumerated type values or object properties were deprecated rather than removed. Most if not all of these deprecated values will be removed in the next major release.
+
+This repository was also renamed from `jpo-wzdx` to `wzdx` on 2021-04-05. All links pointing to `jpo-wzdx` will automatically redirect to the new URL. 
+
+## Features
+* Add `local-access-only` restriction
+* Add `license` property to the `RoadEventFeedInfo` object
+
+## Refactoring
+* Refactor `LaneType` enumerated type to deprecate values that can be determined from other properties of the Lane object, such as `order`, `status`, and `lane_restrictions`
+* Add value `alternating-flow` to `LaneStatus` enumerated type and deprecate `alternating-one-way`
+* Add `road_names` property to the `RoadEvent` object and deprecate `road_name` and `road_number`
+* Deprecate the `total_num_lanes` property on the `RoadEvent` object as the `RoadEvent`'s `lanes` array can be used to determine the number of lanes
+
+## Fixes
+* Add optional `bbox` property to allow providing a [GeoJSON Bounding Box](https://tools.ietf.org/html/rfc7946#section-5) for the `WZDxFeed` and `RoadEventFeature` objects
+* Add an `id` property to the `RoadEventFeature` object for providing the a road event's identifier to better follow [GeoJSON ID recommendations](https://tools.ietf.org/html/rfc7946#section-3.2)
+
 # WZDx Specification v3.0
-> Released September 2020
+Released September 2020
 
-**Features**
+## Features
 * Restrict `version` format to `major.minor` and enforce via v3.0 JSON schema
 * Add `order` property to Lane object to indicate a lane's position in sequence on the roadway
 * Remove `lane_edge_reference` and standardize on counting lanes from the left side of the roadway
@@ -10,27 +31,25 @@
 * Add **RoadEventDataSource** object to allow specifying multiple data sources within a single feed
 * Streamline **metadata** (previously given in an external file, by URL) and add relevant fields to the **RoadEventFeedInfo** and **RoadEventDataSource** objects
 
-**Fixes**
+## Fixes
 * Require `restriction_type` if providing a lane-level restriction
 * Change **Spatial Verification Enumerated Type** and **Time Verification Enumerated Type** values to be all lowercase
 * Remove all plural or nonsensical lane types from the **Lane Type Enumerated Type** and clarify that each WZDx lane should represent a *single* lane on the roadway
 
 # WZDx Specification v2.0
-
-> Released 1/14/2020
+Released January 2020
 
 This release includes the first set of major changes to the specification. 
 
-**CHANGES**
-* [Required GeoJSON formatting](https://github.com/usdot-jpo-ode/jpo-wzdx/pull/53) of a WZDx feed. GeoJSON is a data interchange format based on JavaScript Object Notation (JSON) designed to exchange geospatial data. Since feeds can be used with existing validation, mapping, and visualizations tools, requiring GeoJSON will improve accessibility of work zone data activity to producers and consumers.
-* Converted the “common core” data dictionary into a [relational data model](https://github.com/usdot-jpo-ode/jpo-wzdx/pull/54) with road event tables featuring new geometry-specific data elements. This conversion permits more efficient organization of the data elements for each work zone and supports a flexible, scalable data model.
-* Added new data tables to accommodate [mobility impact and lane level impacts/restrictions](https://github.com/usdot-jpo-ode/jpo-wzdx/pull/57) (i.e., closures and restrictions). The new lane-level information, as well as overall vehicle impact fields, allowing IOOs new flexibility in communicating impacts and mobility restrictions of a work zone.
-* Added a new [Types of Work table](https://github.com/usdot-jpo-ode/jpo-wzdx/pull/59) to provide specific information on the types of work being performed at a work zone. This enumerated table categorizes the type of work and indicates if construction in a work zone will cause any architectural changes to the roadway. This information will support keeping the maps used by autonomous vehicles up to date.  
-
-
-
-# [WZDx Specification v1.1](https://github.com/usdot-jpo-ode/jpo-wzdx/tree/v1.1)
+## Features
+* Added new data tables to accommodate [mobility impact and lane level impacts/restrictions](https://github.com/usdot-jpo-ode/wzdx/pull/57) (i.e., closures and restrictions). The new lane-level information, as well as overall vehicle impact fields, allowing IOOs new flexibility in communicating impacts and mobility restrictions of a work zone.
+* Added a new [Types of Work table](https://github.com/usdot-jpo-ode/wzdx/pull/59) to provide specific information on the types of work being performed at a work zone. This enumerated table categorizes the type of work and indicates if construction in a work zone will cause any architectural changes to the roadway. This information will support keeping the maps used by autonomous vehicles up to date.
 
-> Released 9/15/2018
+## Refactoring
+* [Required GeoJSON formatting](https://github.com/usdot-jpo-ode/wzdx/pull/53) of a WZDx feed. GeoJSON is a data interchange format based on JavaScript Object Notation (JSON) designed to exchange geospatial data. Since feeds can be used with existing validation, mapping, and visualizations tools, requiring GeoJSON will improve accessibility of work zone data activity to producers and consumers.
+* Converted the “common core” data dictionary into a [relational data model](https://github.com/usdot-jpo-ode/wzdx/pull/54) with road event tables featuring new geometry-specific data elements. This conversion permits more efficient organization of the data elements for each work zone and supports a flexible, scalable data model.
+
+# [WZDx Specification v1.1](https://github.com/usdot-jpo-ode/wzdx/tree/v1.1)
+Released September 2018
 
-* Initial release. This version served as a first step in providing a standard work zone data activity framework. This version of the specification focused on “common core” data concepts which are defined as data elements needed for most work zone data use cases. The specification included data elements that data producers were already producing as well as those that may not currently be produced.
+Initial release. This version served as a first step in providing a standard work zone data activity framework. This version of the specification focused on “common core” data concepts which are defined as data elements needed for most work zone data use cases. The specification included data elements that data producers were already producing as well as those that may not currently be produced.

create-feed/README.md

@@ -3,7 +3,7 @@ This directory contains information regarding creation of a WZDx feed, such as t
 
 ## Feed Format and File Type
 
-The WZDx v3.0 data feed is formatted according to the [GeoJSON](https://geojson.org/) specification. GeoJSON is the file format of choice because:
+The WZDx v3.1 data feed is formatted according to the [GeoJSON](https://geojson.org/) specification. GeoJSON is the file format of choice because:
 - It is a lightweight data exchange format.
 - It is easy for humans to read and write.
 - It is easy for machines to parse and generate.
@@ -47,6 +47,7 @@ The [schemas](/create-feed/schemas) directory includes a JSON Schema for the fol
 
 * [WZDx v2.0 Feed](/create-feed/schemas/wzdx_v2.0_feed.json)
 * [WZDx v3.0 Feed](/create-feed/schemas/wzdx_v3.0_feed.json)
+* [WZDx v3.1 Feed](/create-feed/schemas/wzdx_v3.1_feed.json)
 
 ## Business Rules
 The following business rules help assure a standardized and interpretable use of the WZDx specification. The specification describes the required structure and data fields to describe a work zone, whereas business rules are additional requirements for using the WZDx specification in a standard manner. Note that business rules are distinct from best practices in that the latter are suggestions and business rules are requirements.
@@ -56,10 +57,11 @@ The following business rules help assure a standardized and interpretable use of
 3. The preferred [GeoJSON Geometry](https://tools.ietf.org/html/rfc7946#page-7) for a [RoadEventFeature](/spec-content/objects/RoadEventFeature.md) is `LineString`, which allows indicating the full path of the road event. In cases where only the beginning and ending coordinates are available, the `MultiPoint` can be used.  
 4. A cascading multi-lane closure should consider the speed of vehicles traveling through the work zone. If the distance between lane closures is short enough that time in a to-be-closed lane is not significant, which is common, the to-be-closed lane should be represented as closed to avoid traffic delays and potential crashes.
 5. A detour must be represented with a [RoadEvent](/spec-content/objects/RoadEvent.md) of type (i.e. with `event_type` of) `detour` and its containing [RoadEventFeature](/spec-content/objects/RoadEventFeature.md) should have a `geometry` of `type` `LineString` to represent the full detour route. The detour road event should be connected to the work zone road event using the `relationship` property on the detour road event.
+6. If the `lanes` property on the [RoadEvent](/spec-content/objects/RoadEvent.md) object is provided, it must include one entry for every lane in the road event. Providing lane information for only some of the lanes in a road event is not allowed.
 
 ## Data Validation
-### WZDx v2.0 and v3.0
-Use the corresponding JSON schema linked above to validate WZDx v2.0 and v3.0 feeds.
+### WZDx v2.0, v3.0, and v3.1
+Use the corresponding JSON schema linked above to validate WZDx v2.0, v3.0, and v3.1 feeds.
 
 ### WZDx v1.0
 To validate data feeds and measure compliance with the v1.1 specification, the GSA/18F team have developed a prototype data validation tool. This validation service that checks work zone activities against the WZDx v1.1 JSON schema specification is available [here](https://github.com/18F/usdot-jpo-ode-workzone-data-exchange/wiki).

create-feed/examples/linestring_example.geojson

@@ -36,16 +36,15 @@
   "type": "FeatureCollection",
   "features": [
     {
+      "id": "12345",
       "type": "Feature",
       "properties": {
-        "road_event_id": "12345",
         "data_source_id": "1",
         "event_type": "work-zone",
         "relationship": {
           "parents": ["State_Project_001"]
         },
-        "road_name": "Main Street",
-        "road_number": "I-100",
+        "road_names": ["Main Street", "I-100"],
         "direction": "northbound",
         "beginning_cross_street": "Westford St",
         "ending_cross_street": "South St",
@@ -58,7 +57,6 @@
         "start_date_accuracy": "verified",
         "end_date_accuracy": "verified",
         "event_status": "completed",
-        "total_num_lanes": 3,
         "vehicle_impact": "some-lanes-closed",
         "workers_present": false,
         "reduced_speed_limit": 30,
@@ -77,7 +75,7 @@
             "order": 1,
             "lane_number": 1,
             "status": "open",
-            "type": "left-lane",
+            "type": "lane",
             "restrictions": [
               {
                 "restriction_type": "reduced-width",
@@ -90,13 +88,13 @@
             "order": 2,
             "lane_number": 2,
             "status": "closed",
-            "type": "middle-lane"
+            "type": "lane"
           },
           {
             "order": 3,
             "lane_number": 3,
             "status": "closed",
-            "type": "right-lane"
+            "type": "lane"
           }
         ]
       },
@@ -267,16 +265,15 @@
       }
     },
     {
+      "id": "67890",
       "type": "Feature",
       "properties": {
-        "road_event_id": "67890",
         "data_source_id": "2",
         "event_type": "work-zone",
         "relationship": {
           "parents": ["State_Project_002"]
         },
-        "road_name": "Barrett Street",
-        "road_number": "I-200",
+        "road_names": ["Barrett Street", "I-200"],
         "direction": "westbound",
         "beginning_cross_street": "King St",
         "ending_cross_street": "Hampton Garden Dr",
@@ -289,7 +286,6 @@
         "start_date_accuracy": "verified",
         "end_date_accuracy": "verified",
         "event_status": "completed",
-        "total_num_lanes": 2,
         "vehicle_impact": "all-lanes-open",
         "workers_present": true,
         "reduced_speed_limit": 30,
@@ -308,7 +304,7 @@
             "order": 1,
             "lane_number": 1,
             "status": "open",
-            "type": "left-lane",
+            "type": "lane",
             "restrictions": [
               {
                 "restriction_type": "no-trucks"
@@ -319,7 +315,7 @@
             "order": 2,
             "lane_number": 2,
             "status": "open",
-            "type": "right-lane"
+            "type": "lane"
           }
         ]
       },

create-feed/examples/multipoint_example.geojson

@@ -36,16 +36,15 @@
   "type": "FeatureCollection",
   "features": [
     {
+      "id": "12345",
       "type": "Feature",
       "properties": {
-        "road_event_id": "12345",
         "data_source_id": "1",
         "event_type": "work-zone",
         "relationship": {
           "parents": ["State_Project_001"]
         },
-        "road_name": "Main Street",
-        "road_number": "I-100",
+        "road_names": ["Main Street", "I-100"],
         "direction": "northbound",
         "beginning_cross_street": "Westford St",
         "ending_cross_street": "South St",
@@ -58,7 +57,6 @@
         "start_date_accuracy": "verified",
         "end_date_accuracy": "verified",
         "event_status": "completed",
-        "total_num_lanes": 3,
         "vehicle_impact": "some-lanes-closed",
         "workers_present": false,
         "reduced_speed_limit": 30,
@@ -77,7 +75,7 @@
             "order": 1,
             "lane_number": 1,
             "status": "open",
-            "type": "left-lane",
+            "type": "lane",
             "restrictions": [
               {
                 "restriction_type": "reduced-width",
@@ -90,13 +88,13 @@
             "order": 2,
             "lane_number": 2,
             "status": "closed",
-            "type": "middle-lane"
+            "type": "lane"
           },
           {
             "order": 3,
             "lane_number": 3,
             "status": "closed",
-            "type": "right-lane"
+            "type": "lane"
           }
         ]
       },
@@ -115,16 +113,15 @@
       }
     },
 	  {
+      "id": "67890",
       "type": "Feature",
       "properties": {
-        "road_event_id": "67890",
         "data_source_id": "2",
         "event_type": "work-zone",
         "relationship": {
           "parents": ["State_Project_002"]
         },
-        "road_name": "Barrett Street",
-        "road_number": "I-200",
+        "road_names": ["Barrett Street", "I-200"],
         "direction": "westbound",
         "beginning_cross_street": "King St",
         "ending_cross_street": "Hampton Garden Drive",
@@ -137,7 +134,6 @@
         "start_date_accuracy": "verified",
         "end_date_accuracy": "verified",
         "event_status": "completed",
-        "total_num_lanes": 2,
         "vehicle_impact": "all-lanes-open",
         "workers_present": true,
         "reduced_speed_limit": 30,
@@ -157,7 +153,7 @@
             "order": 1,
             "lane_number": 1,
             "status": "open",
-            "type": "left-lane",
+            "type": "lane",
             "restrictions": [
               {
                 "restriction_type": "no-trucks"
@@ -168,7 +164,7 @@
             "order": 2,
             "lane_number": 2,
             "status": "open",
-            "type": "right-lane"
+            "type": "lane"
           }
         ]
       },

create-feed/schemas/wzdx_v2.0_feed.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://raw.githubusercontent.com/usdot-jpo-ode/jpo-wzdx/1dbcd48757a4f83b3704bd0ea3623ee3743c1497/create-feed/schema/wzdx_v2.0_feed.json",
+  "$id": "https://raw.githubusercontent.com/usdot-jpo-ode/wzdx/master/create-feed/schemas/wzdx_v2.0_feed.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "WZDx v2.0 Feed",
   "description": "The GeoJSON output of a WZDx v2.0 data feed",

create-feed/schemas/wzdx_v3.0_feed.json

@@ -1,5 +1,5 @@
 {
-  "$id": "https://github.com/usdot-jpo-ode/jpo-wzdx/tree/v3/create-feed/schemas/wzdx_v3.0_feed.json",
+  "$id": "https://raw.githubusercontent.com/usdot-jpo-ode/wzdx/master/create-feed/schemas/wzdx_v3.0_feed.json",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "WZDx v3.0 Feed",
   "description": "The GeoJSON output of a WZDx v3.0 data feed",