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

Refactor the RoadEvent to extract shared core details for scalability #209

Closed j-d-b closed 2 years ago

j-d-b commented 2 years ago

This PR addresses #203 and provides an alternate (superseding) implementation of #204.

Specifically, it involves:

New Objects

Object Description
DetourRoadEvent A detour on a roadway.
RoadEventCoreDetails The core details of an event occurring on a roadway (i.e. a road event) that is shared by all types of road events.
WorkZoneRoadEvent A work zone road event including where, when, and what activities are taking place within a work zone on a roadway.

Example feeds: representing a work zone before and after this change

Before

{
   "road_event_feed_info": {
      "location_method": "sign-method",
      ...
   },
   "type": "FeatureCollection",
   "features": [
      {
         "id": "71234",
         "type": "Feature",
         "properties": {
            "data_source_id": "1",
            "event_type": "work-zone",
            "road_names": [
               "I-80, I-35"
            ],
            "direction": "northbound",
            "beginning_accuracy": "estimated",
            "ending_accuracy": "estimated",
            "start_date": "2010-01-01T01:00:00Z",
            "end_date": "2010-01-02T01:00:00Z",
            "start_date_accuracy": "estimated",
            "end_date_accuracy": "estimated",
            "event_status": "active",
            "vehicle_impact": "some-lanes-closed",
            "reduced_speed_limit": 55,
            "description": "Single direction work zone without lane-level information.",
            "creation_date": "2009-12-31T18:01:01Z",
            "update_date": "2009-12-31T18:01:01Z"
         },
         "geometry": {
            "type": "LineString",
            "coordinates": [...]
         }
      }
  ]
}

After

{
   "road_event_feed_info": {...},
   "type": "FeatureCollection",
   "features": [
      {
         "id": "71234",
         "type": "Feature",
         "properties": {
            "core_details": {
                "data_source_id": "1",
                "event_type": "work-zone",
                "road_names": [
                   "I-80, I-35"
                ],
                "direction": "northbound",
                "description": "Single direction work zone without lane-level information.",
                "creation_date": "2009-12-31T18:01:01Z",
                "update_date": "2009-12-31T18:01:01Z"
            },
            "beginning_accuracy": "estimated",
            "ending_accuracy": "estimated",
            "start_date": "2010-01-01T01:00:00Z",
            "end_date": "2010-01-02T01:00:00Z",
            "start_date_accuracy": "estimated",
            "end_date_accuracy": "estimated",
            "event_status": "active",
            "vehicle_impact": "some-lanes-closed",
            "location_method": "sign-method",
            "reduced_speed_limit": 55
         },
         "geometry": {
            "type": "LineString",
            "coordinates": []
         }
      }
  ]
}

Note the only differences are:

  1. Some of the properties on the road event are now nested within the core_details property.
  2. The location_method property moves from the road_event_feed_info to the road event.

Notes about this PR

This PR is a draft for demonstration of the new model and how it will be integrated into the WZDx specification. The PR is a draft as it should not be finalized or merged until other v4.0 PRs are merged to the release branch (v4.0-release) as it would create a large amount of unresolvable merge conflicts and a lot of manual work. This PR does not update examples files or the object diagram. It does include fully complete documentation for all the new objects and an updated JSON schema (wzdx_v4.0_feed.json).

j-d-b commented 2 years ago

From discussion with @mark-mockett it was noted that the location_method property on the RoadEventDataSource is specific to work zones. All other work zone-specific properties are being deprecated or removed in other v4.0 PRs. Thus the location_method property should move to the WorkZoneRoadEvent object which makes the RoadEventDataSource fully generic.

This does lead to a bit of data duplication (there is a reason the location method was on the data source level), but as the data source is not specific to work zones, it needs to happen as part of this "normalization".

Edit: alternatively, we could just remove the location_method concept. As a work zone is separated into multiple work zone road events, it is hard to know a consumer would use location_method.

j-d-b commented 2 years ago

@DeraldDudley

Are we still renaming WZDFeed to RoadEventFeed?

This still needs to be discussed, see https://github.com/usdot-jpo-ode/wzdx/pull/204#issuecomment-921862897. I was drafting an email to all co-chairs about this earlier today as it affects the SWZ field devices work as well. Relatedly, the RoadEventDataSource and RoadEventFeedInfo should be renamed to be generic so they can be used by "feeds" containing features other than road events. I think the feed info/data source renaming and renaming the WZDxFeed object can be considered separate from the scope of this PR, as the changes implemented still apply and are helpful regardless of that change.

