This issue is a replacement of the older PR #34, which was pre-v2 and not properly discussed in an issue prior to the PR creation.

Several subgroup members have expressed interest in adding detour information to the road_event entity.

The original PR was based on MassDOT's use case, which is a human-readable text description of detour information, if available. This would be accomplished simply by adding an optional text field to the road event entity called detour_information. Producers and consumers use this as they wish.

Others suggested having a linestring geometry for the detour and/or other mapping/machine-focused detour information would be helpful.

This issue is intended to be used to discuss what consumers would like to get out of the detour information and thus inform what should be added to the spec.

The project root README.md timestamp is outdated.

This issue was spawned during discussion about solutions for #66.

There appears to be great interest removing the ability for a producer to choose the side (left or right) from which lane number counting begins and instead standardizing the side as part of the WZDx specification.

#66 was more specifically resolved in #97, intended for the v3.0 release, without standardizing the counting start side. Thus this issue is intended to be a place to continue the discussion regarding standardizing the start side.

I know @davidcraig4300 has some thoughts on this.

The version property on the road_event_feed_info entity is described as

The specification version used to create the dataset

This is a text field with no further indication of how the version should be represented, that is, v2.0, V2, 2, 2.0, etc.

This should be standardized, either with clarifying text + a regex in the JSON schema or by creating an enumeration for all the possible feed versions.

My choice for a format for this field would be 2 if we are going to continue release only major versions, and 2.0 if we want to consider minor releases.

There are not currently any versioning rules or conventions defined for WZDx. On the April 29th WZDx v3 Spec subgroup meeting, the desire for a defined versioning scheme was expressed. Having rules for versioning can illustrate what happened between WZDx versions just from the version number.

One of the most of famous and widely used versioning rule specifications in software is the Semantic Versioning Specification, commonly known as SemVer.

Full SemVer rules are defined at https://semver.org/ in a clear format. As a summary:

• The version number must follow major.minor.patch
• The patch version must be incremented if only backwards compatible bug fixes are introduced
• The minor version must be incremented if new, backwards compatible functionality is introduced or any functionality is marked as deprecated
• The major version number must be incremented if any backwards incompatible changes are introduced

For the WZDx specification, this could look like:

• The patch version must be incremented for text documentation/business rule changes that don't affect the structure of the feed
• The minor version must be incremented if new, backwards compatible fields/entities/enumerations are introduced or if any existing fields/entities/enumerations are marked as deprecated
• The major version number must be incremented if any backwards incompatible changes are introduced

Thus far, the WZDx specification has performed updates in bulk in long iteration cycles. Using SemVer would facilitate shorter cycles in the long term, and in the short term, even for the immediate v3 release cycle, we could perform multiple small releases subsequently at the end of the v3 update process after all PRs for v3 are approved. For example, we could introduce all the non-breaking in a minor update, followed by the breaking changes in a major update. This would provide producers with the ability to adopt backwards compatible new features without having to make the breaking changes that are part of the major release.

Even without the usage for shorter release cycles or multiple releases at the end of a cycle, defining versioning rules will be helpful and is an important part of a mature specification.

Issue name: Add Road informations to the EndLocation Data Frame

Summary

I propose to add road informations such as RoadName, Number and Direction to the EndLocation Data Frame.

Motivation

Because a common workzone could begin on a highway and ending on another road or highway, I think that this informations should be important to provide as well.
It is not clear that all the workzone is on the same road all along.

Summary
For optional data elements such as workersPresent, reducedSpdPosted, or the enumerated field roadRestrictions, what is expected if no data is available?
I have seen that some data producers are utilizing the text 'N/A' when there is no data for a optional data element, while others are simply leaving the data element blank, and others are omitting the enumerated element if unavailable.

Motivation
I am currently undergoing the process of creating the specification plan for Oregon DOT's WZDx feed and want to ensure that it closely models and complies with other data producer's feeds for easy plug-in-play use by data consumers.

Desired Result
Direction on what is the standard for these situations where data is unavailable would be appreciated. If the decision is to use the text 'N/A', or leave the element blank, or omit the element, then this should be denoted in the documentation so that data producers follow the same behavior.

Rename release_notes.md to RELEASES.md

The release_notes.md file in the project root describes the current and past spec versions. In many repositories on GitHub this file is named RELEASES.md. This is not an official standard but the all-caps separates the file from data/spec files and groups it with other metadata files such as READMEs, LICENSEs, CONTRIBUTING, etc.

See here for a bit of background information on the all-caps naming convention.

Issue name: “Change wz_location_method to location_method”

Summary

If the field road_events.type is added via issue #82 the field name wz_location_method should be changed to reflect the models accommodation of multiple road event types.

Proposed changes

In the case of a proposed change, provide one or a few options for moving forward.
Replace wz_location_method with location_method

