Transit

Changes to GTFS-realtime

Introduction

The GTFS-realtime specification is not set in stone. Instead, it is an open specification developed and maintained by the community of transit agencies, developers, and other stakeholders who use GTFS-realtime. It is expected that this community of producers and consumers of GTFS-realtime data will have proposals for extending the spec to enable new capabilities. To help manage that process, the following procedures and guidelines have been established.

The general outline for changing the spec has a couple of steps:

  1. Propose a change on the GTFS-realtime discussion list.
  2. Receive comments and feedback from the GTFS-realtime community and iterate on the proposed change.
  3. Find at least one GTFS-realtime producer and one consumer to implement and test the proposed change.
  4. Submit a final request-for-comments on the proposed change to the discussion list. If no outstanding issues are identified after one week’s time, the proposal will be officially adopted.

The discussion group will serve as the primary place for suggesting changes to the spec, such that users of GTFS-realtime can learn about and offer feedback on proposed changes. If the community generally agrees that the proposal is worthwhile and follows the GTFS-realtime guiding principles outlined below, it will be officially added to the spec. We also require that any proposed change be implemented by at least one GTFS-realtime producer and one consumer, in order to verify the feasibility of that change in practice.

Guiding Principles

In order to preserve the original vision of GTFS-realtime, a number of guiding principles have been established to take into consideration when extending the spec:

Feeds should be efficient to produce and consume in realtime.

Realtime information is a continuous, dynamic stream of data that necessarily requires efficient processing. We chose Protocol Buffers as the basis for the specification because they offer a good trade-off in terms of ease of use for developers and in terms of efficiency for transmitting data. Unlike GTFS, we do not imagine many agencies will be editing GTFS-realtime feeds by hand. The choice of Protocol Buffers reflects the conclusion that most GTFS-realtime feeds will be produced and consumed programmatically.

The spec is about passenger information.

Like GTFS before it, GTFS-realtime is primarily concerned with passenger information. That is, the spec should include information that can help power tools for riders, first and foremost. There is potentially a large amount of operations-oriented information that transit agencies might want to transmit internally between systems. GTFS-realtime is not intended for that purpose and there are potentially other operations-oriented data-standards that may be more appropriate.

Changes to the spec should be backwards-compatible.

When adding features to the specification, we want to avoid making changes that will make existing feeds invalid. We don't want to create more work for existing feed publishers until they want to add capabilities to their feeds. Also, whenever possible, we want existing parsers to be able to continue to read the older parts of newer feeds. The conventions for extending Protocol Buffers will enforce backwards-compatibility to a certain extent. However, we wish to avoid semantic changes to existing fields that might break backwards-compatibility as well.

Speculative features are discouraged.

Every new feature adds complexity to creating and reading of feeds. Therefore, we want to take care to only add features that we know to be useful. Ideally, any proposal will have been tested by generating data for a real transit system that uses the new feature and writing software to read and display it.

We will make use of extensions, described in the following section, to support new features. GTFS-realtime producers and consumers can first test a new feature in the extension space. When the feature is ready for official adoption, we will add the feature to the official GTFS-realtime proto definition itself.

Extensions

To facilitate the testing of new features and to allow developers to add extra information to a GTFS-realtime feed, we will take advantage of the Extensions feature of Protocol Buffers. Extensions allow us to define a namespace in a Protocol Buffer message where third-party developers can define additional fields without the need to modify the original proto definition.

When a developer is interested in extending the GTFS-realtime spec, they should contact the GTFS-realtime discussion group and we will assign them the next available extension id, picked incrementally from a list of numbers starting at 1000 and going up and documented in the Extension Registry section found below.

These assigned extension ids corresponds to the tag ids available in the "extension" namespace for each GTFS-realtime message definition. Now that the developer has an assigned extension id, they will use that id when extending any and all GTFS-realtime messages. Even if the developer only plans to extend a single message, the assigned extension id will be reserved for ALL messages.

For a developer extending the spec, instead of adding a single field like a "string" or "int32" with their extension id, the preferred model is to define a new message like "MyTripDescriptorExtension", extend the underlying GTFS-realtime message with your new message, and then put all your new fields in there. This has the nice property that you can manage fields within your extension message however you want, without needing to reserve a new extension id from the master list.

message MyTripDescriptorExtension {
  optional string some_string = 1;
  optional bool some_bool = 2;
  ...
}
extend transit_realtime.TripDescriptor {
  optional MyTripDescriptorExtension my_trip_descriptor = YOUR_EXTENSION_ID;
}
  

Extension Registry

Extension ID Developer Contact Details
1000 OneBusAway onebusaway-developers https://github.com/OneBusAway/onebusaway/wiki/GTFS-Realtime-Resources
1001 New York City MTA mtadeveloperresources http://mta.info/developers/
1002 Google transit-realtime-partner-support@google.com Google Maps Live Transit Updates
1003 OVapi gtfs-rt at ovapi.nl http://gtfs.ovapi.nl
...

Revision History

Oct 12, 2012

May 30, 2012

  • Added specific details about Extensions to the specification.

November 30, 2011

  • Added Protocol Buffer extension namespace to key GTFS-realtime messages to facilitate writing extensions to the spec.

October 25, 2011

  • Updated documentation to clarify that alert header_text and description_text are both plain-text values.

August 20, 2011

  • Updated documentation to clarify semantics of the TimeRange message.

August 22, 2011

  • Initial version.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.