Specification Update Subgroup meeting Apr 4, 2022

Meeting Information

Date: April 04, 2022

Objectives

• Continue discussion of outstanding GitHub issues.
• Review proposed approaches to modifying the specification through Pull Requests (PRs).

Agenda

• Sign-in and Welcome
• Highlight PRs from Other Subgroups
• Review Implementation via Pull Requests
  • Recommend Unique Universal IDs for Road Events – PR #278
  • Rename road_event_feed_info for Consistency – PR #268
  • Use Boolean Properties for Location Verification – PR #281
• Discuss Issues
  • Event Status Values - Issue #189
  • Clarify Usage of RoadEvent update_date - Issue #184
  • Refactoring Relationships - Issue #197
  • Mobile Work Zones - Issue #125
• Action Items and Next Steps

Materials

• Meeting presentation

Minutes

Highlight PRs from Other Subgroups

For those who haven't attended other subgroups, we wanted to highlight the PRs that those groups have created in case folks want to join in on discussion of those issues.

Change traffic sensor traffic data properties from Integer to Number value type – PR #228

• Change the average_speed_kph, occupancy_percent, and volume_vph properties type on the TrafficSensor and TrafficSensorLaneData objects from "integer" to "number"
• Change adds flexiblity when reporting these values

Add road_direction property to FieldDeviceCoreDetails – PR #273

• Add optional road_direction property (for named direction of a roadway) to the FieldDeviceCoreDetails object, which applies to every field device
• Move the "Direction" JSON Schema type definition to it's own JSON file and generalize its description and reference the moved "Direction" type from SwzDeviceFeed and RoadEventFeature schemas

Allow lane-level traffic sensor data without a defined road event – PR #267

• Change the conformance of the road_event_id property on the TrafficSensorLaneData object from Required to Optional.
• This makes the specification easier to implement by making the road_event_id optional

Add is_moving to FieldDeviceCoreDetails – PR #266

• Add optional is_moving property to the FieldDeviceCoreDetails object to allow representing if a device is actively moving.
• is_moving was already a property of arrowboards - deprecate the existing is_moving property as the new is_moving property on the FieldDeviceCoreDetails should be used instead.

Our plan is to review all the pull requests for other subgroups so that folks are aware at a high-level, but if participants have any comments please reach out to the subgroup that put it together.

Recommend Universal Unique IDs for Road Events – PR #278

• Currently, WZDx RoadEventFeature id is allowed to be any string. This makes it difficult to relate two road events or a road event with a field device because IDs may not be unique.
• A Universally Unique Identifier (UUID) is a 128-bit ID that guarantees uniqueness across time and space.
  • Example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
• To maintain backward compatibility, recommend using UUIDs for RoadEventFeature IDs in v4.1.
• Add new property for human-readable road event name.
  • UUIDs are currently recommended for SwzDeviceFeed IDs
  • UUIDs could be required in a future major version of the spec (i.e. v5.0)

Rename road_event_feed_info for Consistency – PR #268

• All three feeds in WZDx v4.0 both use the FeedInfo object, but it occurs on differently named properties
  • Not technically renaming, because we're deprecating the current property
• To maintain backwards compatibility, deprecate the road_event_feed_info property and add a feed_info property. Both could contain the FeedInfo object. • Remove the road_event_feed_info property in a future major release

Use Boolean Properties for Location Verification – PR #281

• Since there are only two "useful" EventStatus values and there's nothing else we're likely to add, this PR effectively replaces those properties with Booleans by adding new properties and deprecating the current ones
• Deprecate the beginning_accuracy and ending_accuracy properties on the WorkZoneRoadEvent.
• Add new boolean properties to the WorkZoneRoadEvent to indicate if the work zone start and end position (first and last geometric coordinate pair, respectively) are based on actual reported data from a GPS-equipped device.
• Conditionally require either beginning_accuracy/ending_accuracy or new is_start_position_verified/is_end_position_verified.

Event Status Values - Issue #189

There are currently 5 enumerations for EventStatus, but we question whether all of these are necessary

• planned: Planned status is associated with overall project or phase timing and locations. Typically, this information is estimated during planning or early design phases. The WZDx will not generally include planned activities.
• pending: Pending is used to alert stakeholders that work is scheduled for the near future (e.g., 2-3 weeks). The certainty of starting at this time is greater than 90% (barring weather and other unforeseen circumstances).
  • Time horizon: approximate begin / end dates
  • Location: coverage area and main road name; path (polyline or geoface) around zone area
