From b279149682fa784a5ae321eaebc20bf7802773b0 Mon Sep 17 00:00:00 2001 From: omar-kabbani <78552622+omar-kabbani@users.noreply.github.com> Date: Thu, 4 Aug 2022 17:37:59 -0400 Subject: [PATCH 1/2] Add fare containers to reference.md --- gtfs/spec/en/reference.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index b3c39ec39..1c88ef02c 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -19,6 +19,7 @@ This document defines the format and structure of the files that comprise a GTFS - [calendar\_dates.txt](#calendar_datestxt) - [fare\_attributes.txt](#fare_attributestxt) - [fare\_rules.txt](#fare_rulestxt) + - [fare\_containers.txt](#fare_containerstxt) - [fare\_products.txt](#fare_productstxt) - [fare\_leg\_rules.txt](#fare_leg_rulestxt) - [fare\_transfer\_rules.txt](#fare_transfer_rulestxt) @@ -343,6 +344,23 @@ For examples that demonstrate how to specify a fare structure with [fare_rules.t | `destination_id` | Foreign ID referencing `stops.zone_id` | Optional | Identifies a destination zone. If a fare class has multiple destination zones, create a record in [fare_rules.txt](#fare_rules.txt) for each `destination_id`.
*Example: The `origin_id` and `destination_id` fields could be used together to specify that fare class "b" is valid for travel between zones 3 and 4, and for travel between zones 3 and 5, the [fare_rules.txt](#fare_rules.txt) file would contain these records for the fare class:*
`fare_id,...,origin_id,destination_id`
`b,...,3,4`
`b,...,3,5` | | `contains_id` | Foreign ID referencing `stops.zone_id` | Optional | Identifies the zones that a rider will enter while using a given fare class. Used in some systems to calculate correct fare class.
*Example: If fare class "c" is associated with all travel on the GRT route that passes through zones 5, 6, and 7 the [fare_rules.txt](#fare_rules.txt) would contain these records:*
`fare_id,route_id,...,contains_id`
`c,GRT,...,5`
`c,GRT,...,6`
`c,GRT,...,7`
*Because all `contains_id` zones must be matched for the fare to apply, an itinerary that passes through zones 5 and 6 but not zone 7 would not have fare class "c". For more detail, see [https://code.google.com/p/googletransitdatafeed/wiki/FareExamples](https://code.google.com/p/googletransitdatafeed/wiki/FareExamples) in the GoogleTransitDataFeed project wiki.* | +### fare_containers.txt + +To describe fare containers, which are used to load fare products such as tickets, passes, and discounted fares. + +File: **Optional** + +Primary Key (`fare_container_id`) + +| Field Name | Type | Presence | Description | +| ------ | ------ | ------ | ------ | +| `fare_container_id` | Unique ID | **Required** | Identifies a fare container. | +| `fare_container_name` | Text | Optional | The name of the fare container as displayed to riders. | +| `amount` | Non-negative currency amount | Optional | The cost of the fare container. | +| `minimum_initial_purchase` | Non-negative currency amount | Optional | The cost of the minimum initial purchase required on the fare container. | +| `currency` | Currency code | **Conditionally Required** | The currency of `fare_containers.amount` or `fare_containers.minimum_initial_purchase`.
Conditionally Required:
- **Required** if `fare_containers.amount` or `fare_containers.minimum_initial_purchase` are defined.
- **Forbidden** if `fare_containers.amount` and `fare_containers.minimum_initial_purchase` are empty. | + + ### fare_products.txt File: **Optional** @@ -357,6 +375,8 @@ To describe the different types of tickets or fares that can be purchased by rid | `fare_product_name` | Text | Optional | The name of the fare product as displayed to riders. | | `amount` | Currency amount | **Required** | The cost of the fare product. May be negative to represent transfer discounts. May be zero to represent a fare product that is free.| | `currency` | Currency code | **Required** | The currency of the cost of the fare product. | +| `fare_container_id` | Foreign ID referencing `fare_containers.fare_container_id` | Optional | Identifies the fare container that the fare product can be loaded on. If this field is left blank, the record corresponds to a fare product that is purchased outside of a fare container. | + ### fare_leg_rules.txt From a1eb24e6f7da66e7fcebc1ff63bf4b486e51eb9c Mon Sep 17 00:00:00 2001 From: omar-kabbani <78552622+omar-kabbani@users.noreply.github.com> Date: Fri, 5 Aug 2022 11:41:56 -0400 Subject: [PATCH 2/2] Update documentation Clearly indicate that fare_containers.txt falls under GTFS-Fares v2 and not v1 Add fare_containers to the dataset files table --- gtfs/spec/en/reference.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/gtfs/spec/en/reference.md b/gtfs/spec/en/reference.md index 1c88ef02c..0eea9bfef 100644 --- a/gtfs/spec/en/reference.md +++ b/gtfs/spec/en/reference.md @@ -110,6 +110,7 @@ This specification defines the following files: | [calendar_dates.txt](#calendar_datestxt) | **Conditionally Required** | Exceptions for the services defined in the [calendar.txt](#calendartxt).

Conditionally Required:
- **Required** if [calendar.txt](#calendartxt) is omitted. In which case [calendar_dates.txt](#calendar_datestxt) must contain all dates of service.
- Optional otherwise. | | [fare_attributes.txt](#fare_attributestxt) | Optional | Fare information for a transit agency's routes. | | [fare_rules.txt](#fare_rulestxt) | **Conditionally Required** | Rules to apply fares for itineraries.

Conditionally Required:
- **Required** if [fare_attributes.txt](#fare_attributestxt) is defined.
- **Forbidden** otherwise. | +| [fare_containers.txt](#fare_containerstxt) | Optional |To describe fare containers, which are used to load fare products such as tickets, passes, and discounted fares.

File [fare_containers.txt](fare_containerstxt) describes fare containers that are not represented in [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). As such, the use of [fare_containers.txt](#fare_containerstxt) is entirely separate from files [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). | | [fare_products.txt](#fare_productstxt) | Optional | To describe the different types of tickets or fares that can be purchased by riders.

File [fare_products.txt](fare_productstxt) describes fare products that are not represented in [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). As such, the use of [fare_products.txt](#fare_productstxt) is entirely separate from files [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). | | [fare_leg_rules.txt](#fare_leg_rulestxt) | Optional | Fare rules for individual legs of travel.

File [fare_leg_rules.txt](#fare_leg_rulestxt) provides a more detailed method for modeling fare structures. As such, the use of [fare_leg_rules.txt](#fare_leg_rulestxt) is entirely separate from files [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). | | [fare_transfer_rules.txt](#fare_transfer_rulestxt) | Optional | Fare rules for transfers between legs of travel.

Along with [fare_leg_rules.txt](#fare_leg_rulestxt), file [fare_transfer_rules.txt](#fare_transfer_rulestxt) provides a more detailed method for modeling fare structures. As such, the use of [fare_transfer_rules.txt](#fare_transfer_rulestxt) is entirely separate from files [fare_attributes.txt](#fare_attributestxt) and [fare_rules.txt](#fare_rulestxt). | @@ -308,7 +309,7 @@ File: **Optional** Primary key (`fare_id`) **Versions**
-There are two modelling options for describing fares. GTFS-Fares V1 is the legacy option for describing minimal fare information. GTFS-Fares V2 is an updated method that allows for a more detailed account of an agency's fare structure. Both are allowed to be present in a dataset, but only one method should be used by a data consumer for a given dataset. It is recommended that GTFS-Fares V2 takes precedence over GTFS-Fares V1.

The files associated with GTFS-Fares V1 are:
- [fare_attributes.txt](#fare_attributestxt)
- [fare_rules.txt](#fare_rulestxt)

The files associated with GTFS-Fares V2 are:
- [fare_products.txt](#fare_productstxt)
- [fare_leg_rules.txt](#fare_leg_rulestxt)
- [fare_transfer_rules.txt](#fare_transfer_rulestxt) +There are two modelling options for describing fares. GTFS-Fares V1 is the legacy option for describing minimal fare information. GTFS-Fares V2 is an updated method that allows for a more detailed account of an agency's fare structure. Both are allowed to be present in a dataset, but only one method should be used by a data consumer for a given dataset. It is recommended that GTFS-Fares V2 takes precedence over GTFS-Fares V1.

The files associated with GTFS-Fares V1 are:
- [fare_attributes.txt](#fare_attributestxt)
- [fare_rules.txt](#fare_rulestxt)

The files associated with GTFS-Fares V2 are:
- [fare_containers.txt](#fare_containerstxt)
- [fare_products.txt](#fare_productstxt)
- [fare_leg_rules.txt](#fare_leg_rulestxt)
- [fare_transfer_rules.txt](#fare_transfer_rulestxt)