data SLAs (e.g., frequency of updates, coverage, etc): hasn't been explicitly discussed, so we'd love to discuss this too. this directly impacts our decision whether to actively support/maintain an ingestion pipeline for this data

In the current version, a feed issuer can submit more than one work type. So one work type may designate an architecture change to a work type, while the other may not. This may be true, but there will be confusion. Also, is maintenance ever an architectural change? by definition, it is just fixing or preserving existing infrastructure. This may require guidance and best practices discussion.

We would prefer we have a single lat/lon field with an optional parameter to specify true if the location has been verified. Otherwise we have to check both and have no guarantee of which one is more up-to-date. I could easily see the estimated field being updated and forgetting to update the verified field as well.

Currently, none of the fields on lane_restriction entity that are present in the output data feed are required. That means it's possible for the lane_restrictions field on the lane object to contain an array of empty objects, that is

{
  "lanes": [
    {
      "lane_restrictions: [{},{}],
    }
  ]
}

Requiring restriction type on the lane_restriction entity would solve this issue and is a simple fix. I don't see a downside to having this required as a lane restriction is useless without the type.

Consider including licensing information in the metadata. Clearly define how the data can be used by consumers. Is it open? Does it require attribution? Can it be used for commercial purposes?

In order for robots to reason about an obstruction best, it should know the heading and directionality of the blockage.

road direction specification"roadDirection" is not always going to be clear. There are roads that canonically go N-S but have jogs in them of E-W. Relying on direction could be inconsistent, especially if entered manually. I think it would be ideal if we could get a heading angle instead (North = 0deg) that aligned with the direction of traffic being affected. That would ensure that we could us the lat/lon and road name to validate the location and direction directly.

Within Iowa we had a few discussions on how to handle recurrent events. Below are some of our notes on how we handled these events.

-Since each lane closure is handled individually then recurrent closures must be separate events in the specification. Since we can have recurrent work zones that last for multiple months, we decided to show only the events for the next 14 days. This helped reduce the total number of events.

-We would only show future or current lane closure events and disregard any completed events (most common in the recurrent event types)

This issue replaces/continues the discussion from #35. Please see the discussion there for background.

From the original discussion:

I'm part of a team working with MassDOT, and we believe town (as the general term; also encompasses city) would be beneficial information about a work zone to include in our data feed.

The road event entity includes location information such as the road name, road number, begin/end cross streets & mileposts, and actual coordinates. An optional human-readable "town" (name tbd) field would provide the same human-readable benefits as these location fields.

In #35, jurisdiction seemed to be the most general term for town/city but this should be discussed here. This optional field would be added to the road_event entity and would allow for providing this information if a producer desires.

Allow Multiple multiple feeds/road_event_feed_infos per GeoJSON file

This issue is intended to recap several comments made throughout the specification development in regards to the the feed output.

Background

Currently, a WZDx compliant feed outputs a single GeoJSON file, which allows for a single road_event_feed_info that applies to all road events in the file/feed. Several contributors expressed the option of allowing multiple feed infos per GeoJSON file.

A simple way to implement this is to change the road_event_feed_info property on the feed's root object to road_event_feed_infos, an array of road_event_feed_info. A feed_info_id property (matching the data-table field of the same name) would be added to both the road_event_feed_info objects in the road_event_feed_infos array and the properties of each element (road event) in the features array to relate road events to their respective feed information/metadata. This has the benefit of allowing road events with different versions, different producers, different update timestamps...etc to be included in a single WZDx compliant feed.

Issues/Confusion with the Proposed Approach

In the majority of cases, however, the output of a WZDX feed would contain just one road_event_feed_info. Thus, an array this would often be unnecessarily and could introduce confusion for implementers and users, as well as introducing unneeded ID fields.

Additionally, if there are multiple feed info objects per "feed", as proposed above, then the name object (and data table) name road_event_feed_info isn't correct since it's not describing a whole feed, but rather a set of road events within the feed. If the whole file is the "feed" there could only be one road_event_feed_info.

What is a "feed"?

This discussion makes it apparent that what a "feed" is should be clarified. Previous spec versions and discussions, as well as my intuition, have described "a feed" (or the output of a feed) as a single file containing information and geometry regarding one or more road events that are described by a single road event feed information object--the feed info describes the entire feed.

I see the benefit in allowing for multiple feeds (using the above definition) per file, though I don't believe making the road_event_feed_info property on the GeoJSON output an array would be the clearest/best way to do it.

It is unclear if the intention of the specification is to limit a unique 'feed' (URL) to a single work zone project with 1 or more work zone activities (as defined by the XSD), or, whether it is acceptable for a single feed to support multiple projects, each with their own header and metadata assignment.

Issue name: Redesign the startDateTime and EndDateTime Data Frames to facilitate translating the WZDx specification into the geoJson specification.

Summary