• active: Used to alert stakeholder that work zone is in place and active.
• cancelled: Reported cancellation of a proposed or active work zone; the coverage applies to the work zone activity record. When date/time is estimated, the cancellation may be one or more days associated within the reported scheduled datetimes
• completed: Work zone is closed and completed; all work zone impacts are mitigated. This status may be used when a work zone activity is completed earlier than expected.

Given the nature of WZDx feeds, the two statuses that make the most sense in WZDx feeds are planned and active.

• Is our understanding of how the event status would be used how others would use it?
• Based on narrowing it down to two statuses, is there a reason to keep them as enumerations versus switching to a Boolean?
  • If active and planned are usually based on the start time, do we need the indicator of work zone status? Could we use an is_active field instead? We started having that discussion as co-chairs
  • Skylar: Based on the implementation in Iowa - whenever current time is past the listed start time, we list the work zone as active Start time and verification are already required in the specification, but the description should likely be updated to clarify how they should be used

Discussion

Chris Brookes: If we have a freeway closure planned to start at 8:00 but now will start at 10:00 - it would work to change the start time, but how are people going to bet the pre-trip planning a few hours in advance?

• Chris: If there's not a trigger in the field turning it active. If you're planning it to be at 8:00, you're saying there's a higher probability of it being there. The fluff there from the planned work that hasn't actually started yet would be missing.
• Skylar: I'm not sure if there's anything in WZDx that helps with that right now
• Jacob B: I think that information comes best from the start/end date accuracies - those indicate whether we're sure that something is active. is_active or event_status doesn't gurantee that.
• Jacob B: Removing event_status puts more emphasis on start date and end date accuracy
• Skylar: Even with the statuses, if you don't change the start date and still say it's planned after the start time, that causes confusion with data consumers (who would be unsure whether to ignore)

Nisar: We've heard from our stakeholders that their event isn't active until someone in the field puts the first cone down, but the date is put in the system based on the request from the contractor. It doesn't mean they'll start at the time when they're permitted to - they might start later, but can't start before. If event has moved from planned to active, then the start time should be adjusted in the data feed. We are getting data from multiple stakeholders. We have a device in the field but can't change the time when they're saying 'we're active'

Eric: From our side, we use start time to determine whether to publish a restriction or closure and that's worked well for us. Additionally, if we go with verification it'd be best to make it a requirement, then we can use that to publish.

• Skylar: The start_date_accuracy field is required, but whether it gets used is not always the case.
• Eric: If it's socialized that the verification is required to be used, then we'd use it.

Eli: Is the assumption of removing event_status mean you default to the calendar start/end dates and using those as live? If that's the full reasoning, the question I have based on planning: knowing there is going to be a closure 30 minutes from now is useful. If we remove that and say to only use the actual start time

• Skylar: The start time and end time would be estimated until the event actually starts. Eric could speak to whether events are used for planning purposes, and that's up to data consumers
• Eric: In our production logic, we'll look at planned restrictions up to 3 weeks in the future and undertake processing of anything in that window and can undertake pre-publishing processing and flip the switch once the start time is met
• Eric: If we can additionally have verification of whether an event is live or not. Start date accuracy seems like a good play for us, or event status as propsoed. Any other verification that an event is actually live is useful Nisar: Where is the issue with using status active as being verified?
• Eric: We're still in the process of ingesting WZDx feeds, but other feeds we ingest don't have that verification. We'd use one of the two fields - or the existing one
• Skylar: To clarify, both of these are currently in the spec and verification is required, status is optional. And the active/planned fields aren't intended for verification - just what the agency says the event status is.

Nisar: I'm not sure about that - we are getting these data and publish whether or not a consumer uses it.

• Jacob B: That's why we disagree - removing ambiguity / redundancy helps data consumers.
• Nisar: How would we use this for a planned event. When the event starts, then the verification field becomes true?

Skylar walked through an example of the stages of activating a work zone a bit after the start/date - will be added to GitHub issue soon

