4.1 update add road incident feed #318
Conversation
* Update Creating_a_WZDx_Feed.md Added a section with data security details. * Update Creating_a_WZDx_Feed.md * Update Creating_a_WZDx_Feed.md * Update Creating_a_WZDx_Feed.md Co-authored-by: Nate Deshmukh Towery <45435037+natedeshmukhtowery@users.noreply.github.com>
* Fix recurring event example feed * Change dates in recurrent event example feed for clarity
|
@DeraldDudley I'm not sure about splitting the components of the IncidentFeed between multiple PRs from an implementation point. If you do keep them separate, you should merge the commits from this branch into those so that the IncidentType enumerations are shown in context. Also, for completeness this PR should add a new schema file for the IncidentFeed and add the IncidentRoadEvent to the RoadEventFeature schema. Let me know if you want any help making these changes - happy to assist as needed. |
mark-mockett
added
the
Specification Extension
Happy to merge the incident type enumerations into this PR if it makes it easier. Didn't want the incidents feed to get rejected because people disagreed with some of the enumeration values. |
| ## Used By | ||
| Road Restriction GeoJSON document (one `RoadIncidentFeed` object per file). |
There was a problem hiding this comment.
I think this needs to be updated to Road Incident GeoJSON document
| # RoadIncidentFeed Object (GeoJSON FeatureCollection) | ||
| The `RoadIncidentFeed` object is the root (highest level) object of a WZDx road incident feed. There is one `RoadIncidentFeed` object per road incident feed GeoJSON document. The `RoadIncidentFeed` is a [GeoJSON FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3). | ||
|
|
||
| The `RoadIncidentFeed` informs drivers about the location of roadway incidents. Incident types are described by [`type_of_incident`](/spec-content/enumerated-types/event_enumerations.md) enumerations. |
There was a problem hiding this comment.
I don't have a preference on whether to keep the enumerations separate in the PRs (#319 and #320) but think a placeholder for the actual enumerations should be added. You refer to it here as event_enumerations.md but just need to add it to the enumerated-type folder.
Also, for PR #319 and #320 you use a different name for the file with the enumerations. My assumptions is they should all be in a single file as described above if it is being used by the same field.
| `end_date_accuracy` | [TimeVerification](/spec-content/enumerated-types/TimeVerification.md) | A measure of how accurate the end date-time is. | Optional| | ||
| `beginning_accuracy` | [SpatialVerification](/spec-content/enumerated-types/SpatialVerification.md) | Indicates how the beginning coordinate was defined. | Required | | ||
| `ending_accuracy` | [SpatialVerification](/spec-content/enumerated-types/SpatialVerification.md) | Indicates how the ending coordinate was defined. | Required | | ||
| `location_method` | [LocationMethod](/spec-content/enumerated-types/LocationMethod.md) | The typical method used to locate the beginning and end of a work zone impact area. | Required | |
There was a problem hiding this comment.
I'm not sure location_method is necessary since this is very work zone specific. If you do think it is important to include then we may need to generalize the descriptions that are appropriate.
| `beginning_accuracy` | [SpatialVerification](/spec-content/enumerated-types/SpatialVerification.md) | Indicates how the beginning coordinate was defined. | Required | | ||
| `ending_accuracy` | [SpatialVerification](/spec-content/enumerated-types/SpatialVerification.md) | Indicates how the ending coordinate was defined. | Required | |
There was a problem hiding this comment.
Since incidents are most likely going to be unplanned events, is the beginning and ending accuracy needed? We modified the description in I think v4.0 that verified needs to be based on a GPS equipped device which is more applicable for work zones. Not saying it can't be used but just wanted to ask the question.
| `ending_cross_street` | String | Name or number of the nearest cross street along the roadway where the event ends. | Optional | | ||
| `beginning_milepost` | Number | The linear distance measured against a milepost marker along a roadway where the event begins. | Optional | A milepost or mile marker is a surveyed distance posted along a roadway measuring the length (in miles or tenth of a mile) from the south west to the north east. These markers are typically notated on State and local government digital road networks. | ||
| `ending_milepost` | Number | The linear distance measured against a milepost marker along a roadway where the event ends. | Optional | A milepost or mile marker is a surveyed distance posted along a roadway measuring the length (in miles or tenth of a mile) from the south west to the north east. These markers are typically notated on State and local government digital road networks. | ||
| `event_status` | [EventStatus](/spec-content/enumerated-types/EventStatus.md) | The status of the event. | Optional | |
There was a problem hiding this comment.
The event_status is very work zone focused and not sure it is applicable for incidents. Its not approved but there is also PR #294 that is planning on deprecating event_status
| `beginning_milepost` | Number | The linear distance measured against a milepost marker along a roadway where the event begins. | Optional | A milepost or mile marker is a surveyed distance posted along a roadway measuring the length (in miles or tenth of a mile) from the south west to the north east. These markers are typically notated on State and local government digital road networks. | ||
| `ending_milepost` | Number | The linear distance measured against a milepost marker along a roadway where the event ends. | Optional | A milepost or mile marker is a surveyed distance posted along a roadway measuring the length (in miles or tenth of a mile) from the south west to the north east. These markers are typically notated on State and local government digital road networks. | ||
| `event_status` | [EventStatus](/spec-content/enumerated-types/EventStatus.md) | The status of the event. | Optional | | ||
| `worker_presence` | [WorkerPresence](/spec-content/objects/WorkerPresence.md) | Information about whether workers are present in the road event area. | Optional | |
There was a problem hiding this comment.
Right now the worker_presence is very work zone specific. I assume you are trying to indicate whether someone is responding or on site of the incident which I think is valuable but we either need to modify the description of the WorkerPresence object or use another field.
|
The Road Incident Feed has moved to TDx |
Summary
Add an Incident Road Feed
Motivation
Adding an incident Road Feed enables publishers to inform drivers about events that close or restricts the use of road segments. This is valuable because it reduces driver uncertainty and increases the probability of driver success. It also fulfills use cases identified by WZDx working group members and state transportation officials. These use cases include informing citizens about road closures after a hurricane and informing transportation management centers about road status during emergencies.
Adding incidents will bolster the specifications usefulness. A more useful specification is more likely to be implemented. More implementations inform more drivers about hazards to navigation. Better informed drivers avoid hazards resulting in safer, cleaner, and more efficient transportation.
IncidentRoadEvents vs WorkZoneRoadEvents
IncidentRoadEvents are very similar to WorkZoneRoadEvent. They are different in the following ways:
type_of_workis dropped from the IncidentRoadEvent object.end_dateis optional in IncidentRoadEvent object.type_of_incidentis created for the IncidentRoadEvent object. Incident types are described using incident enumerations.Changes
RoadIncidentFeed Object (GeoJSON FeatureCollection)
The
RoadIncidentFeedobject is the root (highest level) object of a WZDx road incident feed. There is oneRoadIncidentFeedobject per road incident feed GeoJSON document. TheRoadIncidentFeedis a GeoJSON FeatureCollection.The
RoadIncidentFeedinforms drivers about the location of roadway incidents. Incident types are described bytype_of_incidentenumerations.Properties
feed_infotype"FeatureCollection"FeatureCollection.featuresbboxUsed By
Road Restriction GeoJSON document (one
RoadIncidentFeedobject per file).RoadEventFeature Object (GeoJSON Feature)
The
RoadEventFeatureobject is the container object for a WZDx road event (WorkZoneRoadEvent, DetourRoadEvent, RestrictionRoadEvent, RestrictionRoadEvent). TheRoadEventFeatureobject is an instance of a GeoJSON Feature.Properties
idtype"Feature"Feature.propertiesgeometrytypeof LineString or MultiPointtypeproperty MUST be LineString or MultiPoint.LineStringallows specifying the entire road event path and should be preferred.MultiPointshould be used when only the start and end coordinates are known.bbox2nwherenis the number of dimensions represented in thegeometryproperty, with all axes of the most southwesterly point followed by all axes of the more northeasterly point. The axes order of a bbox follows the axes order of thegeometry.Used By
featuresfeaturesfeaturesIncidentRoadEvent Object
The
IncidentRoadEventobject locates and describes incidents or events that close or restrict the use of a road segment.The
IncidentRoadEventis a type of road event; it has acore_detailsproperty which contains the RoadEventCoreDetails and exists within a RoadEventFeature.Properties
core_detailstypes_of_incidentstart_date2016-11-03T19:37:00Z.end_date2016-11-03T19:37:00Z.is_start_date_verifiedis_end_date_verifiedis_start_position_verifiedis_end_position_verifiedlocation_methodvehicle_impactlanesbeginning_cross_streetending_cross_streetbeginning_milepostending_milepostworker_presencereduced_speed_limit_kphrestrictionsUsed By
propertiesTypeOfIncident Object
The
TypeOfIncidentobject describes an event that causees disruptions to expected operations.Properties
incident_typeUsed By
incident_typesIncidentType Enumerated Type
Descriptions of the incidents causing disruptions to expected operations.
Values
Used By
incident_typeAdded RoadIncidentFeed.json to Schemas
RoadIncidentFeed.json
{
"$id": "https://raw.githubusercontent.com/usdot-jpo-ode/wzdx/main/schemas/4.1/RoadIncidentFeed.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "WZDx v4.1 RoadIncidentFeed",
"description": "The GeoJSON output of a Road Incident Feed data feed (v4.0)",
"type": "object",
"properties": {
"road_event_feed_info": {
"$ref": "https://raw.githubusercontent.com/usdot-jpo-ode/wzdx/main/schemas/4.1/FeedInfo.json"
},
"type": {
"description": "The GeoJSON type",
"enum": ["FeatureCollection"]
},
"features": {
"description": "An array of GeoJSON Feature objects which represent Incident road events",
"type": "array",
"items": {
"allOf": [
{
"properties": {
"properties": {
"properties": {
"core_details": {
"properties": {
"event_type": {
"enum": ["incident", "detour"]
}
},
"required": ["event_type"]
}
},
"required": ["core_details"]
}
},
"required": ["properties"]
},
{
"$ref": "https://raw.githubusercontent.com/usdot-jpo-ode/wzdx/main/schemas/4.0/RoadEventFeature.json"
}
]
}
},
"bbox": {
"$ref": "https://raw.githubusercontent.com/usdot-jpo-ode/wzdx/main/schemas/4.0/BoundingBox.json"
}
},
"required": ["road_event_feed_info", "type", "features"]}