Merge pull request #118 from usdot-jpo-ode/v3-relationship-object

Identify both sequential and hierarchical relationships between road events and other entities

README.md

@@ -56,6 +56,7 @@ A third directory, [`images`](/images) contains images that are referenced throu
  - [Road Event Feed Info](/spec-content/data-tables/road_event_feed_info.md)
  - [Road Events](/spec-content/data-tables/road_events.md)
  - [Types of Work](/spec-content/data-tables/types_of_work.md)
+ - [Relationships](/feed-content/data-tables/relationships.md)
  - [Lanes](/spec-content/data-tables/lanes.md)
  - [Lane Restrictions](/spec-content/data-tables/lane_restrictions.md)
  - [Metadata](/spec-content/data-tables/metadata.md)

create-feed/examples/linestring_example.geojson

@@ -10,7 +10,9 @@
  "type": "Feature",
  "properties": {
  "road_event_id": "12345",
- "subidentifier": "State_Project_001",
+ "relationship": {
+ "parents": ["State_Project_001"]
+ },
  "road_name": "Main Street",
  "road_number": "I-100",
  "direction": "northbound",
@@ -238,7 +240,9 @@
  "type": "Feature",
  "properties": {
  "road_event_id": "67890",
- "subidentifier": "State_Project_002",
+ "relationship": {
+ "parents": ["State_Project_002"]
+ },
  "road_name": "Barrett Street",
  "road_number": "I-200",
  "direction": "westbound",

create-feed/examples/multipoint_example.geojson

@@ -10,7 +10,9 @@
  "type": "Feature",
  "properties": {
  "road_event_id": "12345",
- "subidentifier": "State_Project_001",
+ "relationship": {
+ "parents": ["State_Project_001"]
+ },
  "road_name": "Main Street",
  "road_number": "I-100",
  "direction": "northbound",
@@ -86,7 +88,9 @@
  "type": "Feature",
  "properties": {
  "road_event_id": "67890",
- "subidentifier": "State_Project_002",
+ "relationship": {
+ "parents": ["State_Project_002"]
+ },
  "road_name": "Barrett Street",
  "road_number": "I-200",
  "direction": "westbound",

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

@@ -71,9 +71,8 @@
  "description": "A unique identifier issued by the data feed provider to identify the work zone project or activity",
  "type": "string"
  },
- "subidentifier": {
- "description": "A unique identifier issued by data feed provider that provides additional references to project or activity",
- "type": "string"
+ "relationship": {
+ "$ref": "#/definitions/relationship"
  },
  "road_name": {
  "description": "Publicly known name of the road on which the event occurs",
@@ -200,6 +199,45 @@
  "vehicle_impact"
  ]
  },
+ "relationship": {
+ "title": "Relationship",
+ "description": "Identifies both sequential and hierarchical relationships between road events and other entities. For example, a relationship can be used to link multiple road events to a common 'parent', such as a project or phase, or identify a sequence of road events",
+ "type": "object",
+ "properties": {
+ "first": {
+ "description": "Indicates the first (can be multiple) road event in a sequence of road events by 'road_event_id'",
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "string"
+ }
+ },
+ "next": {
+ "description": "Indicates the next (can be multiple) road event in a sequence of road events by 'road_event_id'",
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "string"
+ }
+ },
+ "parents": {
+ "description": "Indicates entities that the road event with this relationship is a part of, such as a work zone project or phase. Values can but do not have to correspond to a WZDx entity",
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "string"
+ }
+ },
+ "children": {
+ "description": "Indicates entities that are part of the road event with this relationship, such as a detour or piece of equipment. Values can but do not have to correspond to a WZDx entity",
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "type": "string"
+ }
+ }
+ }
+ },
  "type_of_work": {
  "title": "Type of Work",
  "description": "A description of the type of work being done in a road event and an indication of if that work will result in an architectural change to the roadway",

spec-content/README.md

@@ -19,6 +19,7 @@ This section provides a list of all data tables uses in the WZDx specification.
 - [Road Event Feed Info](/spec-content/data-tables/road_event_feed_info.md)
 - [Road Events](/spec-content/data-tables/road_events.md)
 - [Types of Work](/spec-content/data-tables/types_of_work.md)
+- [Relationships](/feed-content/data-tables/relationships.md)
 - [Lanes](/spec-content/data-tables/lanes.md)
 - [Lane Restrictions](/spec-content/data-tables/lane_restrictions.md)
 - [Metadata](/spec-content/data-tables/metadata.md)

spec-content/data-tables/relationships.md

@@ -0,0 +1,21 @@
+# relationships
+**optional**
+
+Identify both sequential and hierarchical relationships between road events and other entities. For example, a relationship can be used to link multiple road events to a common "parent", such as a project or phase, or identify a sequence of road events.
+
+Relationships show up on the feed as as a `relationship` property on the [road_events](https://github.com/usdot-jpo-ode/jpo-wzdx/blob/master/feed-content/data-tables/road_events.md) feature properties.
+
+## Relationships Table Structure
+Data Name | Data Type | Description | Conformance | Notes
+--- | --- | --- | --- | ---
+**relationship_id** | ID | Identifies the relationship record | Required | Primary key
+[road_event_id](/data-tables/road_events.md) | ID | Identifies the road event to which a relationship applies. | Required | Foreign key to [road_events](/feed-content/data-tables/road_events.md) table
+**first** | ID; Array | Indicates the first (can be multiple) road event in a sequence of road events by `road_event_id` | Optional | Every value provided should be an ID which relates to a road event by `road_event_id`
+**next** | ID; Array | Indicates the next (can be multiple) road event in a sequence by `road_event_id` | Optional | Every value provided should be an ID which relates to a road event by `road_event_id`
+**parents** | Text; Array | Indicates entities that the road event with this relationship is a part of, such as a work zone project or phase | Optional | Values can but do not have to correspond to a WZDx entity
+**children** | Text; Array | Indicates entities that are part of the road event with this relationship, such as a detour or piece of equipment | Optional | Values can but do not have to correspond to a WZDx entity
+
+## Notes
+- The format of `first`, `next`, `parents`, and `children` should be conducive to serializing into a JSON array for the feed ouput (e.g. "["parent1", "parent2"]")
+- The `first` and `next` fields are used to define sequential relationships
+- The `parents` and `children` fields define hierarchical relationships

spec-content/data-tables/road_events.md

@@ -8,6 +8,8 @@ This table is related to the [types_of_work](/spec-content/data-tables/types_of_
 
 This table is related to the [lanes](/spec-content/data-tables/lanes.md) table. For each record in the road_events table there may exist one or more records in the lanes table. The road_event_id field acts as the foreign key in the lanes table.
 
+This table is related to the [relationships](/feed-content/data-tables/relationships.md) table. For each record in the road_events table there may exist one record in the relationships table. The road_event_id field acts as the foreign key in the relationships table.
+
 ## Data Table Structure
 Each data table defines a list of data fields which are described by the following characterstics:
 
@@ -20,15 +22,12 @@ Each data table defines a list of data fields which are described by the followi
  - *Conditional* - associated with two or more data concepts; requires that at least one of the concepts be included in the data feed file
 - **Notes** - comments, guidance, or notes for future consideration
 
-
-
 ## Road Events Table Structure
 
 Field Name | Data Type | Description | Conformance | Notes
 --------- | --------- | ---------------- | ----------- | -----
 **road_event_id** | ID | A unique identifier issued by the data feed provider to identify the work zone project or activity | Required | Primary Key
 **[feed_info_id](/spec-content/data-tables/road_event_feed_info.md)** | ID |Identifies the feed to which a road event is related.|Required|Foreign Key to road_event_feed_info
-**subidentifier** | ID | A unique identifier issued by data feed provider that provides additional references to project or activity | Optional | This identifier may be used in more than one feed as a reference to an<br>agency project number or permit ID
 **geometry_type** | Enumeration: Multipoint or LineString|May be represented as a linestring or a multipoint as defined in the GeoJson specification.|Required|
 **geometry**|Coordinate(s); Float|A coordinate pair or an array of coordinates. In either case, the first coordinate is the beginning point and the last coordinate is the ending point of the road event|Required|Coordinate pairs and coordinate arrays are formatted according to the geoJson spec
 **road_name**|Text|Publicly known name of the road on which the event occurs.|Required|