[Clarification] from/to_stop_id & from/to_trip_id description in transfers.txt

[tzujenchanmbd]

Issue

Recently we have received requests to change the behavior of the Canonical GTFS Validator regarding transfers.from_stop_id and transfers.to_stop_id (e.g. MobilityData/gtfs-validator#1621), stemming from different interpretations of the current specification.

The current description of from_stop_id is:

Identifies a stop or station where a connection between routes begins. If this field refers to a station, the transfer rule applies to all its child stops. Refering to a station is forbiden for transfer_types 4 and 5.

Based on the description and the discussion in PR#303, it should indicate that from_stop_id and to_stop_id cannot be empty, and it cannot be a "station" (location_type =1) if transfer_type is 4 or 5.

However, some community members may interpret it as:

• from_stop_id is required for transfer_type 1, 2, and 3; optional for transfer_type 4 and 5 OR
• from_stop_id is required for transfer_type 1, 2, and 3; forbidden for transfer_type 4 and 5

To prevent such confusion from happening again, we propose the following modification:

Changes in this PR

• Change presence from Conditionally Required to Required. According to the definition of presence Required - "The field or file must be included in the dataset and contain a valid value for each record", these 2 fields should be Required.
• Remove the word "forbidden" from description to avoid potential confusion.

+@gcamp - the main contributor of PR#303

[gcamp]

LGTM on the stop vs station change, however it should still be Conditionally required. For transfer_type 4 and 5, the stop is optional and the main values used in this case are the trip_ids values.

[tzujenchanmbd]

Thanks for the clarification @gcamp !
158ad1d - Changed presence back to Conditionally Required and explicitly stated when is required or optional.

[gcamp]

👏

[isabelle-dr]

@tzujenchanmbd I made a few editorial edits for consistency with the rest pf the spec:

• having "Optional" not in bold
• enum values in code formatting
• added a formatting change to from_trip_id to reproduce in to_trip_id to fit with the rest of the spec

[isabelle-dr]

It might be worth seeing if pieces of #363 could also be included in this PR. The initial scope of it was to revert transfer_type=4 and 5 but it also contained good editorial/clarification fixes.

[tzujenchanmbd]

Included editorial suggestions from #363 . Changes from #363 that would potentially change semantics and/or validator behavior are not included in this PR

[isabelle-dr]

Nit: In the following statement:

It must refer to a stop if transfer_type is 4 or 5

I would add (location_type=0) after "stop".

[tzujenchanmbd]

Identifies a stop (location_type=0) or a station (location_type=1) where a connection between routes begins.

This sentence should already limit to location_type 0 or 1 for this field.

Added "(location_type=0)" after the "stop" - e785501

[isabelle-dr]

One small comment, this LGTM.

[tzujenchanmbd]

This PR is solely for clarification purposes and does not alter any original meaning. However, since there are quite a few changes in wording, I am initiating a vote to confirm the descriptions with the community.

Voting ends on 2024-09-17 at 23:59:59 UTC.

[gcamp]

+1 Transit

[westontrillium]

+1 from Trillium

[SteveGladstone]

+1 Maryland Transit Administration

[skinkie]

+1 OpenGeo

[tzujenchanmbd]

The vote passed on 2024-09-17 at 23:59:59 UTC.

4 votes in favour and no votes against.

Votes came from:
Transit (@gcamp)
Trillium (@westontrillium)
Maryland Transit Administration (@SteveGladstone)
OpenGeo (@skinkie)

Thank you to everyone who participated!

[tzujenchanmbd]

The Canonical GTFS Validator V6.0.0 has fixed the unexpected behavior regarding this clarification. Please refer to the release page: https://github.com/MobilityData/gtfs-validator/releases/tag/v6.0.0.