Define semantic cardinality for GTFS-realtime fields (#64)

* Define semantic cardinality for GTFS-realtime fields

* As originally discussed in #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.

* Make trip.stop_time_update conditionally required based on trip.schedule_relationship

Addresses #64 (review)

* Fix conditional states for stop_time_update.arrival/departure

...based on stop_time_update.schedule_relationship.  See https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#enum-schedulerelationship

* Separate "Required" and "Cardinality" into different columns

* 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

* Change FeedMessage.entity to "Conditionally required"

* 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.

gtfs-realtime/proto/gtfs-realtime.proto

@@ -31,6 +31,10 @@ package transit_realtime;
 // obtained as a response to an appropriate HTTP GET request.
 // A realtime feed is always defined with relation to an existing GTFS feed.
 // All the entity ids are resolved with respect to the GTFS feed.
+// Note that "required" and "optional" as stated in this file refer to Protocol
+// Buffer cardinality, not semantic cardinality.  See reference.md at
+// https://github.com/google/transit/tree/master/gtfs-realtime for field
+// semantic cardinality.
 message FeedMessage {
   // Metadata about this feed and feed message.
   required FeedHeader header = 1;
@@ -47,8 +51,8 @@ message FeedMessage {
 // Metadata about a feed, included in feed messages.
 message FeedHeader {
   // Version of the feed specification.
-  // The current version is 1.0.
-  required string gtfs_realtime_version = 1;
+  // The current version is 2.0.
+  required string gtfs_realtime_version = 2;
 
   // Determines whether the current fetch is incremental.  Currently,
   // DIFFERENTIAL mode is unsupported and behavior is unspecified for feeds

gtfs-realtime/spec/en/examples/alerts.asciipb

@@ -1,7 +1,7 @@
 # header information
 header {
-  # version of speed specification. Currently "1.0"
-  gtfs_realtime_version: "1.0"
+  # version of speed specification. Currently "2.0"
+  gtfs_realtime_version: "2.0"
 
   # determines whether dataset is incremental or full
   incrementality: FULL_DATASET

gtfs-realtime/spec/en/examples/trip-updates-full.asciipb

@@ -1,7 +1,7 @@
 # header information
 header {
-  # version of speed specification. Currently "1.0"
-  gtfs_realtime_version: "1.0"
+  # version of speed specification. Currently "2.0"
+  gtfs_realtime_version: "2.0"
   # determines whether dataset is incremental or full
   incrementality: FULL_DATASET
   # the moment where this dataset was generated on server