Define semantic cardinality for GTFS-realtime fields #64
* As originally discussed in google#19 and https://groups.google.com/forum/#!msg/gtfs-realtime/wm3W7QIEZ9Y/DLyWKkknJyoJ, the current GTFS-realtime spec documentation describes field Protocol Buffer cardinality, not semantic cardinality. This has created confusion for consumers and producers where fields have been omitted based on them being labeled as "optional" in the GTFS-realtime spec, even if they were required under certain logical transit conditions (e.g., stop_sequence must be provided if a trip contains a loop). * This patch changes the "Cardinality" documentation to define the semantic cardinality for each data element as "required", "conditionally required", and "optional". It also bumps the gtfs_realtime_version in the .proto file to 2.0 so validators can strictly enforce semantic cardinality based on the gtfs_realtime_version.
I should also mention that with the exception of making the header timestamp required, I believe all of the other field cardinalities reflect existing GTFS-rt documentation. So, this isn't so much proposing something new as it is trying to capture existing logic spread around the docs into a concise description in the Cardinality and Description fields.
…ule_relationship Addresses google#64 (review)
...based on stop_time_update.schedule_relationship. See https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#enum-schedulerelationship
* A new "Required" field holds the information as to whether a particular field is Required, Optional, or Conditionally required * The existing "Cardinality" field is changed to a semantic version of cardinality instead of using Protobuf cardinality
* This field can't be "Required", because there are legitimate scenarios where a feed may not have any real-time information about the system (e.g., if it's 3am, and the agency doesn't offer any service at 3am). So, change to "Conditionally required" with description.
Sorry for the delay updating this proposal - I was out on vacation last week.
Unfortunately we currently don't have the 3 needed votes for this to pass (we're at 2), and the voting period ended July 20th.
This ends up being a good thing, as I realized there was one issue in this proposal (FeedMessage.entity should be "Conditionally required" - I just fixed this in 3c24ff7, see commit description for more info).
So, I'd like to call for another vote on this PR - voting will end Tuesday Aug 8th at 23:59:59 UTC.
I vote yes.…
On Tue, Aug 1, 2017 at 2:04 AM, Kenneth Tsang ***@***.***> wrote: +1 I vote yes. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#64 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABrtS4u7HRBhQ_opQROXQh6VOnZJXO2lks5sTmuIgaJpZM4OIlGJ> .
Alright, looks like this passed the vote - 3 yes votes and 0 nos! Congrats everyone, we have GTFS-realtime v2.0! 🎊 🎊 🎊
This includes better documentation for semantic cardinality and requirements - which fields are required and under what conditions.
@RachM Would you be able to squash and merge this using the Github web UI, so one commit ends up in the master branch?
Alternately I could force-push a new single commit to replace the iterative commits currently in the PR, although it will erase the history of commits based on feedback through the proposal.