WZDx v4.0

[j-d-b]

WZDx v4.0

WZDx version 4.0 implements clean up and small additions in functionality to the WZDx feed and adds definitions for two new feeds, the SwzDeviceFeed and RoadRestrictionFeed. Until version 4.0, the WZDx specification defined only one feed, the WZDxFeed.

Features

• Add the following values to the VehicleImpact enumerated type:
  • some-lanes-closed-merge-left
  • some-lanes-closed-merge-right
  • all-lanes-open-shift-left
  • all-lanes-open-shift-right
  • some-lanes-closed-split
  • flagging
  • temporary-traffic-signal
• Allow restrictions with a value and unit to be provided at the road event level; specifically:
  • Rename the LaneRestrictionUnit enumerated type to UnitOfMeasurement.
  • Rename the RoadRestriction enumerated type to RestrictionType.
  • Rename the LaneRestriction object to Restriction and remove the lane_restriction_ prefix from its properties.
  • Rename the Restriction object units property to unit.
• Add values parking and median to the LaneType enumerated type.
• Define a new data feed, the RoadRestrictionFeed and RestrictionRoadEvent to enable providing a feed of restrictions on roadways, such as bridge clearances.
• Define a new data feed, the SwzDeviceFeed, to enable equipment vendors and manufacturers to provide high-level information about deployed field devices in work zones. A SwzDeviceFeed contains a new feature type, the FieldDeviceFeature, which contains information about a specific type of field device. The following field devices are defined in WZDx v4.0:
  • ArrowBoard: An electronic, connected arrow board which can display an arrow pattern to direct traffic.
  • Camera: A camera device deployed in the field, capable of capturing still images.
  • DynamicMessageSign: An electronic traffic sign deployed on the roadway, used to provide information to travelers.
  • FlashingBeacon: A flashing beacon light of any form (e.g. trailer-mounted, vehicle), used to indicate something or capture driver attention.
  • HybridSign: A hybrid sign that contains static text (e.g. on an aluminum sign) along with a single electronic message display, used to provide information to travelers.
  • LocationMarker: Describes any GPS-enabled ITS device that is placed at a point on a roadway to dynamically know the location of something (often the beginning or end of a work zone).
  • TrafficSensor: A traffic sensor deployed on a roadway which captures traffic metrics (e.g. speed, volume, occupancy) over a collection interval.
• Rename the workers_present property on the WorkZoneRoadEvent object to worker_presence; change the type from "boolean" to a new WorkerPresence object which enables providing more nuanced information about worker presence in work zones.

Refactoring

• Separate the v3.1 RoadEvent object into RoadEventCoreDetails (details that are shared by all specific types of road events) and specific types of road events (WorkZoneRoadEvent, DetourRoadEvent, and RestrictionRoadEvent) which each contain the RoadEventCoreDetails via a core_details property; update the RoadEventFeature properties property to be one of the specific road events types.
• Move the location_method property from the FeedDataSource object to the WorkZoneRoadEvent object.
• Change the reduced_speed_limit property on the WorkZoneRoadEvent to reduced_speed_limit_kph; change its type from "integer" to "number" and clarify that the value should be in kilometers per hour.
• Deprecate the lane_number property on the Lane object.
• Deprecate the lrs_type and lrs_url properties on the FeedDataSource object.
• Remove the deprecated value alternating-one-way from the LaneStatus enumerated type.
• Remove the following deprecated properties from the road event (RoadEvent in previous versions; WorkZoneRoadEvent and RoadEventCoreDetails in 4.0):
  • road_event_id
  • road_number
  • road_name
  • total_num_lanes
• Remove the following deprecated values from the LaneType enumerated type:
  • left-lane
  • right-lane
  • middle-lane
  • center-lane
  • right-shoulder
  • left-shoulder
  • right-second-exit-ramp
  • left-second-exit-ramp
  • right-entrance-exit-ramp
  • left-entrance-exit-ramp
  • hov-lane
  • alternating-flow-lane
  • reversible-lane
  • right-entrance-lane
  • left-entrance-lane
  • left-entrance-ramp
  • right-merging-lane
  • left-merging-lane
  • right-second-entrance-ramp
  • left-second-entrance-ramp
• Require the road_names property on the RoadEventCoreDetails.
• Require the id property on the RoadEventFeature.
• Refine the LaneType enumerated type; specifically:
  • Rename lane to general.
  • Remove right-turning-lane and left-turning-lane.
  • Remove right-exit-lane and left-exit-lane.
  • Add exit-lane.
  • Remove right-exit-ramp and left-exit-ramp.
  • Add exit-ramp.
  • Remove right-entrance-ramp and left-exit-ramp.
  • Add entrance-ramp.
  • Add entrance-lane.
• Deprecate the location_verify_method property on the FeedDataSource.
• Update the SpatialVerification enumerated type value descriptions to clarify that verified work zone locations should use a GPS enabled device.

[j-d-b]

I added release notes—note that the content of the Release Notes section in the project README is identical to the v4.0 section in RELEASES.md and the first PR comment above.