The startDateTime and endDateTime Data Frames in Version 1.0 of WZDx specification are difficult to translate into the geoJson specification because the fields are not normalized. Specifically, startDateTime-est, startDateTime-ver, startDateTime-cancelled, endDateTime-est, endDateTime-ver, and endDateTime-cancelled, all contain data elements in the field name. To normalize the data, and thus ease the translation from WZDx to geoJson, I suggest the changes below.

Motivation

Work Zone Data is inherently spatial and temporal. By facilitating the use of the geoJson format publishers and consumers can leverage Geographic Information Systems and spatially enabled applications to quickly and easily visualize WZD information.

Normalizing the data simplifies the specification: By replacing the startDatetime-ver, startDateTime-est, startDateTime-cancelled, endDatetime-ver, endDateTime-est, endDateTime-cancelled fields with the startDateTime, endDateTime, startDateTimeAccuracy, and endDateTimeAccuracy fields we reduce the needed fields from 6 to 4.

Normalizing the data eases data retrieval: Custom computer code won’t have to be written to extract the date/time accuracy assessments from 6 different field names. Also, it makes the data easily retrieved from the common core table instead having to write code to parse it from a separate data frame.

Proposed changes

1. Abolish the StartDateTime to and EndDateTime Data Frames
2. Include StartDateTime and EndDateTime fields as data elements in the Common Core Table
3. Create startDateTimeAccurracy and endDateTimeAccurracy fields as data elements in Common Core
4. Include the values "Estimated" and "Verified" to describe StartDateTimeAccuracy and endDateTimeAccurracy.
5. Exclude the value “Canceled” from the Date/Time Accuracy enumeration because it indicates the status of a Work Zone and not a measure of how accurate the date/time value is.

A standard that enables Linear Referencing can help robots understand more about the nature of the blockage and be able to ingest it more intelligently and infer the heading of the obstruction.

We agree that there should be a single data format. We believe there are decent ones to start (LR, CIFs), and we will leave it to the data producers to decide on an MVP.

Waze has "CIFS", which is what Seattle's feed is based off of:
https://developers.google.com/waze/data-feed/road-closure-information

Linear Referencing is a general technique, for which the are competing implementations as well:

(TomTom) https://www.openlr-association.com/

and

(OSM) https://www.mapzen.com/blog/osmlr-2nd-technical-preview/

But we'd be happy to participate in discussions that decide on this standard, since we recognize each consumer's requirements may differ. Granularity of the data (e.g., lane-level vs road-level) falls into this category.

Having a conditional crossStreet value seems odd unless they are assuming it is going to power some in-car Nav that says "construction at Main St. and 3rd Ave". We wouldn't rely on this value and instead would use our own map information to fill in this detail for rider prompts.

As mentioned during the meeting held on Monday, August 5th, MassDOT is working of web-based software interface tool to grab work zone data from our Real-Time Smart Work Zone systems and want to be consistent with the WZDx specification. In a review of the WZDx v1 specification we identified some metrics and device management data elements that we are looking to utilize but have not been incorporated as of yet. We were hoping that some of these might be considered by FHWA to be part of their WZDx v2 specification or some future version, as this effects our software development schedule. We are submitting the attached file that provides a breakdown of these items and we are working on more formal specifications for each item that will be submitted in the Pull Requests tab. MassDOT requested consideration for spec update_07-30-19.pdf

Change Time/Spatial Enumerated Type enumerations to be lowercase, for consistency

Currently, all WZDx enumerated types are all lowercase, dash delineated, except for Geometry Type (which is fine as it is defined by the GeoJSON standard) and time/spatial verification. I don't believe there is a reason that the time/spatial verification enumerated types should be capitalized, so this is unnecessarily inconsistent with the other enumerated types.

Although the GPS system's use of EPSG:4326/WGS84 has made it a more-or-less standard choice, there are numerous American authorities that still use NAD83 or even more region-specific datums. This should be specified to avoid ambiguity or imprecisely submitted coordinates. (context)

