コンテンツにスキップ

GTFS Realtimeに新しいフィールドを追加

GTFS Realtime 仕様に新しいフィールドを追加したい場合、GTFS Realtime GitHub リポジトリに新しいイシューを登録し、GTFS Realtime メーリングリストにそのフィールドを発表します（イシューへのリンクも含む）。

仕様の修正プロセス

  1. プロトコル定義、仕様書、ドキュメントファイルの関連部分をすべて更新したgitブランチを作成する(翻訳を除く)。
  2. https://github.com/google/transit にプルリクエストを作成します。プルリクエストには、パッチの拡張説明を含める必要があります。プルリクエストの作成者は、支持者になります。
  3. プルリクエストが登録されたら、その支持者がGTFS Realtime メーリングリストにアナウンスする必要があります。発表されたプルリクエストは、プロポーザルとみなされます。
  4. 提案の議論は以下の通りです。プルリクエストコメントを唯一の議論の場として使用する。
    • 議論は提唱者が必要と感じる限り続きますが、少なくとも7暦日以上でなければなりません。
    • 提案者は、自分が同意したコメントに基づいて、提案 (すなわちプルリクエスト) を適時に更新する責任があります。
    • 提唱者は、いかなる時点でも提案の放棄を主張することができます。
  5. 提唱者は、議論に必要な最初の7日間の間隔が経過した後のどの時点でも、提案のバージョンに対する投票を要求することができます。
    • 投票を呼びかける前に、少なくとも1つのGTFS-realtime生成者と1つのGTFS-realtime消費者が、提案された変更を実装する必要があります。GTFS-realtime・プロデューサーは、その変更を公衆向けのGTFS-realtime・フィードに含め、そのデータへのリンクをプル・リクエスト・コメントに記載することが期待されます。また、GTFS-realtime・コンシューマーは、その変更を自明ではない方法で利用している（すなわち、新機能または改良機能をサポートしている）アプリケーションへのリンクをプル・リクエスト・コメントに記載することが期待されています。
    • 投票を呼びかける場合、支持者はその投票が仕様への正式採用のためのものなのか、 それとも実験的な分野のためのものなのかを明確に示すべきである。
  6. 投票は暦日で7日間、スイスの営業日で5日間の最小限の期間で行われる。投票は 23:59:59 UTC に終了する。
    • 提唱者は投票の開始時に具体的な終了時刻をアナウンスする必要があります。
    • 投票期間中は、提案の編集上の変更のみが許されます (誤字脱字、意味を変えない限り文言の変更は可能です)。
    • 誰でもプルリクエストにコメントする形で賛成・反対を投票することができ、投票期間の終了まで投票を変更することができます。 投票者が投票を変更する場合、元の投票コメントを取り消し、新しい投票を書き込むことで更新することが推奨されます。
    • 投票期間開始前の投票は考慮されません。
  7. 提案は、少なくとも3票を投じて全会一致の賛成が得られた場合に受理されます。
    • 提案者の票は3票の合計にカウントされません。例えば、提案者 X がプルリクエストを作成して賛成票を投じ、ユーザ Y と Z が賛成票を投じた場合、合計で 2 票の賛成票としてカウントされます。
    • 反対票は動機付けされたものでなければならず、理想的には実行可能なフィードバックを提供するものでなければなりません。
    • 投票が失敗した場合、支持者はその提案の作業を継続するか、あるいはその提案を放棄するかを選ぶことができます。 提唱者のいずれの決定も、メーリングリストにおいて発表されなければなりません。
    • もし支持者が提案の作業を継続するのであれば、いつでも新しい投票を呼びかけることができる。
  8. プルリクエストが30日間アクティブでない場合、プルリクエストはクローズされます。プルリクエストが閉じられると、対応するプロポーザルは放棄されたものとみなされます。提唱者は、会話を継続または維持したい場合、いつでもプルリクエストを再開することができます。
    • なお、提唱者は、その機能を公式仕様の一部ではなく、カスタム拡張機能として実装することを選択することができます。
  9. 提案が受け入れられたら
    • Google は、投票されたバージョンのプルリクエストをマージし、5 営業日以内に実行することを約束します (ただし、貢献者がCLA に署名していることが条件です)。
    • Googleは、https://github.com/google/gtfs-realtime-bindingsリポジトリを適時に更新することを約束します。提案の結果である gtfs-realtime-bindings へのコミットは、提案のプルリクエストを参照する必要があります。
    • 翻訳を元のプルリクエストに含めてはいけません。 Google は最終的に関連する翻訳をサポート言語に更新する責任がありますが、コミュニティからの純粋な翻訳プルリクエストは歓迎され、すべての編集コメントが対処され次第、受理されるでしょう。

