Changed reference.md and service-alerts.md to clarify ambiguity

[minhhpham]

Clarifying ambiguity in Alert.EntitySelector. Problem can be viewed at CUTR-at-USF/gtfs-realtime-validator#19

[barbeau]

Thanks @minhhpham! A few comments in-line. Could you also update the alert example as seen at https://developers.google.com/transit/gtfs-realtime/examples/alerts to define some of this logic in context there too?

[barbeau]

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.

->

You may include multiple entity selectors to apply the same Alert to multiple entities. When multiple field are included in one informed_entity, they should be interpreted as being joined by the AND logical operator.

We don't want to duplicate the entire Alert - instead producers can include multiple informed_entity clauses to get the OR behavior. See http://ridepsta.net/gtfsrt/alerts?debug for an example alert with multiple informed_entity clauses.

[barbeau]

After ...by the AND logical operator., I'd add another short explanation and example, like:

In other words, the alert should only be applied in context that meet all of the provided informed_entity fields. 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 stops on route 1, and it should NOT be applied to any other routes at stop 5.

[barbeau]

If you would like to join the entities by the OR operator, you should include them in separate Alert feed entities.

->

If you would like to represent an alert that affects more than one entity (e.g., an entire route plus a stop not on that route), you should add multiple informed_entity clauses to your alert, with each of them applying to the affected entity (e.g., one informed_entity for the affected route, and one informed_entity for the affected stop not on that route).

We can include multiple informed_entity clauses, so we can have the same Alert apply to multiple distinct things without having to duplicate the entire alert in the feed.

[minhhpham]

I changed this paragraph to this:

You may include multiple entity selectors in one informed_entity. When multiple fields are selected 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).

Does this look good?

[minhhpham]

I changed the example file into this:

    # selects which GTFS entities will be affected
    informed_entity {
      # valid parameters:
      # agency_id, route_id, route_type, stop_id, trip (see TripDescriptor)
      route_id: "219"
    }
    # multiple selectors (informed_entity) can be given
    informed_entity {
      stop_id: "16230"
    }
    # multiple parameters 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.
    }

[barbeau]

@minhhpham Did you push your changes to this branch? I still only see one commit here.

[barbeau]

in one alert feed should be changed to in one alert entity

[barbeau]

I'm closing this draft proposal, as I've opened a final version at google#118. Thanks @minhhpham for all your work on this!