Issue name: “[Clarification/Question — Work Zone Events Description/Clarification”

Summary

Their currently is no exact definition of what a work zone event is in the specification which leave this open to interpretation. After discussing with some other I thought I would put my interpretation and get feedback from others.

The work zone event isn't a single record for the entire work zone but can be separated into different components based on changes in the roadway or work zone configuration. So multiple road_event_id can make up a single work zone. For example, if a work zone starts with one lanes closed then a couple miles down the road changes to two lanes closed, we would represent that as two separate road events since the number of closed lanes change. Another example could be when one lane is closed then a lane is added because of a ramp, since the total number of lanes have changed we would separate that as two separate road events. It may not be the proper application but in both situations we plan on using the subidentier as the link to relate these projects together. This may also be very applicable to intersections where each approach has an event.

This does not impact situations such as a double lane closure https://mutcd.fhwa.dot.gov/htm/2009/part6/fig6h_37_longdesc.htm. In these lane closures we would still only include one work zone event since the portion with only a single lane closed is part of the taper and not intended to be for a long distance.

Feedback/ Potential changes

I'm not sure if this is something we include in the specification or should be included as part of the best practices/guidance subcommittee. At this point I was just looking providing my perspective for other agencies to consider and looking for feedback on whether this could be better accomplished.

From talking with others this may potentially resolve some of the other issues in lane number and references.

Some other things to consider:

• Is using the subidentifier appropriate to relate work zones or should a different field be added?
• Right now we are just considering lanes for breaking work zone events. I don't think we need to break at every attribute in the WZDx but are their higher level attributes where work zone events should break at? Some of the ones discussed are total number of lanes, number of lanes open/closed, intersections, and road name.

Looking forward to further input

Issue name: Local Access Only
Need to communicate that local access only is allowed on certain roadways.
In some cases a roadway is closed to through traffic but is open for local access to businesses or residents.

Motivation
The current spec only allows for full closure of a roadway with specific restrictions such as no trucks, no parking, weight restrictions, etc, which can be applied to the entire road event or just specific lanes. The spec also allow for noting the vehicular impacts such as all lanes closed, some lanes closed.

Proposed changes
To add a new enumerated type to the Road Restrictions values = Local Access Only

Consideration needs to be given to how such a value would interact with Vehicle Impact and Lane Status values to ensure clarity. This may happen through business rules. For example, would producers use Lane Status = closed and a Local Access Only restriction or would the not Lane Status = open with a Local Access Only restriction.

Consider using the geoJson standard to specify how the WZD spec will incorporate and model spatial data. Doing so will enable the use of points, lines, and polygons which could represent streets, WZ Areas, Road Furniture, and more.
https://tools.ietf.org/html/rfc7946

Issue name: “[Clarification / New feature / Question] — Summarize topic”

Summary

Based on the discussion during v2 development, I thought that the type_name in the types_of_work table was going to be optional.

Looking back at the original pull request before it was modified for the relational data model the comments refer to this being optional as well.

In Iowa I don't think we currently have the ability to provide the level of detail without making a lot of assumptions.

Proposed changes

Change type_name to optional

Simplify the Lane Type enumeration

Background

Currently, the Lane Type Enumerated Type allows values that don't make sense given the context it is used. This type is used by the lane_type field on the lane table--each entry in the table represents a single lane. Many of the allowed types are plural and leftover from WZDx v1 when this enumeration was used on the activity/road event level. Examples: middle-two-lanes, left-3-lanes, etc.

Quick Solution

A quick solution would be to disallow the values that no longer apply. This should have been done for the v2 release but was likely not caught in review.

Simplifying the Lane Type enumeration

While the quick solution solves the biggest issue with the current enumeration, this is a good opportunity to think about what type of lane information we want to get from the lane_type field and thus simplify the enumerations of the Lane Type Enumerated Type.

If we just disallowed the plural/non-applicable values, we'd still have several enumerations which are redundant given information from other fields on the lane object.

An example of a redundant lane type is middle-lane. This value indicates if a lane is the "center most lane where are a total of an odd number of lanes". Since a lane also a lane_number and the road event has total_num_lanes, you could already determine if the lane was in the center.

Thelane_number isn't required, but if a producer could provide the lane_type as middle_lane, they could also give the lane_number for the lane.

Conclusion

An update needs to be made to the Lane Type Enumerated Type and I'm hoping this issue thread can start the discussion on what route we should take to do that, as there is potential to simplify the enumeration as part of the change.

Including lane_edge_reference on every lane in a road event is confusing

Background

The lane_edge_reference property defines the start side (either left or right) for identifying the lanes within a road event by lane_number index. For example, if the lane_edge_reference is left, the lane_number 0 refers to the leftmost lane.

Issue

Including the lane_edge_reference is a simple and effective technique for clarifying the often confusing indexing of lanes. lane_edge_reference only needs to be defined once for each road event, rather than for every lane in the road event as is currently done. Defining it for every lane:

• Is confusing, as you could use right for some and left for others within the same road event
• Requires more code to parse the feed, as you must check the field for every lane
• Adds unneeded fields and leads to larger files

Currently (possible scenario)

{
  "road_event": {
    "total_num_lanes": 2,
    "lanes": [
      { 
        "lane_edge_reference": "left",
        "lane_number": 0
      },
      {
        "lane_edge_reference": "right",
        "lane_number": 0
     }
    ]
  }
}

Note the above is pseudocode

Solution

Moving the lane_edge_reference as a conditional field (required if using "lanes") in the road_events table would be a simple solution.

Example

{
  "road_event": {
    "total_num_lanes": 2,
    "lane_edge_reference": "left",
    "lanes": [
      { 
        "lane_number": 0
      },
      {
        "lane_number": 1
     }
    ]
  }
}

Note the above is pseudocode

data types: although the focus of the workshop was WorkZone data, a few one-off discussions between producers and consumers described other types of data that might be worthwhile, such as bike zone, sidewalks, etc. These are also important to SDV companies in general.

Consider allowing the metadata to be embedded within the header as an alternative to providing the file location URL. The amount of metadata is small enough that it can be conveniently included, eliminating the need make a separate request for the data.

Change the lanes table lane_number field to lane_index; clarify/standardize first value

Background and Issue

Currently, each lane's location is identified by an index, the lane_number. It is not specified what the first index should be (that is 0, 1, or 5 even--there's nothing stopping you!). One could also build the following lanes for a two-lane road and they wouldn't be violating the specification.

