Simplifying locations.geojson

[omar-kabbani]

This issue relates to the GTFS-Flex proposal, and is opened following a series of roundtable discussion to resolve the outstanding issues with the proposal. These discussions were hosted by MobilityData and attended by various stakeholders within the GTFS community.

You can find the GTFS-Flex proposal here: https://github.com/MobilityData/gtfs-flex/blob/master/spec/reference.md

---

The file locations.geojson is based on the geoJSON format defined by RFC 7946.
In the current GTFS-Flex proposal, the file locations.geojson is structured as follows:

• Type (always set to FeatureCollection)
• Features
  • type (Always set to Feature)
  • id (Unique ID to describe the location)
  • properties (These properties match how stops are described in stops.txt)
    • stop_name (Text name)
    • stop_desc (Text description)
    • zone_id (In case of Fares v1)
    • stop_url (URL)
  • Geometry
    • Type (Options are: Point, MultiPoint, Linestring, MutiLineString, Polygon, and MultiPolygon)
    • coordinates (Array of coordinates)

It is possible to simplify locations.geojson and to tailor it to GTFS-Flex while remaining compliant with RFC 7946. We propose the following changes:

• Make the file locations.geojson lighter
  • Remove properties and all fields that fall under it (those will be described in stops.txt)
  • Remove Point, MultiPoint, Linestring, and MutiLineString from the list of options for Geometry.Type since there is no need to define points or lines in locations.geojson
• Use the file locations.geojson to create the zone (ID and geometry)
• Use the file stops.txt to associate attributes to the zone (stop_name, stop_desc, zone_id, stop_url, and others)

This means that zones are created in locations.geojson, and then listed with all other stops in stops.txt to associate attributes to the zone (some fields such as stops.stop_lat and stops.stop_lon will be forbidden when a record in stops.txt corresponds to a zone)

The advantages to doing this are:

1. Stops and zones will be listed in the same file instead of multiple files
2. Changes to the spec that relate to the attributes of stops and zones will only affect stops.txt (no need to maintain field parity with locations.geojson)

With these changes, the file locations.geojson will be structured as follows:

• Type (always set to FeatureCollection)
• Features
  • type (Always set to Feature)
  • id (Unique ID to describe the location)
  • Geometry
    • Type (Polygon, MultiPolygon)
    • coordinates (array of coordinates)

If there is a general consensus on proceeding with this option, we can post a proposal of how to modify the files and fields in stops.txt (and other files like transfers.txt, pathways.txt, levels.txt, and fare_leg_rules.txt) to accommodate GeoJSON locations.

[westontrillium]

I agree with

Make the file locations.geojson lighter

• Remove properties and all fields that fall under it (those will be described in stops.txt)
• Remove Point, MultiPoint, Linestring, and MutiLineString from the list of options for Geometry.Type since there is no need to define points or lines in locations.geojson

But to me, I do not see the advantage of including zones in stops.txt.

Stops and zones will be listed in the same file instead of multiple files

But then information on zones will be split between two files, so two files still have to be referenced.

Why do stops and zones need to live in the same file? It seems redundant to list zones in stops.txt when they will already exist with an id in locations.geojson. I'm assuming the implied advantage of doing this is so that an application only needs to hunt for the primary key of stop_times.stop_id in one file–stops.txt. But, consumers will need to reference non-stops.txt records in stop_times.stop_id with the existence of location_groups.txt anyway, so the need for an app to be able to search for a primary key in more than one file doesn't go away.

Setting aside the existence of location_groups.txt for a moment, if you still need to reference locations.geojson somewhere along the line, isn’t referencing a stop_id in stops.txt first just adding an extra step? You still have to pull from a separate file, we’re just changing when in the process that takes place.

Changes to the spec that relate to the attributes of stops and zones will only affect stops.txt (no need to maintain field parity with locations.geojson)

I think it's unlikely that this would become an issue, more so if we simplify the locations.geojson file. First, what kind of changes to the attributes of stops are likely and likely to affect zones as well? Secondly, including zones in stops.txt doesn't guarantee the necessity to maintain parity with other files in the event that there is some sort of change to the spec in this way; there would still be a locations.geojson file, a location_groups.txt file, and potentially others down the road, to deal with.

[tsherlockcraig]

• Remove Point, MultiPoint, Linestring, and MutiLineString

The last, 'MutliLineString', I'm not so sure about. A polygon could accomplish the same but a multiline seems like the right way to indicate that a specific set of roads within a polygon is the service area.

I'm also a little unclear on question of 'zone_id', and will need to review the Fares v2 spec again before I feel like I can comment on that.

Generally, however, I support this change.

[e-lo]

If the two objectives are to

1. consolidate PK items and properties to a single table (which seems like a good idea) and
2. continue support visualization of geographic data out of the box (e.g. geojson)

I'm thinking about something like:

shapes.geojson

PK: shape_id
(replaces shapes.txt if used)

Contains any shapes associated with any entity in stops.txt and trips.txt which can be mapped out of the box.

stops.txt

PK: stop_id
Contains information about any stops, stations, location group (location_type = 5), and zone (location_type = 6).

If location_type is 5 or 6, stop_lat and stop_lon are not required.
If location_type is 6 (zone), shape_id (new column) is required...along any with others needed (?)

[westontrillium]

I haven't yet heard a good justification for adding zones to the stops.txt file. Why is it important to have stops and zones listed in the same file? Keeping the primary key for a zone within locations.geojson keeps all zone information in one place instead of having zone information straddle multiple files.

In addition, I don't think zones need attributes akin to stop_name, stop_desc etc., so there's no benefit to being able to being able to attach those fields to a zone.

@e-lo IMO, those kinds of changes would have been better suited for the drafting stage of the spec. Given the maturity of Flex, I personally think the community needs to focus on addressing blockers to getting the spec to PR status rather than proposing alternative files/key relationships.

[e-lo]

@e-lo IMO, those kinds of changes would have been better suited for the drafting stage of the spec.

Fair enough. Happy to commit to the process to get it approved.

[leonardehrenfried]

OBA and OTP only support a subset of the available geometry types anyway so I'm ok with allowing only a subset of the available Geojson geometry types.

I'm with @westontrillium when it comes to moving stop_name, stop_description into stops.txt. You already need to parse both files to get a complete picture so you might as well keep all the information about a zone in one place.

I do believe however that zone names and descriptions are useful as they can give hints to a user about why they can be picked up in one place but not another one a few meters down the street.

In OTP we've settled on the following implementation. The start point of a flex leg has the name $streetCornerName (part of $flexZoneName), so it's corner of Main Street and Park Lane (part of Springfield Flex Zone 2).

I would not vote -1 on the moving of the properties into stops.txt as I can see the benefits of having all the information in one place.

[isabelle-dr]

After a discussion with @tzujenchanmbd, I am closing this issue, it has been included in #433