search

usdot-jpo-ode / wzdx

The Work Zone Data Exchange (WZDx) Specification aims to make harmonized work zone data provided by infrastructure owners and operators (IOOs) available for third party use, making travel on public roads safer and more efficient through ubiquitous access to data on work zone activity.
Creative Commons Zero v1.0 Universal
89 stars 62 forks source link

Normalize the RoadEvent Object #204

Closed DeraldDudley closed 2 years ago

DeraldDudley commented 3 years ago

Normalize the RoadEvent Object

The RoadEvent object, in version 3.1 of the Work Zone Data Specification comingles Road Events, Work Zone Events, and Detour Events in a single class. Comingling objects in a single class deviates from the well-established best practice of data normalization. Normalization is important in data design because it reduces redundant data storage, retrieval, maintenance, and exchange.

Normalization is important to the Work Zone Data Working group because it eliminates the unnecessary exchange of unneeded, or unwanted, data and enables the publication of basic features like named roads or restrictions. Without normalization, the required fields of the work-zone event prohibit the specification from being used to publish anything other than a Work Zone Feature or a related Detour Feature. In the case of publishing a Detour, it forces the use of unneeded and irrelevant properties to describe a detour. This makes the specification inflexible and hard to scale. With normalization the specification becomes flexible, easy to scale, can be used to address non-work-zone related use-cases, and maximizes the specifications social benefit.

Normalizing the content of the specification's data model will split the RoadEvent object. The first derivative is a “minimum-content” version of the RoadEvent which requires only the properties necessary to publish a named road segment. The second derivative is the newly formatted work-zone feature. The new format nests the “minimum-content” RoadEvent within the work-zone feature and carries only the properties needed to describe a work-zone. The last derivative, a normalized Detour feature, nests the “minimum-content” RoadEvent within the detour feature and carries only the properties needed to describe a detour.

Changes to the Road Event Object

Requirements: Carry only the properties necessary to locate and describe the simplest use-case of mapping a named road segment.

RoadEvent Object

The RoadEvent object contains the minimum-content needed to locate a named road segment.

Properties

Name Type Description Conformance Notes
event_type EventType The type/classification of road event. Required
data_source_id String Identifies the data source from which the road event originates. Required The value must match to the data_source_id property of a RoadEventDataSource included within the same WZDx GeoJSON document.
road_names Array; [String] A list of publicly known names of the road on which the event occurs. This may include the road number designated by a jurisdiction such as a county, state or interstate (e.g. I-5, VT 133). Conditional: required if road_name is not provided. This property captures the functionality of the deprecated road_number and road_name properties and conformance will be required in a future release.
direction Direction The digitization direction of the road that is impacted by the event. This value is based on the standard naming for US roadways and indicates the direction of the traffic flow regardless of the real heading angle. Required Example northbound (for I-5 North)
relationship Relationship Identifies both sequential and hierarchical relationships between the 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 Optional
description String Short free text description of work zone. Optional
creation_date String; date-time The UTC time and date when the activity or event was created. Optional All datetime formats shall follow RFC 3339 Section 5.6. Example: 2016-11-03T19:37:00Z.
update_date String; date-time The UTC time and date when the activity or event was updated. Optional All datetime formats shall follow RFC 3339 Section 5.6. Example: 2016-11-03T19:37:00Z.

Used By

Property Object
properties RoadEventFeature
road_event WorkZoneEvent
road_event DetourEvent
road_event RestrictionEvent

Important Notes

The value of the RoadEvent's data_source_id property MUST match the value of the data_source_id property of a RoadEventDataSource that is included in the same WZDx GeoJSON document.

Changes to the Work-Zone Event Object

Requirements: Include the RoadEvent object and carry only the properties necessary to describe the a work-zone segment.

WorkZoneEvent Object

The WorkZoneEvent object contains information that describes where, when, and what activities are taking place in a work-zone, along a road segment.

Properties

Name Type Description Conformance Notes
road_event RoadEvent Describes the basic characterisitics of a Road Event. Required
start_date String; date-time The UTC time and date when the event begins. Required All datetime formats shall follow RFC 3339 Section 5.6. Example: 2016-11-03T19:37:00Z.
end_date String; date-time The UTC time and date when the event ends. Required All datetime formats shall follow RFC 3339 Section 5.6. Example: 2016-11-03T19:37:00Z.
start_date_accuracy TimeVerification A measure of how accurate the start Date Time is. Required
end_date_accuracy TimeVerification A measure of how accurate the end Date Time is. Required
beginning_accuracy SpatialVerification Indicates how the beginning coordinate was defined. Required
ending_accuracy SpatialVerification Indicates how the ending coordinate was defined. Required
vehicle_impact VehicleImpact The impact to vehicular lanes along a single road in a single direction. Required
lanes Array; [Lane] A list of individual lanes within a road event (roadway segment) Optional
beginning_cross_street String Name or number of the nearest cross street along the roadway where the event begins. Optional
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. See also the lrs_type property on the RoadEventDataSource object.
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. See also the lrs_type property on the RoadEventDataSource object.
event_status EventStatus The status of the event. Optional
types_of_work Array; [TypeOfWork] A list of the types of work being done in a road event and an indiciation of if each type results in an architectural change to the roadway. Optional
workers_present Boolean A flag indicating that there are workers present in the event space. Optional
reduced_speed_limit Integer The reduced speed limit posted within the event space. Optional
restrictions Array; [RoadRestriction] Zero or more road restrictions applying to the work zone road segment associated with the work zone. Optional These are included as flags rather than detailed restrictions. Detailed restrictions are coded to specific lanes.

Used By

Property Object
properties RoadEventFeature

Important Notes

None

