Clarify usage of 'update_date' property on the FeedDataSource object

[j-d-b]

Background

There is an update_date property on the RoadEventFeedInfo (WZDx feed-level info), RoadEventDataSource, and RoadEvent objects.

The property is defined as:

The UTC date and time when the data feed/data source/road event was last updated.

The property can be beneficial for consumers to assess data quality by the recency of the update_date value. It can also be used to indicate to the consumer that something has changed and they should update their cached data.

Currently update_date is required on the feed-level RoadEventFeedInfo but optional on both the RoadEventDataSource and RoadEvent.

The feed-level update_date is not ample to show the RoadEvent information is recently updated as producers may populate the feed-level update_date with every response to a request for the WZDx feed. This would be a fair approach, as it represents when that feed document was generated. It indicates nothing about the recency of the road event data, though.

Proposal

I want to propose requiring update_date on the RoadEvent object. The same can possibly be done for the RoadEventDataSource as well, though the latter is less clear what the update_date represents.

From working with MassDOT to publish their WZDx Feed, the RoadEvent's update_date is a core piece of information and is easily populated by the data processing logic. If there is a change to road event information, we update the value of this property. This allows consumers to note if the data is being maintained and is current.

However, before along with requiring update_date, we should decide and clarify when it should be set—this could be as simple as "when any property of the road event changes".

Next steps

• Decide on a definition for update_date.
• Current or upcoming producers, note if RoadEvent update_date would be a burden to provide.

The intention of all changes to WZDx is never to make the spec harder to implement. My thoughts on this is that it is not a difficult piece of information to gather and is useful. If I am incorrect or missing possible negatives of requiring update_date.

Edited to change to clarifying the update date before it can be required

[j-d-b]

Though a simple change, requiring this property breaks backwards compatibility, so if there is support for this and it is not a challenge for other producers to supply, getting it in for the fall 2021 v4.0 release would be ideal. Else it will likely be at least another year before the change can be made.

[j-d-b]

Co-chairs discussion of this issue made it clear that before update_date can be required it needs to be clarified what the date represents and when it should be updated.

[j-d-b]

WZDx v4.0 included the clarification of what update_date on the FeedInfo refers to:

The UTC date and time when the GeoJSON file (representing the instance of the feed) was generated.

Thus, I think this issue can be resolved by better descriptions of the update_date property on the FeedDateSource, RoadEventCoreDetails, and FieldDeviceCoreDetails.

Below are proposed updates to the descriptions for the update_date property on these three objects.

RoadEventCoreDetails update_date

Current

The UTC time and date when the activity or event was updated.

Proposed

The UTC date and time when any information in the RoadEventFeature (including child objects) that the RoadEventCoreDetails applies to was most recently updated or confirmed as up to date.

FieldDeviceCoreDetails update_date

Current

The UTC time and date when the field device information was updated.

Proposed

The UTC date and time when any information in the FieldDeviceFeature (including child objects) that the FieldDeviceCoreDetails applies to was most recently updated or confirmed as up to date.

FeedDataSource update_date

Current

The UTC date and time when the data source was last updated.

Proposed

The UTC date and time that the feed producer most recently received data from the data source.

Edited based on early April 2022 co-chairs discussion

[j-d-b]

FieldDeviceCoreDetails and RoadEventCoreDetails update_date descriptions were changed/resolved in #302.

This issue can remain open regarding the update_date on FeedDataSource.