Clarify new location_types in stops.txt spec #188
Description
The "pathways and locations" pull request #143 introduced several new location_types for stops, generalizing stops into nodes for use in routable graphs of stations.
When talking to @t2gran today about the internal domain model of a GTFS consumer application (OTP) we realized neither of us really understood some new location_types, even after reading the spec. So I believe some definitions and explanations should be revised, especially if they are to be understood by first-time readers.
Specifically, location_type 4 "boarding area" and location_type 0 "stop" have very similar descriptions, and one can only guess at their different roles if one knows to read the descriptions of parent_station field and pathways.txt. Even then it is not entirely clear that location_type 0 is a "true" stop referenced in schedules, while 4 is a micro-mapping modeling node akin to type 3.
The location_type section should clearly state if only location_type 0 may be referenced by stop_times, and whether all the other location_types instead serve to model movement within stations and logical groupings of platforms into stations, and often only make sense in the presence of a pathways table. It must be apparent to the first time reader that only stops (location_type 0) are truly necessary and universally used, and that the rest of the types are set apart as conceptual generalizations of "stop" to "node" or "point".
Additionally, the section on parent_station implies that location_type 4 boarding areas are hierarchically under platforms (i.e. under stops, location_type 0) at the lowest level in a hierarchy. Further explanation is needed. It's not clear (at least on first reading, without piecing together disparate parts of the spec) how a GTFS consumer system would ever determine which boarding area a rider would need to pass through, because the transition into the public transit network happens at the location_type 0 level. Any movement via pathways to a location_type 4 is a movement to a leaf node, and therefore cannot be located along any path through the network.
I see some text in the platforms.txt section stating: "A platform that has boarding areas is treated as a parent object, not a point. It may not have pathways assigned. All pathways should be for boarding areas." This provides some hints about how pathways are connected, but it's still not explicitly stated how this relates to stop_times. The expressions "parent object" and "not a point" are not well-defined and it's difficult to know what they imply or require. My understanding is that by following pathways we can reach boarding areas only (never platforms), and that the routing system must then make the transition up the hierarchy from boarding location to platform when relating to schedule data from stop_times. This seems somewhat awkward to me, but I see how it could work. If this is the intended meaning and behavior, it should be explained more fully, and information included in all fields related to this structure.
Finally, based on recent discussions I think it would be best to avoid the aliasing of platform_type 0 "stop" as "platform". The spec should say that stops are effectively platforms when they are within a station (as a helpful mental image), but we should not introduce both of these as standard terms in the data model vocabulary - this rapidly leads to confusion by implying that they are distinct types that might have different type codes.