Changes to the Detour Event Object

Requirements: Include the RoadEvent object and carry only the properties necessary to describe a detour segment.

DetourEvent Object

The DetourEvent object contains information that describes where, when, and what activity are taking place in a detour, along a road segment.

Properties

Name Type Description Conformance Notes
road_event RoadEvent Describes the basic characterisitics of a Road Event. Required
start_date String; date-time The UTC time and date when the event begins. Required All datetime formats shall follow RFC 3339 Section 5.6. Example: 2016-11-03T19:37:00Z.
end_date String; date-time The UTC time and date when the event ends. Required All datetime formats shall follow RFC 3339 Section 5.6. Example: 2016-11-03T19:37:00Z.
start_date_accuracy TimeVerification A measure of how accurate the start Date Time is. Required
end_date_accuracy TimeVerification A measure of how accurate the end Date Time is. Required
beginning_cross_street String Name or number of the nearest cross street along the roadway where the event begins. Optional
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. See also the lrs_type property on the RoadEventDataSource object.
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. See also the lrs_type property on the RoadEventDataSource object.
event_status EventStatus The status of the event. Optional

Used By

Property Object
properties RoadEventFeature

Important Notes

None

Changes in P.R.

  1. Normalize Road Event: This is a major change that breaks backwards compatibility. Recommended to foster scalability and for data storage, exchange, and publication efficiency. This action derives/creates: 1.1. A normalized RoadEvent feature 1.2. A new event_type value called “road” so a RoadEvent object can be instantiated. 1.3. A Normalized WorkZoneEvent 1.4. A Normalized DetourEvent

  2. Rename WZDxFeed to RoadEventFeed: This is an editorial change and has no effect on feed publication. Recommended because it aligns with the specification’s naming conventions and it more accurately reflects what the feeds are.

  3. Update Examples (Not included in this pull request): Update examples to reflect new data model and formatting. I did not attempt this because I’m not sue what the other pull requests are changing.

  4. Update Data Model (Not included in this pull request): I did not attempt this because I’m not sue what the other pull requests are changing. 4.1. Update the RoadEvent, WorkZoneEvent, and DetourEvent objects in the data model. Ensures the specification and the model agree. 4.2. Insert the RoadEventFeatureCollection: This is an editorial change and has no effect on feed publication. Recommended because it more accurately reflect how the feeds are publish and better aligns with the GeoJSON specification

j-d-b commented 3 years ago

@DeraldDudley thanks for starting this PR. I agree that separating the road event core information from the properties specific to the type of road event is important for scalability. I generally support the changes described in the PR comment.

I skimmed the files changed but have not reviewed in depth yet. As you noted in the "Changes in this PR", the PR is not complete/should not be merged as the examples and several READMEs need to be updated and that cannot happen without the other v4.0 changes being completed first. If this was merged there would be massive merge conflicts requiring hours of manually merging as the other v4.0 changes were merged. Thus I converted this PR to a draft to clarify it is not ready to be merged into the release branch.

j-d-b commented 2 years ago

Updates following spec update subgroup meeting:

j-d-b commented 2 years ago

As I was working on the PR for the smart work zone field devices (see #195), I had a thought regarding the name of the work zone road event. In this PR the object is named WorkZoneEvent. I first thought, how about WorkZoneRoadEvent, as it is more clear, since it is a road event with type work-zone. The WorkZoneRoadEvent name makes it easy to tell that the object is a type of road event and will contain the RoadEventCoreDetails and occur within a RoadEventFeature.

I then thought, maybe the benefit of the suffix convention doesn't matter that much and the object should just be called WorkZone.

Edit: WorkZone is not as semantic as a WorkZoneRoadEvent may not be a work zone itself, just part of a work zone.

In summary, I like WorkZone or WorkZoneRoadEvent more than am fine with WorkZoneEvent.

j-d-b commented 2 years ago

Regarding the following:

Rename WZDxFeed to RoadEventFeed: This is an editorial change and has no effect on feed publication. Recommended because it aligns with the specification’s naming conventions and it more accurately reflects what the feeds are.

A concern with this change is that it precludes this feed from being able to include any other features except road events. Changing the name of the WZDxFeed to RoadEventFeed is taking the approach that a "feed" should be defined by the content, rather than the use case or intended consumer (see this comment in #191).

So let's step back to the definition of a feed: a feed is a is a way of delivering structured data from one system to another. In WZDx, the structure of the data provided by a feed is defined by a single object (containing many sub-objects) which appears the content of a GeoJSON file. In WZDx, the root (highest level) object is a GeoJSON FeatureCollection containing information about the feed (RoadEventFeedInfo) and a list of RoadEventFeatures.

New feeds that were discussed, such as a structures feed, field devices feed, or smart work zones only differ by what types of features they allow in the "features" array of the feed (FeatureCollection) object. Specifically, the RoadEventFeed allows only RoadEventFeatures, the smart work zones feed allows RoadEventFeatures and FieldDeviceFeatures, and the field devices feed allows only FieldDeviceFeatures. Maybe the "WZDxFeed" can be a comprehensive feed allowing all types of features defined in WZDx.

Or, WZDx can just define one feed (the WZDxFeed) and separating that feed into smaller feeds with sub-sets of content is outside the realm of the specification and up to the producer. For example, a producer could provide a URL which is a WZDx feed that contains only work zones, another URL for a feed with just restrictions, and another for field devices. All feeds would be valid WZDx feeds, however, the WZDx spec only defines the one feed that could contain all information.

We have to make a decision on this before this PR or the PR for #195 can be finalized.

j-d-b commented 2 years ago

@DeraldDudley I created #209 to supersede this PR and tagged you as a reviewer.