From 5e09543ce43b0f42c89f49c8073c4f256bd1b6c9 Mon Sep 17 00:00:00 2001 From: Minh Pham Date: Mon, 22 Oct 2018 18:46:42 -0400 Subject: [PATCH 1/7] Changed reference.md and service-alerts.md to clarify ambiguity in Alert.EntitySelector --- gtfs-realtime/spec/en/reference.md | 2 +- gtfs-realtime/spec/en/service-alerts.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 1e71bfeca..0d6d3e0dd 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -372,7 +372,7 @@ Identification information for the vehicle performing the trip. ## _message_ EntitySelector -A selector for an entity in a GTFS feed. The values of the fields should correspond to the appropriate fields in the GTFS feed. At least one specifier must be given. If several are given, then the matching has to apply to all the given specifiers. +A selector for an entity in a GTFS feed. The values of the fields should correspond to the appropriate fields in the GTFS feed. At least one specifier must be given. If several are given, they should be interpreted as being joined by the `AND` operator and the combination of specifiers should match the information in the corresponding GTFS feed. #### Fields diff --git a/gtfs-realtime/spec/en/service-alerts.md b/gtfs-realtime/spec/en/service-alerts.md index c27031ecc..629d89a66 100644 --- a/gtfs-realtime/spec/en/service-alerts.md +++ b/gtfs-realtime/spec/en/service-alerts.md @@ -14,7 +14,7 @@ If no time is given, we will display the alert for as long as it is in the feed. ### Entity Selector -Entity selector allows you specify exactly which parts of the network this alert affects, so that we can display only the most appropriate alerts to the user. You may include multiple entity selectors for alerts which affect multiple entities. +Entity selector allows you specify exactly which parts of the network this alert affects, so that we can display only the most appropriate alerts to the user. Entities are selected using their GTFS identifiers, and you can select any of the following: @@ -24,6 +24,8 @@ Entities are selected using their GTFS identifiers, and you can select any of th * Trip - affects a particular trip * Stop - affects a particular stop +You may include multiple entity selectors. When multiple entities are selected in one Alert feed entity, they should be interpreted as being joined by the `AND` logical operator. If you would like to join the entities by the `OR` operator, you should include them in separate Alert feed entities. + ### Cause What is the cause of this alert? You may specify one of the following: From 496d428c38706d0c62c0f27e23c9378cc8df612d Mon Sep 17 00:00:00 2001 From: Minh Pham Date: Mon, 29 Oct 2018 14:21:44 -0400 Subject: [PATCH 2/7] Revised Alerts example file, revised service-alerts.md --- gtfs-realtime/spec/en/examples/alerts.asciipb | 9 ++++++++- gtfs-realtime/spec/en/service-alerts.md | 4 +++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/gtfs-realtime/spec/en/examples/alerts.asciipb b/gtfs-realtime/spec/en/examples/alerts.asciipb index 774adeb1f..19da50c1d 100644 --- a/gtfs-realtime/spec/en/examples/alerts.asciipb +++ b/gtfs-realtime/spec/en/examples/alerts.asciipb @@ -30,10 +30,17 @@ entity { # agency_id, route_id, route_type, stop_id, trip (see TripDescriptor) route_id: "219" } - # multiple selectors (informed_entity) can be given + # multiple selectors (informed_entity) can be included in one alert feed informed_entity { stop_id: "16230" } + # multiple fields can be included in one informed_entity + informed_entity { + stop_id: "16299" + route_id: "100" + # This example means route 100 at stop 16299. + # This does not apply to any other stop on route 100 and any other route at stop 16299. + } # cause of the alert - see gtfs-realtime.proto for valid values cause: CONSTRUCTION diff --git a/gtfs-realtime/spec/en/service-alerts.md b/gtfs-realtime/spec/en/service-alerts.md index 629d89a66..128f7dd4d 100644 --- a/gtfs-realtime/spec/en/service-alerts.md +++ b/gtfs-realtime/spec/en/service-alerts.md @@ -24,7 +24,9 @@ Entities are selected using their GTFS identifiers, and you can select any of th * Trip - affects a particular trip * Stop - affects a particular stop -You may include multiple entity selectors. When multiple entities are selected in one Alert feed entity, they should be interpreted as being joined by the `AND` logical operator. If you would like to join the entities by the `OR` operator, you should include them in separate Alert feed entities. +You may include more than one of the fields listed above in one `informed_entity`. When multiple fields are included in one `informed_entity`, they should be interpreted as being joined by the `AND` logical operator. In other words, the alert should only be applied in a context that meets all of the fields provided in an `informed_entity`. For example, if `route_id: "1"` and `stop_id: "5"` are both included in one `informed_entity`, then the alert should apply only to route 1 at stop 5. It should NOT be applied to any other stop on route 1, and it should NOT be applied to any other route at stop 5. + +If you would like to represent an alert that affects more than one entity (e.g. an alert to all stops along route 1 and to all routes that visit stop 5) , you should add multiple `informed_entity` to your `alert`, with each of them applying to the affected entity (e.g. one `informed_entity` that includes route 1 and another `informed_entity` that includes stop 5). ### Cause From 7ce66477e9569a5a740d55614e2f511f4a443c0a Mon Sep 17 00:00:00 2001 From: Minh Pham Date: Thu, 1 Nov 2018 10:33:09 -0400 Subject: [PATCH 3/7] changed 'alert feed' to 'alert entity' --- gtfs-realtime/spec/en/examples/alerts.asciipb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/examples/alerts.asciipb b/gtfs-realtime/spec/en/examples/alerts.asciipb index 19da50c1d..601bfd061 100644 --- a/gtfs-realtime/spec/en/examples/alerts.asciipb +++ b/gtfs-realtime/spec/en/examples/alerts.asciipb @@ -30,7 +30,7 @@ entity { # agency_id, route_id, route_type, stop_id, trip (see TripDescriptor) route_id: "219" } - # multiple selectors (informed_entity) can be included in one alert feed + # multiple selectors (informed_entity) can be included in one alert entity informed_entity { stop_id: "16230" } From 2edb62d42a272a34e73f262166c2f6e0e41e5cfd Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Thu, 8 Nov 2018 16:06:08 -0500 Subject: [PATCH 4/7] Add example --- gtfs-realtime/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 0d6d3e0dd..09d70eb91 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -372,7 +372,7 @@ Identification information for the vehicle performing the trip. ## _message_ EntitySelector -A selector for an entity in a GTFS feed. The values of the fields should correspond to the appropriate fields in the GTFS feed. At least one specifier must be given. If several are given, they should be interpreted as being joined by the `AND` operator and the combination of specifiers should match the information in the corresponding GTFS feed. +A selector for an entity in a GTFS feed. The values of the fields should correspond to the appropriate fields in the GTFS feed. At least one specifier must be given. If several are given, they should be interpreted as being joined by the logical `AND` operator and the combination of specifiers should match the information in the corresponding GTFS feed. In other words, in order for an alert to apply to an entity it must match all of the provided `EntitySelector` fields. For example, an `EntitySelector` that includes the fields `route_id: "5"` and `route_type: "3"` applies only to the `route_id: "5"` bus - it does not apply to any other routes of `route_type: "3"`. #### Fields From 85040614ed0efdeb8b8deb5050d600c3cf01228b Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Thu, 8 Nov 2018 16:07:48 -0500 Subject: [PATCH 5/7] Add back sentence to allow single entity selector --- gtfs-realtime/spec/en/service-alerts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/service-alerts.md b/gtfs-realtime/spec/en/service-alerts.md index 128f7dd4d..56b4f0afd 100644 --- a/gtfs-realtime/spec/en/service-alerts.md +++ b/gtfs-realtime/spec/en/service-alerts.md @@ -14,7 +14,7 @@ If no time is given, we will display the alert for as long as it is in the feed. ### Entity Selector -Entity selector allows you specify exactly which parts of the network this alert affects, so that we can display only the most appropriate alerts to the user. +Entity selector allows you specify exactly which parts of the network this alert affects, so that we can display only the most appropriate alerts to the user. You may include multiple entity selectors for alerts which affect multiple entities. Entities are selected using their GTFS identifiers, and you can select any of the following: From 4b87481fba147cfd462121ae47a95122b07102c7 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Thu, 8 Nov 2018 16:12:27 -0500 Subject: [PATCH 6/7] Further explain separate EntitySelectors --- gtfs-realtime/spec/en/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/reference.md b/gtfs-realtime/spec/en/reference.md index 09d70eb91..859af403f 100644 --- a/gtfs-realtime/spec/en/reference.md +++ b/gtfs-realtime/spec/en/reference.md @@ -372,7 +372,7 @@ Identification information for the vehicle performing the trip. ## _message_ EntitySelector -A selector for an entity in a GTFS feed. The values of the fields should correspond to the appropriate fields in the GTFS feed. At least one specifier must be given. If several are given, they should be interpreted as being joined by the logical `AND` operator and the combination of specifiers should match the information in the corresponding GTFS feed. In other words, in order for an alert to apply to an entity it must match all of the provided `EntitySelector` fields. For example, an `EntitySelector` that includes the fields `route_id: "5"` and `route_type: "3"` applies only to the `route_id: "5"` bus - it does not apply to any other routes of `route_type: "3"`. +A selector for an entity in a GTFS feed. The values of the fields should correspond to the appropriate fields in the GTFS feed. At least one specifier must be given. If several are given, they should be interpreted as being joined by the logical `AND` operator and the combination of specifiers should match the information in the corresponding GTFS feed. In other words, in order for an alert to apply to an entity it must match all of the provided EntitySelector fields. For example, an EntitySelector that includes the fields `route_id: "5"` and `route_type: "3"` applies only to the `route_id: "5"` bus - it does not apply to any other routes of `route_type: "3"`. If a producer wants an alert to apply to `route_id: "5"` as well as `route_type: "3"`, it should provide two separate EntitySelectors, one referencing `route_id: "5"` and another referencing `route_type: "3"`. #### Fields From 32c25defd7b04677b8ff26921d9239ee053e8630 Mon Sep 17 00:00:00 2001 From: Sean Barbeau Date: Wed, 14 Nov 2018 17:41:45 -0500 Subject: [PATCH 7/7] Further clarify multiple informed_entity behavior --- gtfs-realtime/spec/en/service-alerts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtfs-realtime/spec/en/service-alerts.md b/gtfs-realtime/spec/en/service-alerts.md index 56b4f0afd..bc6f58d28 100644 --- a/gtfs-realtime/spec/en/service-alerts.md +++ b/gtfs-realtime/spec/en/service-alerts.md @@ -26,7 +26,7 @@ Entities are selected using their GTFS identifiers, and you can select any of th You may include more than one of the fields listed above in one `informed_entity`. When multiple fields are included in one `informed_entity`, they should be interpreted as being joined by the `AND` logical operator. In other words, the alert should only be applied in a context that meets all of the fields provided in an `informed_entity`. For example, if `route_id: "1"` and `stop_id: "5"` are both included in one `informed_entity`, then the alert should apply only to route 1 at stop 5. It should NOT be applied to any other stop on route 1, and it should NOT be applied to any other route at stop 5. -If you would like to represent an alert that affects more than one entity (e.g. an alert to all stops along route 1 and to all routes that visit stop 5) , you should add multiple `informed_entity` to your `alert`, with each of them applying to the affected entity (e.g. one `informed_entity` that includes route 1 and another `informed_entity` that includes stop 5). +If you would like to represent an alert that affects more than one entity (e.g. an alert for both route 1 and stop 5) , you should add multiple `informed_entity` to your `alert`, with each of them applying to the affected entity (e.g. one `informed_entity` that includes route 1 and another `informed_entity` that includes stop 5). ### Cause