• Nisar: So until the start/date accuracy becomes verified, users will show it with less certainty?
• Eric: From the changing of route algorithms perspective, it wouldn't change until the verified.
• Skylar: But you're talking about the event status in the way that we would want to use the start/date accuracy, and that's why we see it as redundant.
• Nisar: I'm still thinking about this - it may remove some level of flexibility and I'll discuss with our stakeholders.
• Skylar: For our next meeting I'll put together an example to walk through to make clear what we're trying to walk through.
• Jacob B: I also recommend checking out the issue posted in the chat about how it can be more confusing the way the spec is now.

Clarify RoadEventCoreDetails update_date - Issue #184

RoadEventCoreDetails update_date is defined as "The UTC time and date when the activity or event was last updated.

• It's beneficial for us to know when the information at the road event level was last changed, but it's unclear how to use this field now
• Most systems already cover this information, so we think requiring it in the future is attainable - but first we need to clarify when it should update:
  • Change to any element in the road event?
  • Change to location or status?
  • Other enumeration?

Currently update date is on the RoadEventCoreDetails, FeedInfo, and FeedDataSource

• Jacob B: I was proposing making this issue to make clear that it should be updated when any property changes, and applying the same standard to the field device

Two questions:

• What are thoughts on rules for updating the RoadEvent update date?
• Thoughts on when feed level update date should be updated?

Discussion

Chris Lambert: We think of update date as the time of publishing. We have an update date at the feed level when something is published

• Skylar: The feed level update date could reflect that. Does your system keep that information for events too?
• Chris Lambert: Interesting you say update - clarifying where that happens would be interesting. Lots of people in the chain

Refactoring Relationship Object - Issue #197

We don't have a clear solution for this yet, but we wanted to run it by everyone since it does relate to the other things we're working on.

The Relationship object is intended to be used to specify relationships between road events

• Currently is not well defined and clarified how it can be used
• Proposal to re-define relationships specific to work zone/detours

Related Entities would define what entities it's related to in WZDx more explicitly

Types of related entities we want to include:

• Work zone project - identify road events that are all part of the same project by pointing to the same project ID number. This would be new functionality - would point to an ID that does not correspond to an object in a WZDx feed.
• Work zone phase
• Recurrent work zone - for a series of road events that are the representation of recurring work
• first road event - the first road event in a sequence
• next road event - the subsequent road event in a sequence
• detour road event - road event describing a detour for the work zone

With this proposal:

• Simple, single event work zone: No changes.
• Three-event work zone: All events would be under the same work zone project - the arrows at the bottom show the relationship between the road events
• Work zone affecting both directions: Work zones on the same road but in opposite directions can use the project to identify the relationship without

Discussion

Chris Brookes: If we have a 15 mile work zone with workers for the first mile, how do we break that up and segment to make that clear where workers are?

• Skylar: I submitted an issue to define when work zones need to be split into multiple road events [that issue has since been closed - #178]

Participants

Name	Organization
Randy Jackson	Applied Concepts
Marty Lauber	Arizona DOT
Jackie Beckwith	Association of Uncrewed Vehicle Systems International
Mahsa Ettefagh	Booz Allen Hamilton
David Aylesworth	CeVe
Jacob Larson*	City of Omaha
David Craig^	General Motors
Eli Sherer	GEWI
Eric Kolb	Google
Weimin Huang	HERE
Casey Inoue	Houston Radar
Jacob Brady*	IBI Group
Sinclair Stolle	Iowa DOT
Skylar Knickerbocker*	Iowa State University
Chris Lambert	Kentucky Transportation Cabinet
Brandon Saylor	Kentucky Transportation Cabinet
Samer Rajab	Locomation
Neil Boudreau	Massaschusetts DOT
Nisar Ahmed	Metropolitan Transportation Commission (San Francisco Bay)
Chris Brookes	Michigan DOT
Dan Oesch	Missouri DOT
Navin Nageli	Navjoy
Tony English	Neaera
Tim Fiato	New York State DOT
Adam Graham*^	one.network
Chad Mann	Oregon DOT
Devorah Henderson	Qlynx Tech
Sabrina Mosher	Southwest Research Institute
Yang Cheng	University of Wisconsin-Madison
Nate Deshmukh-Towery^	USDOT Volpe Center
Mark Mockett	USDOT Volpe Center
Molly Behan	USDOT Volpe Center
Pier Castonguay	Ver-Mac
Tony Leingang	Washington State DOT
Qassim Abdullah	Woolpert

* Co-Chair of Spec Update Subgroup
^ Co-Chair of Work Zone Data Working Group