{
  "road_event": {
    "lanes": [
      {
        "lane_number": 15
      },
      {
        "lane_number": 3
      }
    ]
  }
}

note the above is pseudocode

Solution

Since the number is an index, the field name lane_index would be more clear. It should be clarified in the field description what the first/start lane index is, either 0 (I'm for this because indexes usually start at 0) or 1.

Rename feed-content directory name to spec-content

The feed-content directory contains all information about the content of the specification, not just the feed (which is created using the spec). While feed-content is not incorrect, spec-content is more accurate.

This proposal is part of an ongoing effort to organize the GitHub repository. This naming change would require updating hyperlinks in several markdown files but doesn't change anything in the specification or output feed. Thus the change does not necessitate a bump in spec version.

New feature — Adding elevation data to all reported positions.

Changing all positional data from 2D to 3D.

The current specification assumes a flat world with no stacking of road elements. The real world has many instances of multiple items being stacked. For example, the High 5 interchange in Dallas Texas has 5 levels of roads stacked on-top of each other. Elevation data is needed to be able to correctly distinguish these different levels of roads.

Additional use cases would involve:

1. Steep inclines for temporary bypasses. These steep inclines cannot be correctly annotated and conveyed to vehicles without elevation data.
2. Work on ramps where the beginning and ending work at at significantly different elevations.
3. Work on inclined and declined (hilly/mountainous) roads.
4. Tunnel work
5. Overpass/Underpass work
6. Stacked road work.

In the road_events table description it refers to types_of_work as a separate table that has a foreign key reference of road_event_id to the road_events table. I noticed the same thing with the lanes table description. However, when you look at the examples lanes and types_of_work are actually nested elements of the road_events element, not some separate element that refers to road_events by a foreign key. In fact, road_event_id does not appear in either of the lanes or types_of_work elements themselves. See below for an example. If the examples are the correct way for the feed to look, then I think you could just add lanes and types_of_work to the road_events table description as type lanes and types_of_work respectively.

{ "type": "Feature", "properties": { "road_event_id": "67890", "subidentifier": "State_Project_002", "road_name": "Barrett Street", "road_number": "I-200", "direction": "west bound", "beginning_cross_street": "King St", "ending_cross_street": "Hampton Garden Dr", "beginning_milepost": 120.10, "ending_milepost": 121.50, "beginning_accuracy": "estimated", "ending_accuracy": "estimated", "start_date": "2010-01-01T01:03:01Z", "end_date": "2010-01-02T01:07:01Z", "start_date_accuracy": "verified", "end_date_accuracy": "verified", "event_status": "completed", "total_num_lanes": 2, "vehicle_impact": "all-lanes-open", "workers_present": true, "reduced_speed_limit": 30, "restrictions": [], "description": "Dummy work zone", "issuing_organization": "Testco", "creation_date": "2010-01-01T01:01:01Z", "update_date": "2010-01-01T01:01:01Z", "types_of_work": [ { "type_name": "roadside-work", "is_architectual_change": false } ], "lanes": [ { "lane_edge_reference": "left", "lane_number": 1, "lane_status": "open", "lane_type": "left-lane", "lane_restrictions": [ { "restriction_type": "no-trucks" } ] }, { "lane_edge_reference": "left", "lane_number": 2, "lane_status": "open", "lane_type": "right-lane" } ] }, "geometry": { "type": "LineString", "coordinates": [ [ -72.63547003269196, 42.333474551052404 ], [ -72.63563096523285, 42.333450757565444 ], [ -72.63599574565887, 42.333446791983405 ], [ -72.63645708560944, 42.33349041337203 ], [ -72.63735830783844, 42.33354593145921 ], [ -72.63793766498564, 42.33359748392484 ], [ -72.63901591300964, 42.33368472646276 ], [ -72.63960599899292, 42.33373627881463 ], [ -72.64037847518921, 42.3337997278051 ] ] } }

Based on WZDx Workshop participants, construction workers can benefit from data that puts them “on the map,” making them visible in work zones, which can be high-risk environments. In addition, participants noted that these workers can provide real-time, on-the-ground information to make work zone data more complete and useful as a tool for improving safety. Incorporating this information about work zones into navigation apps and consumer maps can alert drivers to reduce speed and signal to AVs to transfer control to a human driver ahead of time.

Solution: Make WorkersPresent data field changed from "Optional" to "Required" in the next version of the specification

Issue name: Best Practices for Road Number

Road number requires a designator for county, state or interstate. Yet there are no rules for its value. Either there should be a business rule for interstate, each state and county or a standardized list for every numbered road in the US.

There are inconsistencies between the full specification identifying fields as optional and the XSD file identifying values for min and max occurrences. All optional fields should have minOccurrences set to "0" in the XSD.

Also, there is inconsistency in the full spec as to whether roadRestrictions is required. It is defined as optional, but the description states "one or more", which implies it is required.

Standardize Lat/Long (3857 vs wgs-84). We prefer to use WGS-84, as this is the common standard for this kind of information.

In Iowa we are trying to map our standard closure types to the lane enumerations for both the open and closed lanes. We are not exactly sure when and how to use the exit ramp laneType enumerations from Table 7 in the specification (left-exit-ramp, right-exit-ramp, right-second-exit-ramp, etc). Without a definition it is hard to determine if these should only be used when the roadway is a ramp or is this to be used for dedicated exit lanes (not treat them as through lanes). Some more definitions, descriptions, or examples of these would be beneficial.

Issue name: “Redesign the BeginLocation and EndLocation Data Frames to facilitate translating the WZDx specification into the geoJson specification.”

Work Zone Examples:
https://gist.github.com/DeraldDudley/ae492b090fdddca6574e72f804d9a2f5

Begin & End Location Examples: https://gist.github.com/DeraldDudley/d1155539e31467e5725eb9f6f7f0b3cf

Maricopa County WZD as a geoJson feed:
https://maps.bts.dot.gov/.well-known/wzd/maricopa_county_wzd.geojson

Maricopa County WZD feed Mapped as a geoJson Feature Collection:
https://gist.github.com/DeraldDudley/1c686933be7fbb99b96d7205f5ff79d9

Summary

The BeginLocation and EndLocation Data Frames in Version 1.0 of WZDx specification are difficult to translate into the geoJson specification because the fields are not normalized. Specifically, latitude-est, latitude-ver, longitude-ver, milepost-est, milepost-ver all contain data elements in the field name. To normalize the data, and thus ease the translation from WZDx to geoJson, I suggest the changes below.

Motivation

Work Zone Data is inherently spatial and temporal. By facilitating the use of the geoJson format publishers and consumers can leverage Geographic Information Systems and spatially enabled applications to quickly and easily visualize WZD information.

Proposed changes

Work Zone Feature

• Convert the Common Core Table to a spatial feature called WorkZone by adding a geometryType field and a geometry field.
• The geometryType field holds the kind of geometry being used to represent the work zone and is optional. Geometry types are enumerated in the geoJson specification.
• The geometry field holds the coordinates, or an array of coordinates, used to spatially define the work zone. This field is required if geometryType is not null.
• Add a demarcationMethod field in the common core table.
• demarcationMethod is required if the geometryType field is not null and represented as an Enumeration with the values of Verified or Estimated.
• Add a wzFeatureType field to the common core table
• wzFeatureTypes is required and represented as an Enumeration with the values of Work Zone, BeginLocation/Entry Point, and EndLocation/Exit Point. Work Zone feature types may be added to the specification as needed.

Work Zone Feature

• Provide TMDD Example
• Provide XML Example
• geoJson Example: https://gist.github.com/DeraldDudley/ae492b090fdddca6574e72f804d9a2f5

BeginLocation Feature

• Consider changing the feature name from BeginLocaton to wzEntryPoint because the BeginLocation descriptor maybe become ambiguous as the specification adds more spatial features.
• Extract the BeginLocation Data Frame from the common core to a spatial feature by adding a geometryType field and a geometry field.
• The geometryType field holds the kind of geometry being used to represent the BeginingLocation and is optional. Geometry types are enumerated in the geoJson specification.
• The geometry field holds coordinates, or an array of coordinates, used to spatially define the BeginLocation. This field is required if geometryType is not null.
• Add a demarcationMethod field in the common core table.
• demarcationMethod is required if the geometryType field is not null and represented as an Enumeration with the values of Verified or Estimated.
• Add a wzFeatureType field to the common core table
• wzFeatureTypes is required and represented as an Enumeration with the values of Work Zone, BeginLocation/Entry Point, and EndLocation/Exit Point. Work Zone feature types may be added to the specification as needed.
• Add an identifier field
• The identifier field serves as a foreign key and relates the BeginLocation feature to the WorkZone feature.
• Normalize the Milepost field by splitting it into two parts.
• The milepost field holds the milepost value.
• The mpDemarcationMethod field indicates how the milepost value was defined.

BeginLocation Feature

• Provide TMDD Example
• Provide XML Example
• geoJson Example: https://gist.github.com/DeraldDudley/d1155539e31467e5725eb9f6f7f0b3cf

EndLocation Feature

• Consider changing the feature name from EndLocaton to wzExitPoint because the EndLocation descriptor maybe become ambiguous as the specification adds more spatial features.
• Extract the EndLocation Data Frame from the common core to a spatial feature by adding a geometryType field and a geometry field.
• The geometryType field holds the kind of geometry being used to represent the EndLocation and is optional. Geometry types are enumerated in the geoJson specification.
• The geometry field holds coordinates, or an array of coordinates, used to spatially define the EndLocation. This field is required if geometryType is not null.
• Add a demarcationMethod field in the common core table.
• demarcationMethod is required if the geometryType field is not null and represented as an Enumeration with the values of Verified or Estimated.
• Add a wzFeatureType field to the common core table
• wzFeatureTypes is required and represented as an Enumeration with the values of Work Zone, BeginLocation/Entry Point, and EndLocation/Exit Point. Work Zone feature types may be added to the specification as needed.
• Add an identifier field
• The identifier field serves as a foreign key and relates the EndLocation feature to the WorkZone feature.
• Normalize the Milepost field by splitting it into two parts.
• The milepost field holds the milepost value.
• The mpDemarcationMethod field indicates how the milepost value was defined.

End Location Feature

• Provide TMDD Example
• Provide XML Example
• geoJson Example: https://gist.github.com/DeraldDudley/d1155539e31467e5725eb9f6f7f0b3cf

Clarify optional field representation in GeoJSON feed ouput - create a JSON Schema

Background

Currently, some WZDx fields are optional. The intention of an optional field is to allow pieces of information that:

• May not apply to a certain road event (e.g. milepost); or
• Are unable to be provided by a significant amount of data producers (e.g. worker presence)

to be included when relevant or if available.

However, the spec doesn't clarify how an optional piece of data that is intended to have no value should be represented in the GeoJSON feed output.

Representing a value-less optional field in the feed output

There are two (reasonable) ways to accomplish this:

1. The JSON property for an optional piece of data (e.g. beginning_milepost) is still required to be present in the GeoJSON feed output but its value should be null if it is inapplicable/unable to be filled out.
2. The JSON property for an optional piece of data without a value should not be present in the GeoJSON feed output.

Implementing the clarification

The chosen representation from the previous section could be clarified with an additional paragraph of text in the create-feed README, however, a better approach would be to describe the representation by creating a schema for the GeoJSON feed output. A JSON schema leaves nothing up to interpretation by the reader and has the additional benefit of allowing feed producers to validate their feed output. I believe this benefit makes it worth the additional time to create over just adding a block of explanatory text.

The current specification has restrictions but does not provide any value limits to the restrictions. This is critical information for oversize/overweight trucks and Iowa modified the specification slightly so that these values could be present in the feed. We used the same restriction enumerations but provided an additional field for the restriction value (see screenshot example below). In addition, it does not currently appear that multiple restriction enumeration types can be handled in the specification. The modification we made would allow for multiple restriction types which is common.

For the openLanes and closedLanes fields, how can multiple lane type enumerations be used? For example on a three lane roadway, if we have a center lane closed that would leave the left lane and right lanes open. Based on the enumerations the closedLanes=middle-lane and the openLanes =left-lane and right-lane. The specification currently does not allow for the ability to have multiple lane type enumerations.

The specification needs a way to communicate mobility impact at a work zone record level when lane level impacts are not available.

Summary
The current spec codes mobility impacts using the required element of lanes closed. This element has allowed values of all or none but requires data creators to produce lane specific data to enumerate partial closures.

Motivation
Many infrastructure owner and operators (IOOs) are unable to produce lane specific data about closures so requiring this is a barrier to adoption. Such IOOs are likely to be able to describe a mobility impact for the entire work zone record.

Proposed changes
There are a two options that should be discussed that can solve this issue

1. Add a new enumerated element named Mobility Impact to the Common Core Data
   • Values for this element would be: Impacted, Closed, None
2. Remove the closedLanes and openLanes elements and replace them with a new data frame named Mobility Impact
   • a new element named General Mobility Impact would be conditionally required unless one or more enumerated lane types are listed. It would have values of: Impacted, Closed, None
   • all the enumerated values for openLanes/closedLanes would become optional (or conditional) elements under this data frame
   • for each lane type used there would be the one of the following values: Open, Impacted, Closed, Shift Right, Shift Left

Option 2 has the benefit of solving the issues raised in #issue #5 and #issue #4 since multiple lanes could be listed within the Mobility Impact data frame, each with their own specific impact value.

I prefer option 2 since it allows for greater specificity and the impacts to individual lanes to be enumerated clearly. It also creates the framework to add more specificity to the impacts at a lane level such as width, heigth, or weight. I does present backwards compatibility issues though doesn't require any new data from current producers just a reformatting of their feeds.

Replace the subidentifier field with a Relationship object

The specification currently uses the road_events.subidentifier field as a foreign key to relate objects. However, the field does not explicitly describe how linked features are related. Replacing road_events.subidentifier with a Relation object, like the one used in JSCalendar, will relate road event features and explicitly describe how features are related.

The Relationship object as defined in the JSCalendar Specification.

A Relation object defines the relation to other objects, using a possibly empty set of relation types. The object that defines this relation is the linking object, while the other object is the linked object.

The Relation object has the following properties:

• @type: "String" (mandatory)

Specifies the type of this object. This MUST be "Relation".

• relation: "String[Boolean]" (optional, default: empty Object)

Describes how the linked object is related to the linking object. The relation is defined as a set of relation types. If empty, the relationship between the two objects is unspecified. Keys in the set MUST be one of the following values, or specified in the property definition where the Relation object is used, or a value registered in the IANA JSCalendar Enum Registry, or a vendor-specific value:

• "first": The linked object is the first in a series the linking object is part of.
• "next": The linked object is the next in a series the linking object is part of.
• "child": The linked object is a subpart of the linking object.
• "parent": The linking object is a subpart of the linked object.

The value for each key in the set MUST be true.

The Relationship object used in the Work Zone Data Specification.

Hierarchical Example

• In the example below, the first road event feature ("road_event_id": "1") is the parent of the second, third, and fourth features ("road_event_id": "2", "road_event_id": "3", "road_event_id": "4")
• Note the relationship in the first feature ("road_event_id": "1") can be left blank. The children can point to the parent with the same effect.

{
  "road_event_feed_info": {},
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "road_event_id": "1",
        "relatioship": [{"child":"2"},{"child":"3"},{"child":"4"}]
      },
      "geometry": {
        "type": "LineString",
        "coordinates": []
      }
    },
    {
      "type": "Feature",
      "properties": {
        "road_event_id": "2",
        "relatioship": {"parent":"1"}
      },
        "geometry": {
          "type": "LineString",
          "coordinates": []
      }
    },
    {
      "type": "Feature",
      "properties": {
        "road_event_id": "3",
        "relatioship": {"parent":"1"}
      },
      "geometry": {
        "type": "LineString",
        "coordinates": []
      }
    },
    {
      "type": "Feature",
      "properties": {
        "road_event_id": "4",
        "relatioship": {"parent":"1"}
      },
      "geometry": {
        "type": "LineString",
        "coordinates": []
      }
    }
  ]
}

