Skip to content

Commit

Permalink
Add Components section (#285)
Browse files Browse the repository at this point in the history 
Adds new files for each component and fixes nav
  • Loading branch information
@Sergiodero
Sergiodero authored Jan 19, 2024
1 parent 4fe16b2 commit f70e6fd
Show file tree
Hide file tree
Showing 15 changed files with 687 additions and 13 deletions.
1 change: 1 addition & 0 deletions .idea/.name
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

15 changes: 5 additions & 10 deletions docs/schedule/best-practices.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -255,13 +255,12 @@ Working Group members voted on each Best Practice. Most Best Practices were appr

### Why not just change the GTFS reference?

Good question! The process of examining the Specification, data usage and needs did indeed trigger some changes to the Specification (see [closed pull requests in GitHub](https://github.com/google/transit/pulls?q=is%3Apr+is%3Aclosed)). Specification reference amendments are subject to a higher bar of scrutiny and comment than the Best Practices. However, there was still need to agree on a clear set of Best Practice recommendations.
Good question! The process of examining the Specification, data usage and needs did indeed trigger some changes to the Specification (see [closed pull requests in GitHub](https://github.com/google/transit/pulls?q=is%3Apr+is%3Aclosed)).
Specification reference amendments are subject to a higher bar of scrutiny and comment than the Best Practices. Certain Best Practices are being merged into the spec based on their level of adoption and community consensus. Eventually, all GTFS Best Practices could become part of the core GTFS Reference.

The working group anticipates that some GTFS Best Practices will eventually become part of the core GTFS reference.
### How to check for conformance with these Best Practices?

### Do GTFS validator tools check for conformance with these Best Practices?

No validator tool currently checks for conformance with all Best Practices. Various validator tools check for conformance with some of these best practices. For a list of GTFS validator tools, see [GTFS Validators](https://github.com/CUTR-at-USF/awesome-transit#gtfs-validators). If you write a GTFS validator tool that references these Best Practices, please email [[email protected]](mailto:[email protected]).
The Canonical GTFS Schedule Validator checks for compliance against these Best Practices. You can find more about this validation tool on the [validate page](https://gtfs.org/schedule/validate/).

### I represent a transit agency. What steps can I take so that our software service providers and vendors follow these Best Practices?

Expand All @@ -271,10 +270,6 @@ Refer your vendor or software service provider to these Best Practices. We recom

Identify the contact for the feed, using the [proposed feed\_contact\_email or feed\_contact\_url](https://github.com/google/transit/pull/31/files) fields in *feed_info.txt* if they exist, or looking up contact information on the transit agency or feed producer website. When communicating the issue to the feed producer, link to the specific GTFS Best Practice under discussion. (See ["Linking to this Document"](#linking-to-this-document)).

### I would like to propose a modification/addition to the Best Practices. How do I do this?

Email [[email protected]](mailto:[email protected]) or open an issue or pull request in the [GitHub GTFS Best Practices repo](https://github.com/rocky-mountain-institute/gtfs-best-practices).

### How do I get involved?

Email [[email protected]](mailto:[email protected]).
Expand All @@ -292,7 +287,7 @@ The objectives of maintaining GTFS Best Practices is to:

### How to propose or amend published GTFS Best Practices

GTFS applications and practice evolve, and so this document may need to be amended from time to time. To propose an amendment to this document, open a pull request [in the GTFS Best Practices GitHub repository](https://github.com/MobilityData/gtfs-best-practices) and advocate for the change. You can slo email any comments to [[email protected]](mailto:[email protected]).
The Best Practices are in the process of being merged into the spec. If you'd like to suggest a new best practice, please go to the [GTFS Reference GitHub repository](https://github.com/google/transit/) to open an issue or create a PR, or contact [[email protected]](mailto:[email protected]).

### Linking to This Document

Expand Down
74 changes: 74 additions & 0 deletions docs/schedule/components/accesibility.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Accessibility Component
The Accessibility Component of GTFS contains multiple functionalities to provide information that helps end users navigate and access public transit services. Some of these features can be used to communicate the name and color of a route, making it easier to identify; confirming whether or not a trip and a station are wheelchair accessible, helping users choose the most adequate route; and providing translations in multiple languages, among other things.

## Text-to-speech

<div class="grid" markdown>

This feature allows to provide the necessary inputs to convert text into audio, making it possible to communicate transit information, such as stop names, in a more inclusive format.

| Files associated | [stops.txt](/schedule/reference/#stopstxt) |
|-----------------------|---------------|
| **Fields associated** | tts_stop_name |

</div>

## Wheelchair accessibility

<div class="grid" markdown>

This feature makes it possible to indicate if a stop and/or vehicle can accommodate users using wheelchairs, allowing them to plan their trips based on the most convenient option for their needs.

| Files associated | [stops.txt](/schedule/reference/#stopstxt) | [trips.txt](/schedule/reference/#tripstxt) |
|-----------------------|---------------------|-----------------------|
| **Fields associated** | wheelchair_boarding | wheelchair_accessible |

</div>

## Route Colors

<div class="grid" markdown>

This feature allows to accurately depict and communicate the color scheme assigned to specific routes by the agency’s design guidelines, this enables users to easily identify transit services by their official color.

| Files associated | [routes.txt](/schedule/reference/#routestxt) |
|-----------------------|---------------------------------|
| **Fields associated** | route_color<br>route_text_color |

</div>

## Bike Allowed

<div class="grid" markdown>

This feature allows to indicate if vehicles providing service on a specific trip are able to accommodate bicycles or not, helping users to plan and access services that enable them to make multimodal trips.

| Files associated | [trips.txt](/schedule/reference/#tripstxt) |
|-----------------------|---------------|
| **Fields associated** | bikes_allowed |

</div>

## Translations

<div class="grid" markdown>

This feature allows service information such as station names to be provided in multiple languages enabling travel planners to display the information in a specific language depending on the user’s language and location settings.

| Files associated | [translations.txt](/schedule/reference/#translationstxt) |
|-----------------------|--------------------------------------------------------------------------------------------------|
| **Fields associated** | table_name<br>field_name<br>language<br>translation<br>record_id<br>record_sub_id<br>field_value |

</div>

## Headsigns

<div class="grid" markdown>

This feature allows to communicate the signage used by vehicles indicating the trip’s destination, making it easier for users to identify the correct transit service. This feature supports headsign changes along a specific route.

| Files associated | [trips.txt](/schedule/reference/#tripstxt) | [stop_times.txt](/schedule/reference/#stop_timestxt) |
|-----------------------|---------------|----------------|
| **Fields associated** | trip_headsign | stop_headsign |

</div>
72 changes: 72 additions & 0 deletions docs/schedule/components/base.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Base component
The features included in this component provide the most basic and essential elements that a GTFS needs to represent a transit service. This includes entries for each individual trip, stop, arrival and departure times and service days among many other important pieces of information. Since all of the features included in the base component are essential to enable a working GTFS feed, all these features should be implemented together.

## Agency

<div class="grid" markdown>

This feature contains basic information regarding the agencies in charge of the transit service, including their name, website URL, and the language and timezone in which the service operates among other information. This allows to match specific services with their own corresponding agency.

| Files associated | [Agency.txt](/schedule/reference/#agencytxt) |
|-----------------------|----------------------------------------------------------------------------------------------------------------|
| **Fields associated** | agency_name<br>agency_url<br>agency_timezone<br>agency_lang<br>agency_phone<br>agency_fare_url<br>agency_email |

</div>

## Stops

<div class="grid" markdown>
This feature allows to represent the basic information elements used to identify where a transit service can be accessed, this could be a metro station or a bus stop. Geographical coordinates are used by this feature to locate the stop or station in a map, while defining a specific ID and name so that it could be identified easily, along with other complementary information.


| Files associated | [stops.txt](/schedule/reference/#stopstxt) |
|-----------------------|----------------------------------------------------------------------------------------------------------------------|
| **Fields associated** | stop_id<br>stop_code<br>stop_name<br>stop_desc<br>stop_lat<br>stop_lon<br>stop_url<br>stop_timezone<br>platform_code |

</div>

## Routes

<div class="grid" markdown>
This feature helps define the elements that identify a transit route, including its name, description and the type of service that is being represented (such as a bus, a subway or metro, ferry, etc.).

| Files associated | [routes.txt](/schedule/reference/#routestxt) |
|-----------------------|---------------------------------------------------------------------------------------------------------------------------|
| **Fields associated** | route_id<br>agency_id<br>route_desc<br>route_type<br>route_url<br>route_sort_order<br>route_short_name<br>route_long_name |

</div>

## Stop Times

<div class="grid" markdown>
This feature is used to represent the arrival and departure times at each stop, allowing users to know precisely at what time the bus, train or ferry is arriving and departing a specific location.

| Files associated | [stop_times.txt](/schedule/reference/#stop_timestxt) |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| **Fields associated** | trip_id<br>arrival_time<br>departure_time<br>stop_id<br>stop_sequence<br>pickup_type<br>drop_off_type<br>shape_dist_traveled<br>timepoint |

</div>

## Service dates

<div class="grid" markdown>
This feature helps create the structure required to schedule trips, as well as creating service exemptions such as holidays and other special services on specific dates.


| Files associated | [calendar.txt](/schedule/reference/#calendartxt) | [calendar_dates.txt](/schedule/reference/#calendar_datestxt) |
|-----------------------|--------------------------------------------------------------------------------------------------------------------|--------------------------------------|
| **Fields associated** | service_id<br>monday<br>tuesday<br>wednesday<br>thursday<br>friday<br>saturday<br>sunday<br>start_date<br>end_date | service_id<br>date<br>exception_type |

</div>

## Trips

<div class="grid" markdown>
This feature brings together the main elements of the Base component of GTFS, making it possible to model transit services, by creating individual trips and associating them with their corresponding routes, stops and service dates.


| Files associated | [trips.txt](/schedule/reference/#tripstxt) |
|-----------------------|----------------------------------------------------------------------------------|
| **Fields associated** | route_id<br>service_id<br>trip_id<br>trip_short_name<br>direction_id<br>block_id |

</div>
86 changes: 86 additions & 0 deletions docs/schedule/components/fares.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
# Fares Component
The Fares component includes multiple features that allow to precisely describe a wide variety of pricing structures and payment methods used by different transit agencies around the world, such as zone-based fares and reloadable prepaid cards. This helps users know the correct price applicable to their trip.

## Fare Products

<div class="grid" markdown>

This feature is used to list the types of tickets or fares (i.e. single-trip fare, Monthly pass, etc.) offered by a transit agency that can be purchased by riders to access a service, defining their name, price and currency. This feature acts as the base to implement all other functionalities associated with fares (except for Fares v1).

| Files associated | [fare_products.txt](/schedule/reference/#fare_productstxt) | [fare_leg_rules.txt](/schedule/reference/#fare_leg_rulestxt) |
|-----------------------|-----------------------------------------------------------------------------|--------------------|
| **Fields associated** | fare_product_id<br>fare_product_name<br>amount<br>currency<br>fare_media_id | fare_product_id |

</div>

## Fare Media

<div class="grid" markdown>

This feature helps define the supported media that can be used to hold and/or validate a fare product. This refers to physical or virtual containers such as a paper ticket, a rechargeable transit card or even contactless payment with credit cards or smartphones.

| Files associated | [fare_media.txt](/schedule/reference/#fare_mediatxt) | [fare_products.txt](/schedule/reference/#fare_productstxt) |
|-----------------------|-----------------------------------------------------|-------------------|
| **Fields associated** | fare_media_id<br>fare_media_name<br>fare_media_type | fare_media_id |

</div>

## Route-Based Fares

<div class="grid" markdown>

This feature allows to describe rules used to apply different fares for specific groups of routes, such as special fares for express services or differentiating fares between a BRT service versus traditional bus services.

| Files associated | [routes.txt](/schedule/reference/#routestxt) | [fare_leg_rules.txt](/schedule/reference/#fare_leg_rulestxt) | [netowrks.txt](/schedule/reference/#networkstxt) | [route_networks.txt](/schedule/reference/#route_networkstxt) |
|-----------------------|------------|-------------------------------|----------------------------|------------------------|
| **Fields associated** | network_id | fare_product_id<br>network_id | network_id<br>network_name | network_id<br>route_id |

</div>

## Time-Based Fares

<div class="grid" markdown>

This feature can be used to create rules that are useful to represent fares differentiated based on the time of the day or the day of the week, such as peak and off-peak fares and/or weekend fares.

| Files associated | [fare_leg_rules.txt](/schedule/reference/#fare_leg_rulestxt) | [timeframes.txt](/schedule/reference/#timeframestxt) |
|-----------------------|---------------------------------------------------------------------|------------------------------------------------------------|
| **Fields associated** | fare_product_id<br>from_timeframe_group_id<br>to_timeframe_group_id | timeframe_group_id<br>start_time<br>end_time<br>service_id |

</div>

## Zone-Based Fares

<div class="grid" markdown>

This feature allows to define rules that enable fares differentiated when traveling from a specific group of stops to another. This can be useful to represent zone-based systems where a specific fare applies when traveling from one particular zone to another.

| Files associated | [fare_leg_rules.txt](/schedule/reference/#fare_leg_rulestxt) | [areas.txt](/schedule/reference/#areastxt) | [stop_areas.txt](/schedule/reference/#stop_areastxt) |
|-----------------------|-----------------------------------------------|----------------------|--------------------|
| **Fields associated** | fare_product_id<br>from_area_id<br>to_area_id | area_id<br>area_name | area_id<br>stop_id |

</div>

## Transfer Fares

<div class="grid" markdown>

This feature allows to define rules applicable when transferring from one leg of the trip to another, this is helpful to correctly model the cost of a multi leg trip especially when a special transfer policy is used such as free transfers for a specific time limit or applying fare discounts to the second leg of the trip.

| Files associated | [fare_leg_rules.txt](/schedule/reference/#fare_leg_rulestxt) | [fare_transfer_rules.txt](/schedule/reference/#fare_transfer_rulestxt) |
|-----------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| **Fields associated** | leg_group_id | from_leg_group_id<br>to_leg_group_id<br>transfer_count<br>duration_limit<br>duration_limit_type<br>fare_transfer_type<br>fare_product_id |

</div>

## Fares V1

<div class="grid" markdown>

This feature is a legacy alternative to other Fares Features that allows to model simpler fare information including fare pricing, payment methods and transfers and zone-based fares. While simpler to produce, its capacity to adapt to more complex fare structures is more limited compared to using the rest of the Fares features, thus their is preferred over Fares V1.

| Files associated | [stops.txt](/schedule/reference/#stopstxt) | [fare_attributes.txt](/schedule/reference/#fare_attributestxt) | [fare_rules.txt](/schedule/reference/#fare_rulestxt) |
|-----------------------|-----------|----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| **Fields associated** | zone_id | fare_id<br>price<br>currency_type<br>payment_method<br>transfers<br>agency_id<br>transfer_duration | fare_id<br>route_id<br>origin_id<br>destination_id<br>contains_id |

</div>
14 changes: 14 additions & 0 deletions docs/schedule/components/flexible_services.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Flexible services Component
This component contains features that make it possible to communicate service information for flexible services with special operations that might not follow the common behavior of scheduled and/or fixed services.

## Continuous stops

<div class="grid" markdown>

This feature makes it possible to indicate if a rider can be picked up and/or dropped off between scheduled stops all along the route or on specific sections of it.

| Files associated | [stop_times.txt](/schedule/reference/#stop_timestxt) | [routes.txt](/schedule/reference/#routestxt) |
|-----------------------|------------------------------------------|------------------------------------------|
| **Fields associated** | continuous_pickup<br>continuous_drop_off | continuous_pickup<br>continuous_drop_off |

</div>
Loading

0 comments on commit f70e6fd

Please sign in to comment.