実験的分野

  1. コミュニティが (a) 提案されたフィールドは有用であると判断し、(b) フィールドのタイプ (optional repeated、string intかbool か) について合意できれば、GTFS Realtime メッセージでフィールド番号を割り当て、.proto ファイルとドキュメントに、これは将来的に変わるかもしれない実験的フィールドである旨を記述します。
    • 合意形成は、以下の仕様書修正プロセスと同じように、議論と投票によって行われます。ただし、全会一致ではなく、80%の賛成票のみで承認されます。
    • 新しい実験的フィールドを使用したいGTFS Realtime プロデューサーとコンシューマーは、新しいフィールドを含む .proto ファイルを使用してライブラリを再作成し（例えば、Google はgtfs-realtime-bindings ライブラリを更新します）、ライブデータでフィールドの入力とパージングを開始します。
    • 実験的なフィールドに価値があり、生産者と消費者の両方がそのフィールドを使用していることが確認されたら、以下の仕様修正プロセスに従って、そのフィールドを仕様に正式に追加する予定です。
    • 実験 的フィールドとして承認されてから2年以内に仕様修正プロセスによって実験的フィールドが採用されない場合、.protoファイルファイルのフィールド値の横に[deprecated=true]を追加して非推奨とします。 RESERVEDの代わりに）[deprecated=true]を使うことで、すでにそのフィールドを採用している生産者と消費者は、使用からそれを削除する必要がありません。 さらに、仕様の修正プロセスに続く投票において承認されれば、そのフィールドは将来的に「非推奨」になる可能性がある（たとえば、追加の生産者や消費者がそのフィールドを使い始める場合など）。
  2. 新しいフィールドが単一の製作者に特有であると考えられる場合、またはデータ型に関して論争がある場合は、製作者にカスタム拡張を割り当てて、そのフィールドを独自のフィードで使用できるようにします。 可能な限り、拡張機能を避け、多くの機関に有用なフィールドをメイン仕様に追加することで、仕様の断片化や、消費者がさまざまな拡張機能をサポートするための余分な作業を回避することが望まれます。

指導方針

GTFS Realtime の本来の姿を維持するために、仕様を拡張する際に考慮すべき指針がいくつかあります。


フィードは、リアルタイムに生成、消費するのが効率的であるべきです。

リアルタイム情報は、連続的でダイナミックなデータの流れであり、効率的な処理が必要です。プロトコルバッファを仕様のベースとしたのは、開発者の使いやすさとデータ伝送の効率という点でトレードオフの関係にあるためです。GTFSとは異なり、多くの機関がGTFS-realtimeードを手作業で編集することは想定していません。プロトコルバッファは、GTFS-realtimeードをプログラムで生成し、消費することを想定しています。


この仕様は、旅客情報についてのものです。

GTFSのように、GTFS Realtime は乗客の情報を扱うものです。つまり、ライダーのためのパワーツールに役立つ情報が、まず第一に仕様に含まれるべきです。運輸機関では、システム間で内部的に送信したい運用に適した情報が大量にある可能性があります。GTFS Realtimeはそのような目的ではありませんし、他のオペレーション指向のデータ規格の方が適している可能性もあります。


仕様の変更は、後方互換性を保つ必要があります。

仕様の変更に際して、既存のフィードを無効にしてしまうような変更は避けたいと思います。既存のフィード発行者が自分のフィードに機能を追加したくなるまで、作業を増やしたくありません。また、可能な限り、既存のパーサーが新しいフィードの古い部分を読み続けられるようにしたいと思います。Protocol Bufferを拡張するための規約は、ある程度の後方互換性を強制することになります。しかし、既存のフィールドの意味的な変更によって後方互換性が損なわれることは避けたいと思います。


投機的な機能は推奨されません。

新しい機能を追加するたびに、フィードの作成と読み込みが複雑になる。したがって、有用であることが分かっている機能のみを追加するように注意したい。理想的には、どのような提案であっても、その新機能を使用する実際の交通システムのデータを生成し、それを読み込んで表示するソフトウェアを作成することによって、テストされていることが望ましい。

改訂履歴

2020年3月12日

  • GTFS RealtimeのリファレンスページのTripDescriptorの説明を更新しました。

2015年2月26日（木

  • TripDescriptorに実験的なフィールドdirection_idを追加した[(議論)](https://groups.google.com/d/msg/gtfs-realtime/b8N2GGd2TBs/0fJ1IOMTjJ0J）。

2015年1月30日（木

  • Protocol Buffer拡張名前空間を、まだ持っていない残りのGTFS-realtimeメッセージ（FeedMessage や FeedEntity）などすべてに追加しました。

2015年1月28日（木

  • TripUpdateに実験的なフィールドdelayを追加した(議論)。

2015年1月16日（木

  • TripDescriptor.start_timeの説明を更新しました。

2015年1月8日（木

  • 実験的な enumOccupancyStatus を定義しました。
  • VehiclePositionに実験的なフィールドoccupancy_statusを追加した（議論）。

2014年5月22日（木

  • StopTimeUpdateメッセージのScheduleRelationshipenumの記述を更新しました(審議)。
  • TripDescriptorメッセージのScheduleRelationshipenum値からREPLACEMENTを削除しました（審議）。

2012年10月12日

  • TripUpdateメッセージにtimestampフィールドを追加しました。

2012年5月30日

  • 拡張機能の具体的な内容を仕様に追加しました。

2011年11月30日

  • GTFS-Realtimeの主要メッセージにProtocol Buffer拡張名前空間を追加し、仕様の拡張を書きやすくした。

2011年10月25日

  • alert、header_text、description_textがともにプレーンテキスト値であることを明確にするため、ドキュメントを更新しました。

2011年8月20日（木

  • TimeRangeメッセージのセマンティクスを明確にするためにドキュメントを更新しました。

2011年8月22日

  • 初期バージョン。