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

[j-d-b]

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.

[lynnerandolph]

We would definitely like to see this occur!

[natedeshmukhtowery]

Agree with the need for a JSON Schema. My only substantive concern at this point would be that a JSON Schema would need to be consistent with what the WZDx specification has tried to balance so far - allowing for the diversity of existing approaches but trying to bring some degree of harmony.

If folks think that a JSON Schema is a helpful approach to feed validation that doesn't become too prescriptive, then it seems to be a very useful, even critical, tool to have.

Thoughts?

Also worth noting that a team at 18F developed a validator for v1.1 WZDx JSON feeds, which may be a possible place to build from: https://github.com/18F/usdot-jpo-ode-workzone-data-exchange

[j-d-b]

@natedeshmukhtowery can you clarify what you mean by the following?

allowing for the diversity of existing approaches but trying to bring some degree of harmony

The JSON Schema would allow for as much diversity of implementation as possible given the required fields and GeoJSON required structure.

I'm glad to see there was a JSON Schema for v1.1, thank you for linking to it. I feel as though we should definitely go ahead with this for v2. I'll begin putting that together for review.

[j-d-b]

Note also we still need community consensus on how we want to represent value-less optional fields, as described in the first issue comment text.

[natedeshmukhtowery]

@j-d-b your following sentence clarifies sufficiently - as long as the JSON schema allows for as much diversity of implementation as possible given the required elements and GeoJSON structure, I'm 100% comfortable. This is the sharp edge of where my technical knowledge ends...

Thanks for moving forward with a v2 Schema draft - agree that there needs to be additional discussion on the value-less optional fields - @sknick-iastate, @DeraldDudley and others - any thoughts?

[j-d-b]

Resolved in #79