Sequential Example

• The example below shows how to relate and order road event features.
• The first road event feature ("road_event_id": "1") begins the sequence and identifies the second feature ("road_event_id": "2") as next in the sequence.
• The second feature identifies the first feature ("road_event_id": "1") as the beginning of the sequence and the third feature ("road_event_id": "3") as next in the sequence.
• The third feature identifies the first feature ("road_event_id": "1") as the beginning of the sequence and the fourth feature ("road_event_id": "4") as next in the sequence.
• The fourth feature identifies the first feature ("road_event_id": "1") as the beginning of the sequence.

{
  "road_event_feed_info": {},
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "road_event_id": "1",
        "relatioship": {"first":"1","next":"2"}
      },
      "geometry": {
        "type": "LineString",
        "coordinates": []
      }
    },
    {
      "type": "Feature",
      "properties": {
        "road_event_id": "2",
        "relatioship":  {"first":"1","next":"3"}
      },
        "geometry": {
          "type": "LineString",
          "coordinates": []
      }
    },
    {
      "type": "Feature",
      "properties": {
        "road_event_id": "3",
        "relatioship":  {"first":"1","next":"4"}
      },
      "geometry": {
        "type": "LineString",
        "coordinates": []
      }
    },
    {
      "type": "Feature",
      "properties": {
        "road_event_id": "4",
        "relatioship":  {"first":"1"}
      },
      "geometry": {
        "type": "LineString",
        "coordinates": []
      }
    }
  ]
}

If a single construction project affects both directions on a highway, would we get two entries for the two directions are one single entry?

As this data starts to become a standard across many states, there are a few items that could make it more usable to Autonomous vehicles. The missing pieces of data are about what type of construction is occurring. A simple boolean field that would denote if the road is architecturally changing would be very helpful to know in this era of LiDAR scanning roads. Once this exists, the next level of fidelity would be something like 10 pre-defined typical construction projects. i.e. 1= restriping, 2 = repaving with restriping, 3 = lane addition (and there could be the lane attribute added here for which lane is being added), 4 = new intersection, etc. This would pave the way for a clearing house server for all US construction and would simplify the HD mapping communities workload!