I was thinking we should slim down to the Release Notes section of the project README and leave the detailed notes in the RELEASES.md, what do you think?

[mark-mockett]

I was thinking we should slim down to the Release Notes section of the project README and leave the detailed notes in the RELEASES.md, what do you think?

I agree, especially considering how long this version's notes are.

[j-d-b]

I agree, especially considering how long this version's notes are.

I revised the Release Notes section of the project README to remove some specifics (such as the sub-lists).

[chuehlien]

Added a couple of comments. Please double check my changes, since I'm not 100% sure about some of the ones I've made relating to the field device that referenced RoadEvents. I've only reviewed the RoadRestrictionFeed and WZDxFeed contents and have not reviewed the json schema, example files, and only skimmed the example README - hope others are able to provide coverage for those. Good work, all!

[j-d-b]

Added a couple of comments. Please double check my changes, since I'm not 100% sure about some of the ones I've made relating to the field device that referenced RoadEvents.

@chuehlien your review was excellent and fixed a lot of issues. Thank you so much. I updated two of your edits regarding the use of the TrafficSensorLaneData (this object's tie to the road event is a bit confusing).

If you can make any time to review the schemas at any point, even if it's after the release, I'd really appreciate it as I bet you would find some issues given what you found in the markdown files.

Eventually, I think it would be ideal if the JSON schema is all that we maintain and we can auto-generate more human-friendly docs from it assuming there are acceptable tools for that (e.g. json-schema-for-humans).

[j-d-b]

should the WZDx feed also be changed to feed_info?

I would like that, but I brought that up at a spec update co-chairs meeting (near the end of the meeting) and at that time the consensus was (which I understood) that it was another breaking change for minimal reason.

However seeing that we don't want to do another major release anytime soon and the change would great greater consistency and less stuff that is only that way for historical reasons, I think we should do it. It's a trivial from a development perspective.

@mark-mockett, @sknick-iastate I think if you both are for it (renaming the WZDxFeed road_event_feed_info property to feed_info for consistency with the RoadRestrictionFeed and SwzDeviceFeed), let's do it.

[sknick-iastate]

should the WZDx feed also be changed to feed_info?

I would like that, but I brought that up at a spec update co-chairs meeting (near the end of the meeting) and at that time the consensus was (which I understood) that it was another breaking change for minimal reason.

However seeing that we don't want to do another major release anytime soon and the change would great greater consistency and less stuff that is only that way for historical reasons, I think we should do it. It's a trivial from a development perspective.

@mark-mockett, @sknick-iastate I think if you both are for it (renaming the WZDxFeed road_event_feed_info property to feed_info for consistency with the RoadRestrictionFeed and SwzDeviceFeed), let's do it.

Just throwing it out there but what are your thoughts on changing the restriction to road_event_feed_info? Then also changing the SwzDevice to swz_device_feed_info? I know it breaks the consistency but really these would not be in the same feed since it is different producers/consumers.

[j-d-b]

Just throwing it out there but what are your thoughts on changing the restriction to road_event_feed_info? Then also changing the SwzDevice to swz_device_feed_info?

Since the properties use the same object (the FeedInfo object), I think it is more clear to have the property name be the same for all feeds.

In addition, the WZDxFeed could be expanded to include things that are not road events and then the road_event_feed_info would be incorrect.

[mark-mockett]

@j-d-b @sknick-iastate I agree that it'd be cleaner to have each feed info property called the same thing. But I'm also reluctant to make several last-minute revisions that don't improve functionality of the spec (applies to this requiring LineString geometry for detours)

[mark-mockett]

@j-d-b I need some help understanding what I (accidentally) did with the "Merge branch v4.0 release" commit and its reversion - I switched over to the desktop version of GitHub, and it looks like the first commit just redid all the changes that have been made since the last merge (even though they were already committed). I reverted it but now all those changes are gone. Do I revert the reversion??

[sknick-iastate]

@j-d-b should the road_event_id be removed from the MarkedLocation Object? It seems redundant since the FieldDeviceCoreDetails already includes the road event id's. I can't think of a scenario where this information would be different but wanted to verify in case I was overlooking something.

[j-d-b]

I agree that it'd be cleaner to have each feed info property called the same thing. But I'm also reluctant to make several last-minute revisions that don't improve functionality of the spec (applies to this requiring LineString geometry for detours)

I think the only revisions we should make right now are those that don't change the functionality of the spec! As for the specific proposal of renaming road_event_feed_info to feed_info, I'll make an issue for it to address next cycle.

should the road_event_id be removed from the MarkedLocation Object?

Good thought and I'd like to continue the discussion but I think this is too major of a change to make now. Can you make an issue for this?

[sknick-iastate]

@j-d-b sounds good on the MarkedLocation issue. I have a couple others written out as well but was waiting for v4.0 release to be merged so I can link to the relevant information directly.

[j-d-b]

I need some help understanding what I (accidentally) did with the "Merge branch v4.0 release" commit and its reversion...

@mark-mockett I see you reverted the revert commit. That was the right call. It looks like the merge commit was just catching up/combining your local copy to what was new on remote since last time you were working locally.