Refactor the Relationship object: explicitly define and identify entities related to a road event

[j-d-b]

Background

The Relationship object (see #108 and #118 for the discussion on why it was added) is intended to be used to specify relationships between road events and other entities which facilitates grouping road events. The Relationship object appears on the RoadEvent as the value of the relationship property.

For usage examples, the Relationship object can be used to:

• Indicate that multiple road events are part of the same project
• Indicate that a road event is part of the same phase of the work zone
• Show that one road event occurs physically before or after another in a sequence
• Show that a detour road event is associated with a specific work zone road event
• Indicate that a road event is one occurrence of work in a recurring work zone

Instead of defining all the use cases, the implementation of the Relationship object was very general, allowing the broadly defined parents/children and first/next relationships as a list of strings. I believe this is too general so it is difficult to use effectively.

For first/next, the description indicates the value of the strings must correspond to a road event ID within the same WZDx feed. Thus it is clear what the strings in the first/next properties refer to, though you have to read into the description to know this and examples to see how to use them "properly".

For parents/children, the value of the string can be anything. Thus there is no way for a consumer to know how to use the value. For example say one road event lists children as ["1412", "2233"]—there is no context to have any idea what this means. Maybe they are detours, the consumer could iterate through all detour road events and see if it matches, but what if it doesn't? That mean's they're some non-WZDx construct and without specific documentation from the producer it's impossible to use.

One way around this is the producer could have the string include what it is description, e.g. "project: 12312", but this is still producer-specific and not able to be processed effectively without coding rules for each producer based on documentation they provide, which defeats the purpose of a standard.

Thus, I think the Relationship object needs to be refactored to explicitly define relationships.

Proposed refactoring

At a high level, the proposed changes achieve the following:

• Allow representing, per road event, a list of relationships between the road event and an explicitly defined and identified entity.

And that is accomplished through two changes (and all the sub-objects/types that come along with it):

1. Deprecate the relationship property on the RoadEvent
2. Add new related_entities property to the RoadEvent

This property name is more semantic because relationship is actually describing many relationships, and all the relationships are between the road event it occurs on and "other entities".

related_entities property on the RoadEvent object (replaces relationship)

Property Name	Value	Description	Conformance	Notes
related_entities	Array; [RelatedEntity object] (see below)	A list describing one or more entities which are related to this road event, such as a work zone project it is part of or another road event that occurs before or after it in sequence.	Optional

RelatedEntity Object

The RelatedEntity object is used to identify an entity that is related to a road event. The types of entities supported are detailed in the RelatedEntityType enumerated type (see below).

For example, a RelatedEntity can be used to show multiple road events are part of the same work zone project, relate a detour road event to the work zone road event the detour applies to, or identify a sequence of road events that make up a larger work zone.

Property Name	Value	Description	Conformance	Notes
type	RelatedEntityType enumerated type (see below)	The type of entity being identifed, such as a parent work zone project or next road event in sequence.	Required
entity_identifier	String	An identifier for the entity described by the type property.	Required
is_wzdx_feature_id	Boolean	A yes/no value indicating if the entity_identifier corresponds to the id property of a feature in the same WZDx feed.	Required

Used By

Property	Object
related_entities	RoadEvent

RelatedEntityType Enumerated Type

Describes a type of entity, such as a work zone project, work zone phase, or detour-type road event. The entity type does not need to correspond to an entity defined within a WZDx feed.

Value	Description
work-zone-project	A work zone project that one or more road events are part of.
work-zone-phase	A phase of a work zone that one or more road events are part of.
recurrent-work-zone	A recurring work zone that one or more road events are representations of an occurrence of work of.
first-road-event	The first road event in a sequence of road events that together describe a full work zone.
next-road-event	The next (subsequent) road event in a sequence of road events that together describe a full work zone.
detour-road-event	A road event describing a detour for a work-zone-type road event.

Used By

Property	Object
type	RelatedEntity

Next steps

• Discuss the is_wzdx_feature_id; this could be removed and instead certain RelatedEntityType's indicate (business rule) that the entity_identifier is a WZDx feature's id.
• How do we describe a RelatedEntityType to related a detour-type road event to the work zone it applies to (we have the other way via the detour-road-event)?
• Are there any other RelatedEntityTypes we want to support?
• Does anyone object to losing the flexibility allowed by the generic "parents" and "children" in the current specification?

[devorah-ql]

The current Road Event object and the associated parent-child relationships appear fairly complex in the original specification, and it is not completely clear how exactly they will be implemented. It would be helpful to clarify these objects and relationships in upcoming WZDX meetings. Hopefully they can be specified in a simple way, so they are practical for vendors to implement.

From a vendor perspective, it is reasonable to track the roadway and direction for any piece of equipment, as well as its specific location. So, if the intention of the roadway event object is simply to list a roadway, and direction, that seems quite reasonable. However, the specification says that "A change in the lane configuration or roadway should result in creating a new road event, separating the work zone into multiple road events." If this is the case, it appears to create a great deal of complexity, and also confusion about who will own and be responsible for maintaining this data.

Some things that appear is if they could add undue complexity:

1. If the same roadway segment is split into multiple events due to different lane configurations in different parts of the road, and then different pieces of equipment must be associated with each segment, this seems like a formula for confusion and unnecessary complexity. A realistic application would simply be a parent-child relationship between a roadway/direction, and equipment on it, not a bunch of different segments of the same road.
2. If changes in the lane configuration or roadway trigger a new road event, who is responsible for maintaining that data? When lane configurations are changed during construction, typically the DOT and contractor will be the ones tracking this, not the smart work zone vendor providing the feed. So, how can this be properly maintained and communicated? My experience is that in major highway construction projects, lane configurations change all the time. So how can this be managed properly?

[devorah-ql]

The definition of the LaneObjects for a particular road event is also unclear. It does not seem that each individual vendor should be defining the roadway geometry. This seems like a task for the DOT or other agency. If so, do they simply submit a schema to the vendor for this data to be used in the WZDX. How are these roadway definitions managed, and by whom?

[natedeshmukhtowery]

@devorah-ql thanks for these inputs. Really helpful. I'll look forward to the discussion here and at the 9/23 meeting!

[j-d-b]

@devorah-ql thank you for your comments. Can you create a new issue that includes the questions in 2. which are not related to refactoring relationship object? I am afraid they will get lost here.

[j-d-b]

@devorah-ql also see #208 which may clarify the difference between the two feeds WZDx v4.0 will define: the WZDxFeed (work zone information) and the SwzDeviceFeed (field device information).

[devorah-ql]

Thanks @j-d-b. Yes, I can create a new issue for question 2. With regard to #208, yes, I am on the swz subgroup, so I am aware of the new swz feed and think it will be very helpful. But the issue is that it is relying on the RoadEvent objects defined by WZDX in general. That is why when I originally submitted these comments with regard to the SWZ feed, you asked me to move them to WZDX. It is clear that they are defined within WZDX so can only be changed from there.

[j-d-b]

@devorah-ql thanks for creating an issue.

For reference: #214.

[sknick-iastate]

After some further discussion with others, below is a modification to the proposed refactoring of the relationship object. One of the major changes is that all relationships should be made with a road event. This seems to be more straightforward as there are not new entities added that group road events together. We also modified the type enumerations that work better in a few scenarios we put together and help further describe the relationship within the road events.

related_road_events property on the RoadEvent object (replaces relationship)

Property Name	Value	Description	Conformance	Notes
related_road_events	Array; [RelatedRoadEvents object] (see below)	A list describing one or more road events which are related to this road event, such as a work zone project it is part of or another road event that occurs before or after it in sequence.	Optional

RelatedRoadEvents Object

The RelatedRoadEvents object is used to identify another road event that is related to a road event.

Property Name	Value	Description	Conformance	Notes
type	RelatedRoadEventType enumerated type (see below)	The type of road event being identifed, such as another sequence of related work zones, a detour, or next road event in sequence.	Required
id	String	An identifier for the related road event by the type property.	Required

Used By

Property	Object
related_road_event	RoadEvent

RelatedRoadEventType Enumerated Type

Describes a type of related road event, such as a work zone project, recurrent work zone, or detour-type road event.

Value	Description
first-in-sequence	The first road event in a sequence of road events that together describe a full work zone or detour
next-in-sequence	The next (subsequent) road event in a sequence of road events that together describe a full work zone or detour
first-occurrence	The first road event of the first occurrence of a recurrent work zone. End users will need to iterate using the first road event to find all relevant road events to a related work zone
next-occurrence	The first road event of the next occurrence of a recurrent work zone. End users will need to iterate using the first road event to find all relevant road events to a related work zone
related-work-zone	First road event of related work zones (i.e. not part of a sequence of road events or recurrent work zone) that are relevant to the given road event. End users will need to iterate using the first road event to find all relevant road events to a related work zone
related-detour	First road event of related detours (i.e. not part of a sequence of road events) that are relevant to the given road event. End users will need to iterate using the first road event to find all relevant road events to a related detour
planned-moving-operation	First road event of a related planned moving operation work zones (i.e. not part of a sequence of road events) that are relevant to the given road event. End users will need to iterate using the first road event to find all relevant road events to a related work zone
active-moving-operation	First road event of a related active moving operation work zones (i.e. not part of a sequence of road events) that are relevant to the given road event. End users will need to iterate using the first road event to find all relevant road events to a related work zone

Used By

Property	Object
type	RelatedRoadEvents

[j-d-b]

Resolved in #322.