References to WZDx should be removed from object/features that are not specific to the WorkZoneRoadEvent. (Editorial changes that don't need formal review).

I'll look for some of these now and make those changes.

ekolb1 commented 2 years ago

From discussion with @mark-mockett it was noted that the location_method property on the RoadEventDataSource is specific to work zones. All other work zone-specific properties are being deprecated or removed in other v4.0 PRs. Thus the location_method property should move to the WorkZoneRoadEvent object which makes the RoadEventDataSource fully generic.

This does lead to a bit of data duplication (there is a reason the location method was on the data source level), but as the data source is not specific to work zones, it needs to happen as part of this "normalization".

Edit: alternatively, we could just remove the location_method concept. As a work zone is separated into multiple work zone road events, it is hard to know a consumer would use location_method.

As a consumer, we rely on the geometry to match the Event location to our road network. In the cases where supplied RoadEventFeature geometry cannot be confidently matched to our road network, would we look to other object attributes for additional contextual information helpful for solving matching ambiguities. With that said, Event object attributes most useful would be: beginning_cross_street and ending_cross_street. The only potential location_method value that could be similarly useful is: junction_method. However, junction_method values would be largely redundant in what is provided in beginning_cross_street and ending_cross_street.

j-d-b commented 2 years ago

After @CraigMoore-Sea's comments in today's (2021-09-23) subgroup meeting, I support keeping WZDx restricted to describing temporal events that represent a change to the base/default configuration of the roadway.

Thus, the following properties should be added to the RoadEventCoreDetails (and removed from the DetourRoadEvent and WorkZoneRoadEvent):

In addition, I think the following should also be added, as they are just helpful contextual information about the location of the road event and do not replace the geometry or require that the geometry exactly matches the cross streets:

The following I could see potentially being added, as I can't imagine a type of road event where there would be no relevance to the accuracy of the start/end geometry (see also #199):

davidcraig4300 commented 2 years ago

After reflecting on yesterday's Core Details conversation, I have a few observations:

  1. Creating the "Core Details" is directionally correct and desired by all. So, this is good and needs to be done.
  2. I also want to remind everyone that we try to operate as a Agile framework design. Take a best effort approach, then tweak it in future releases.
  3. Most people will have their own "essential element" and will lobby for that to be included in the Core Details. But, if everything gets included in the Core Details, then we have accomplished nothing.
  4. Therefore, I am suggesting that we implement PR-209 as it is currently constructed, without cross streets and without date information for this release. Remember, just because it is not part of the Core Details, doesn't mean that it will not be part of the specification. Temporal date information is still very much a part of the specification.
  5. Then if at some-point in the future, if we decide we absolutely need to elevate an element to the Core Details, we will modify the spec.
  6. We need to remember that the spec is growing and could soon be used to convey non ending information. So, forcing date elements as Core Details will force data producers to create false start and end dates, i.e. start date of 1900 and end date of the year 3000, which is meaningless data and has no value.
CraigMoore-Sea commented 2 years ago

@davidcraig4300 makes some strong points that I agree with; it's more important that we implement core details now, which will allow for logical expansion of the specification to other road events, than to battle over the elements to be included.

That said, I still strongly support the idea that WZDx should represent temporal changes to the road network and not the road network itself. This discussion about the strategic direction of the specification should be carried out at the highest levels of the specification governance and not just in the technical specification working group.

On a related note, we have struggled with this very issue in Seattle where we have a long-term, unplanned closure of a major bridge that we struggle to effectively communicate to data consumers. There is no guidance yet on when a change is temporal versus a change to the network. In our case the bridge closed in March of 2020 and will reopen someday but we don't have an exact date yet; maybe in 2023 if all goes to plan.?

j-d-b commented 2 years ago

@chuehlien thanks again for the thorough review.

As for the items awaiting updating:

  1. The examples are waiting for all the non-draft v4.0 PRs to be merged to the v4.0-release branch, then the v4.0-release branch can be merged in here, then the examples can be updated. That ordering is to help limit merge conflicts. They can be done alongside the diagram.
  2. Merge conflicts will likely not be an issue on /create-feed/README.md so we can make any needed changes there now. I will look it over now and make any I see, please feel free to do the same.
j-d-b commented 2 years ago

@sknick-iastate I merged in v4.0-release and this PR is now ready to have the examples updated.

Thanks!

j-d-b commented 2 years ago

@chuehlien and @mark-mockett, this PR is now ready for final review.

j-d-b commented 2 years ago

@mark-mockett thank you for reviewing. I'm going to merge it now (without @chuehlien's review) so I can start on the remaining PRs.

@chuehlien I will wait to tag you until the final PR for merging the v4.0-release branch into main.

@mark-mockett I'll tag you in the other PRs as soon as they're ready.