├── .github
├── dependabot.yml
└── workflows
│ ├── check_website_returns_200_OK.yaml
│ ├── lint.yml
│ ├── update-requirements.yaml
│ └── update_website_contents_on_server.yml
├── .gitignore
├── .markdownlint.yaml
├── .pre-commit-config.yaml
├── CITATION
├── LICENSE
├── LICENSE-APACHE-2.0
├── LICENSE-CC-BY-4.0
├── Makefile
├── README.md
├── config
└── en
│ └── mkdocs.yml
├── docs
└── en
│ ├── about
│ ├── about.md
│ ├── attribution.md
│ ├── contributors.md
│ └── spec-development.md
│ ├── governance
│ ├── actions.md
│ ├── board-meetings.md
│ ├── contributor-meetings.md
│ ├── governance.md
│ └── policies
│ │ ├── CLA.md
│ │ ├── board-composition.md
│ │ ├── board-decisionmaking.md
│ │ ├── change-management-versioning.md
│ │ ├── code-of-conduct.md
│ │ └── repository-organization-access.md
│ ├── index.md
│ ├── resources
│ ├── faq.md
│ ├── implementation-guide.md
│ └── resources.md
│ └── spec
│ ├── examples.md
│ ├── examples
│ ├── mid-trip-relief-diagram.png
│ └── single-run-diagram.png
│ ├── index.md
│ └── revision-history.md
├── mlc_config.json
├── overrides
└── assets
│ ├── images
│ ├── favicon.ico
│ └── ods-small-eggshell.png
│ └── stylesheets
│ └── ods.css
└── requirements.txt
/.github/dependabot.yml:
--------------------------------------------------------------------------------
1 | version: 2
2 | updates:
3 | - package-ecosystem: "pip"
4 | directory: "/" # Adjust this if requirements.txt is in a subfolder
5 | schedule:
6 | interval: "weekly" # You can also use "daily", "monthly", or "live"
7 | allow:
8 | - dependency-type: "direct"
9 | open-pull-requests-limit: 2
10 |
--------------------------------------------------------------------------------
/.github/workflows/check_website_returns_200_OK.yaml:
--------------------------------------------------------------------------------
1 | name: Check Website returns 200 OK
2 |
3 | on:
4 | workflow_dispatch:
5 | workflow_run:
6 | workflows:
7 | - Update website on server
8 | types:
9 | - completed
10 |
11 | jobs:
12 | validate:
13 | runs-on: ubuntu-latest
14 | steps:
15 | - name: Wait for 5 minutes
16 | run: sleep 300
17 |
18 | - name: Check HTTP Status Code
19 | run: |
20 | STATUS_CODE=$(curl -s -o /dev/null -w "%{http_code}" https://tods-transit.org/ )
21 | if [ "$STATUS_CODE" -ne 200 ]; then
22 | echo "Error: Website returned status code $STATUS_CODE"
23 | exit 1
24 | fi
25 | echo "Website is up and returned 200"
26 |
--------------------------------------------------------------------------------
/.github/workflows/lint.yml:
--------------------------------------------------------------------------------
1 | name: Lint and style checks
2 |
3 | on:
4 | workflow_dispatch:
5 | push:
6 | branches: [ main ]
7 | pull_request:
8 | branches: [ main ]
9 |
10 | jobs:
11 | lint:
12 | runs-on: ubuntu-latest
13 | steps:
14 | - uses: actions/checkout@v4.2.2
15 | - uses: actions/setup-python@v5.6.0
16 | - uses: pre-commit/action@v3.0.1
--------------------------------------------------------------------------------
/.github/workflows/update-requirements.yaml:
--------------------------------------------------------------------------------
1 | name: Update requirements.txt
2 |
3 | on:
4 | schedule:
5 | - cron: '0 3 1 * *' # Runs every first day of the month @ 3 AM.
6 | workflow_dispatch: # Allow manual runs
7 |
8 | jobs:
9 | update-requirements:
10 | runs-on: ubuntu-latest
11 |
12 | steps:
13 | - name: Checkout repository
14 | uses: actions/checkout@v4
15 |
16 | - name: Set up Python
17 | uses: actions/setup-python@v4
18 | with:
19 | python-version: 3.11 # Adjust to your required Python version
20 |
21 | - name: Load secrets from 1Password
22 | id: onepw_secrets
23 | uses: 1password/load-secrets-action@v2.0.0
24 | with:
25 | export-env: true # Export loaded secrets as environment variables
26 | env:
27 | OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
28 | GITHUB_TOKEN: "op://rbiv7rvkkrsdlpcrz3bmv7nmcu/GitHub generic action token for all repos/credential"
29 |
30 | - name: Create virtual environment
31 | run: |
32 | python -m venv venv
33 | source venv/bin/activate
34 | python -m pip install --upgrade pip
35 |
36 | - name: Install pur
37 | run: |
38 | source venv/bin/activate
39 | pip install pur
40 |
41 | - name: Update requirements.txt
42 | run: |
43 | source venv/bin/activate
44 | pur -r requirements.txt
45 |
46 | - name: Check for changes
47 | id: check_changes
48 | run: |
49 | if git diff --exit-code; then
50 | echo "changes=false" >> $GITHUB_ENV
51 | else
52 | echo "changes=true" >> $GITHUB_ENV
53 | fi
54 |
55 | - name: Create Branch Name
56 | id: createbranchname
57 | if: env.changes == 'true'
58 | env:
59 | GITHUB_TOKEN: ${{ env.GITHUB_TOKEN }}
60 | run: |
61 | branch_name="update-requirements-$(date +'%Y%m%d')"
62 | echo "branchname=branch_name" >> $GITHUB_ENV
63 |
64 | - name: Create Pull Request
65 | id: createpr
66 | if: env.changes == 'true'
67 | uses: peter-evans/create-pull-request@v7.0.6
68 | with:
69 | token: ${{ env.GITHUB_TOKEN }}
70 | sign-commits: true
71 | assignees: "fredericsimard"
72 | branch: ${{ env.branchname }}
73 | commit-message: 'This PR updates the `requirements.txt` file with the latest versions of dependencies.'
74 | title: 'Monthly `requirements.txt` update'
75 | body: |
76 | This PR updates the `requirements.txt` file with the latest versions of dependencies.
77 |
--------------------------------------------------------------------------------
/.github/workflows/update_website_contents_on_server.yml:
--------------------------------------------------------------------------------
1 | name: Update website on server
2 |
3 | # Controls when the action will run. Workflow runs when manually triggered using the UI or API.
4 | on:
5 | workflow_dispatch:
6 | push:
7 | branches:
8 | - main
9 | paths-ignore:
10 | - '.gitignore'
11 | - '.gitattributes'
12 | - 'LICENSE'
13 | - 'README.md'
14 | - '.github/workflows/**'
15 |
16 | # A workflow run is made up of one or more jobs that can run sequentially or in parallel
17 | jobs:
18 | build:
19 | name: Build
20 | runs-on: ubuntu-latest
21 | steps:
22 |
23 | - name: Load secrets from 1Password
24 | id: onepw_secrets
25 | uses: 1password/load-secrets-action@v2.0.0
26 | with:
27 | export-env: true # Export loaded secrets as environment variables
28 | env:
29 | OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
30 | ACTION_GXFS_WEBSERVER_SSH_HOST: "op://rbiv7rvkkrsdlpcrz3bmv7nmcu/kttdw7r3jp6rir7rtgkwk2a22q/ACTION_GXFS_WEBSERVER_SSH_HOST"
31 | ACTION_GXFS_WEBSERVER_SSH_PORT: "op://rbiv7rvkkrsdlpcrz3bmv7nmcu/kttdw7r3jp6rir7rtgkwk2a22q/ACTION_GXFS_WEBSERVER_SSH_PORT"
32 | ACTION_GXFS_WEBSERVER_SSH_USER: "op://rbiv7rvkkrsdlpcrz3bmv7nmcu/kttdw7r3jp6rir7rtgkwk2a22q/ACTION_GXFS_WEBSERVER_SSH_USER"
33 | ACTION_GXFS_WEBSERVER_SSH_PRIVATE_KEY: "op://rbiv7rvkkrsdlpcrz3bmv7nmcu/kttdw7r3jp6rir7rtgkwk2a22q/ACTION_GXFS_WEBSERVER_SSH_PRIVATE_KEY"
34 |
35 | - name: executing remote ssh commands using password
36 | uses: appleboy/ssh-action@master
37 | with:
38 | host: ${{ env.ACTION_GXFS_WEBSERVER_SSH_HOST }}
39 | username: ${{ env.ACTION_GXFS_WEBSERVER_SSH_USER }}
40 | key: ${{ env.ACTION_GXFS_WEBSERVER_SSH_PRIVATE_KEY }}
41 | port: ${{ env.ACTION_GXFS_WEBSERVER_SSH_PORT }}
42 | script: |
43 | ./tods_mobilitydata_org_webaite_updater.sh
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
2 | site/
3 | generated/
4 | node_modules
5 | venv/
--------------------------------------------------------------------------------
/.markdownlint.yaml:
--------------------------------------------------------------------------------
1 | # includes/excludes all rules by default
2 | default: true
3 |
4 | # 4-space list indentation works best with MkDocs
5 | MD007:
6 | indent: 4
7 |
8 | # Remove line length limit - no one wants to hard wrap all their paragraphs
9 | MD013: false
10 |
11 | # Remove code indent format error because it incorrectly catches admonitions
12 | MD046: false
13 |
14 | # allow duplicate sub-headings
15 | MD024: false
16 |
17 | # allow inline HTML
18 | MD033: false
19 |
20 | # throwing a false positive on the email link
21 | MD034: false
22 |
23 | # in some cases, emphasis really is more appropriate than a heading
24 | MD036: false
25 |
--------------------------------------------------------------------------------
/.pre-commit-config.yaml:
--------------------------------------------------------------------------------
1 | repos:
2 | - repo: https://github.com/pre-commit/pre-commit-hooks
3 | rev: v5.0.0
4 | hooks:
5 | - id: check-added-large-files
6 | - id: end-of-file-fixer
7 | - id: mixed-line-ending
8 | - id: requirements-txt-fixer
9 | - id: trailing-whitespace
10 | args: [--markdown-linebreak-ext=md]
11 |
12 | - repo: https://github.com/igorshubovych/markdownlint-cli
13 | rev: v0.45.0
14 | hooks:
15 | - id: markdownlint
16 |
--------------------------------------------------------------------------------
/CITATION:
--------------------------------------------------------------------------------
1 | # Citation for Operational Data Standard
2 |
3 | ## APA
4 |
5 | Operational Data Standard Working Group. (2022). Transit Operational Data Standard. Operational Data Standard Board of Directors. Retrieved from https://ods.calitp.org
6 |
7 | ## MLA
8 |
9 | Operational Data Standard Working Group. Transit Operational Data Standard. Operational Data Standard Board of Directors, 2022, https://ods.calitp.org.
10 |
11 | ## Chicago
12 |
13 | Operational Data Standard Working Group. 2022. Transit Operational Data Standard. Operational Data Standard Board of Directors. https://ods.calitp.org.
14 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | The contents of this repository are Copyright 2024 by ODS Board of Directors and licensed as follows:
2 |
3 | [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt)
4 |
5 | All code, its parameters and tests including the contents of:
6 |
7 | - `mkdocs.yml`
8 |
9 | [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/)
10 |
11 | All documentation, sample data, and the ODS Specification itself including the contents of:
12 |
13 | - `/docs`
14 | - `*README.md`
15 |
--------------------------------------------------------------------------------
/LICENSE-APACHE-2.0:
--------------------------------------------------------------------------------
1 | Apache License
2 | ==============
3 |
4 | _Version 2.0, January 2004_
5 | _<>_
6 |
7 | ### Terms and Conditions for use, reproduction, and distribution
8 |
9 | #### 1. Definitions
10 |
11 | “License” shall mean the terms and conditions for use, reproduction, and
12 | distribution as defined by Sections 1 through 9 of this document.
13 |
14 | “Licensor” shall mean the copyright owner or entity authorized by the copyright
15 | owner that is granting the License.
16 |
17 | “Legal Entity” shall mean the union of the acting entity and all other entities
18 | that control, are controlled by, or are under common control with that entity.
19 | For the purposes of this definition, “control” means **(i)** the power, direct or
20 | indirect, to cause the direction or management of such entity, whether by
21 | contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the
22 | outstanding shares, or **(iii)** beneficial ownership of such entity.
23 |
24 | “You” (or “Your”) shall mean an individual or Legal Entity exercising
25 | permissions granted by this License.
26 |
27 | “Source” form shall mean the preferred form for making modifications, including
28 | but not limited to software source code, documentation source, and configuration
29 | files.
30 |
31 | “Object” form shall mean any form resulting from mechanical transformation or
32 | translation of a Source form, including but not limited to compiled object code,
33 | generated documentation, and conversions to other media types.
34 |
35 | “Work” shall mean the work of authorship, whether in Source or Object form, made
36 | available under the License, as indicated by a copyright notice that is included
37 | in or attached to the work (an example is provided in the Appendix below).
38 |
39 | “Derivative Works” shall mean any work, whether in Source or Object form, that
40 | is based on (or derived from) the Work and for which the editorial revisions,
41 | annotations, elaborations, or other modifications represent, as a whole, an
42 | original work of authorship. For the purposes of this License, Derivative Works
43 | shall not include works that remain separable from, or merely link (or bind by
44 | name) to the interfaces of, the Work and Derivative Works thereof.
45 |
46 | “Contribution” shall mean any work of authorship, including the original version
47 | of the Work and any modifications or additions to that Work or Derivative Works
48 | thereof, that is intentionally submitted to Licensor for inclusion in the Work
49 | by the copyright owner or by an individual or Legal Entity authorized to submit
50 | on behalf of the copyright owner. For the purposes of this definition,
51 | “submitted” means any form of electronic, verbal, or written communication sent
52 | to the Licensor or its representatives, including but not limited to
53 | communication on electronic mailing lists, source code control systems, and
54 | issue tracking systems that are managed by, or on behalf of, the Licensor for
55 | the purpose of discussing and improving the Work, but excluding communication
56 | that is conspicuously marked or otherwise designated in writing by the copyright
57 | owner as “Not a Contribution.”
58 |
59 | “Contributor” shall mean Licensor and any individual or Legal Entity on behalf
60 | of whom a Contribution has been received by Licensor and subsequently
61 | incorporated within the Work.
62 |
63 | #### 2. Grant of Copyright License
64 |
65 | Subject to the terms and conditions of this License, each Contributor hereby
66 | grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
67 | irrevocable copyright license to reproduce, prepare Derivative Works of,
68 | publicly display, publicly perform, sublicense, and distribute the Work and such
69 | Derivative Works in Source or Object form.
70 |
71 | #### 3. Grant of Patent License
72 |
73 | Subject to the terms and conditions of this License, each Contributor hereby
74 | grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
75 | irrevocable (except as stated in this section) patent license to make, have
76 | made, use, offer to sell, sell, import, and otherwise transfer the Work, where
77 | such license applies only to those patent claims licensable by such Contributor
78 | that are necessarily infringed by their Contribution(s) alone or by combination
79 | of their Contribution(s) with the Work to which such Contribution(s) was
80 | submitted. If You institute patent litigation against any entity (including a
81 | cross-claim or counterclaim in a lawsuit) alleging that the Work or a
82 | Contribution incorporated within the Work constitutes direct or contributory
83 | patent infringement, then any patent licenses granted to You under this License
84 | for that Work shall terminate as of the date such litigation is filed.
85 |
86 | #### 4. Redistribution
87 |
88 | You may reproduce and distribute copies of the Work or Derivative Works thereof
89 | in any medium, with or without modifications, and in Source or Object form,
90 | provided that You meet the following conditions:
91 |
92 | * **(a)** You must give any other recipients of the Work or Derivative Works a copy of
93 | this License; and
94 | * **(b)** You must cause any modified files to carry prominent notices stating that You
95 | changed the files; and
96 | * **(c)** You must retain, in the Source form of any Derivative Works that You distribute,
97 | all copyright, patent, trademark, and attribution notices from the Source form
98 | of the Work, excluding those notices that do not pertain to any part of the
99 | Derivative Works; and
100 | * **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any
101 | Derivative Works that You distribute must include a readable copy of the
102 | attribution notices contained within such NOTICE file, excluding those notices
103 | that do not pertain to any part of the Derivative Works, in at least one of the
104 | following places: within a NOTICE text file distributed as part of the
105 | Derivative Works; within the Source form or documentation, if provided along
106 | with the Derivative Works; or, within a display generated by the Derivative
107 | Works, if and wherever such third-party notices normally appear. The contents of
108 | the NOTICE file are for informational purposes only and do not modify the
109 | License. You may add Your own attribution notices within Derivative Works that
110 | You distribute, alongside or as an addendum to the NOTICE text from the Work,
111 | provided that such additional attribution notices cannot be construed as
112 | modifying the License.
113 |
114 | You may add Your own copyright statement to Your modifications and may provide
115 | additional or different license terms and conditions for use, reproduction, or
116 | distribution of Your modifications, or for any such Derivative Works as a whole,
117 | provided Your use, reproduction, and distribution of the Work otherwise complies
118 | with the conditions stated in this License.
119 |
120 | #### 5. Submission of Contributions
121 |
122 | Unless You explicitly state otherwise, any Contribution intentionally submitted
123 | for inclusion in the Work by You to the Licensor shall be under the terms and
124 | conditions of this License, without any additional terms or conditions.
125 | Notwithstanding the above, nothing herein shall supersede or modify the terms of
126 | any separate license agreement you may have executed with Licensor regarding
127 | such Contributions.
128 |
129 | #### 6. Trademarks
130 |
131 | This License does not grant permission to use the trade names, trademarks,
132 | service marks, or product names of the Licensor, except as required for
133 | reasonable and customary use in describing the origin of the Work and
134 | reproducing the content of the NOTICE file.
135 |
136 | #### 7. Disclaimer of Warranty
137 |
138 | Unless required by applicable law or agreed to in writing, Licensor provides the
139 | Work (and each Contributor provides its Contributions) on an “AS IS” BASIS,
140 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
141 | including, without limitation, any warranties or conditions of TITLE,
142 | NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
143 | solely responsible for determining the appropriateness of using or
144 | redistributing the Work and assume any risks associated with Your exercise of
145 | permissions under this License.
146 |
147 | #### 8. Limitation of Liability
148 |
149 | In no event and under no legal theory, whether in tort (including negligence),
150 | contract, or otherwise, unless required by applicable law (such as deliberate
151 | and grossly negligent acts) or agreed to in writing, shall any Contributor be
152 | liable to You for damages, including any direct, indirect, special, incidental,
153 | or consequential damages of any character arising as a result of this License or
154 | out of the use or inability to use the Work (including but not limited to
155 | damages for loss of goodwill, work stoppage, computer failure or malfunction, or
156 | any and all other commercial damages or losses), even if such Contributor has
157 | been advised of the possibility of such damages.
158 |
159 | #### 9. Accepting Warranty or Additional Liability
160 |
161 | While redistributing the Work or Derivative Works thereof, You may choose to
162 | offer, and charge a fee for, acceptance of support, warranty, indemnity, or
163 | other liability obligations and/or rights consistent with this License. However,
164 | in accepting such obligations, You may act only on Your own behalf and on Your
165 | sole responsibility, not on behalf of any other Contributor, and only if You
166 | agree to indemnify, defend, and hold each Contributor harmless for any liability
167 | incurred by, or claims asserted against, such Contributor by reason of your
168 | accepting any such warranty or additional liability.
169 |
170 | _END OF TERMS AND CONDITIONS_
171 |
172 | ### APPENDIX: How to apply the Apache License to your work
173 |
174 | To apply the Apache License to your work, attach the following boilerplate
175 | notice, with the fields enclosed by brackets `[]` replaced with your own
176 | identifying information. (Don't include the brackets!) The text should be
177 | enclosed in the appropriate comment syntax for the file format. We also
178 | recommend that a file or class name and description of purpose be included on
179 | the same “printed page” as the copyright notice for easier identification within
180 | third-party archives.
181 |
182 | Copyright [yyyy] [name of copyright owner]
183 |
184 | Licensed under the Apache License, Version 2.0 (the "License");
185 | you may not use this file except in compliance with the License.
186 | You may obtain a copy of the License at
187 |
188 | http://www.apache.org/licenses/LICENSE-2.0
189 |
190 | Unless required by applicable law or agreed to in writing, software
191 | distributed under the License is distributed on an "AS IS" BASIS,
192 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
193 | See the License for the specific language governing permissions and
194 | limitations under the License.
195 |
196 |
--------------------------------------------------------------------------------
/LICENSE-CC-BY-4.0:
--------------------------------------------------------------------------------
1 | # Creative Commons Attribution-ShareAlike 4.0 International
2 |
3 | Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
4 |
5 | **Using Creative Commons Public Licenses**
6 |
7 | Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
8 |
9 | * __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors).
10 |
11 | * __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees).
12 |
13 | ## Creative Commons Attribution-ShareAlike 4.0 International Public License
14 |
15 | By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
16 |
17 | ### Section 1 – Definitions.
18 |
19 | a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
20 |
21 | b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
22 |
23 | c. __BY-SA Compatible License__ means a license listed at [creativecommons.org/compatiblelicenses](http://creativecommons.org/compatiblelicenses), approved by Creative Commons as essentially the equivalent of this Public License.
24 |
25 | d. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
26 |
27 | e. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
28 |
29 | f. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
30 |
31 | g. __License Elements__ means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike.
32 |
33 | h. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
34 |
35 | i. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
36 |
37 | j. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License.
38 |
39 | k. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
40 |
41 | l. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
42 |
43 | m. __You__ means the individual or entity exercising the Licensed Rights under this Public License. __Your__ has a corresponding meaning.
44 |
45 | ### Section 2 – Scope.
46 |
47 | a. ___License grant.___
48 |
49 | 1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
50 |
51 | A. reproduce and Share the Licensed Material, in whole or in part; and
52 |
53 | B. produce, reproduce, and Share Adapted Material.
54 |
55 | 2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
56 |
57 | 3. __Term.__ The term of this Public License is specified in Section 6(a).
58 |
59 | 4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
60 |
61 | 5. __Downstream recipients.__
62 |
63 | A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
64 |
65 | B. __Additional offer from the Licensor – Adapted Material.__ Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply.
66 |
67 | C. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
68 |
69 | 6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
70 |
71 | b. ___Other rights.___
72 |
73 | 1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
74 |
75 | 2. Patent and trademark rights are not licensed under this Public License.
76 |
77 | 3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.
78 |
79 | ### Section 3 – License Conditions.
80 |
81 | Your exercise of the Licensed Rights is expressly made subject to the following conditions.
82 |
83 | a. ___Attribution.___
84 |
85 | 1. If You Share the Licensed Material (including in modified form), You must:
86 |
87 | A. retain the following if it is supplied by the Licensor with the Licensed Material:
88 |
89 | i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
90 |
91 | ii. a copyright notice;
92 |
93 | iii. a notice that refers to this Public License;
94 |
95 | iv. a notice that refers to the disclaimer of warranties;
96 |
97 | v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
98 |
99 | B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
100 |
101 | C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
102 |
103 | 2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
104 |
105 | 3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
106 |
107 | b. ___ShareAlike.___
108 |
109 | In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply.
110 |
111 | 1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License.
112 |
113 | 2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material.
114 |
115 | 3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply.
116 |
117 | ### Section 4 – Sui Generis Database Rights.
118 |
119 | Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
120 |
121 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;
122 |
123 | b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and
124 |
125 | c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
126 |
127 | For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
128 |
129 | ### Section 5 – Disclaimer of Warranties and Limitation of Liability.
130 |
131 | a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__
132 |
133 | b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__
134 |
135 | c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
136 |
137 | ### Section 6 – Term and Termination.
138 |
139 | a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
140 |
141 | b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
142 |
143 | 1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
144 |
145 | 2. upon express reinstatement by the Licensor.
146 |
147 | For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
148 |
149 | c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
150 |
151 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
152 |
153 | ### Section 7 – Other Terms and Conditions.
154 |
155 | a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
156 |
157 | b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
158 |
159 | ### Section 8 – Interpretation.
160 |
161 | a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
162 |
163 | b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
164 |
165 | c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
166 |
167 | d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
168 |
169 | > Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” The text of the Creative Commons public licenses is dedicated to the public domain under the [CC0 Public Domain Dedication](https://creativecommons.org/publicdomain/zero/1.0/legalcode). Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
170 | >
171 | > Creative Commons may be contacted at creativecommons.org.
172 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | PHONY: help
2 |
3 | help: ## This help.
4 | @awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z0-9_-]+:.*?## / {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
5 |
6 | clean:
7 | rm -rf generated/
8 |
9 | serve: clean
10 | @echo "Starting MkDocs server..."
11 | @trap 'echo "Stopping MkDocs server..."; pkill -f "mkdocs serve"' SIGINT SIGTERM; \
12 | mkdocs serve -f config/en/mkdocs.yml --dev-addr 127.0.0.1:8000 --watch overrides
13 |
14 | build: clean
15 | mkdir -p generated # Ensure the folder exists
16 | mkdocs build -f config/en/mkdocs.yml --clean
17 |
18 | killserve:
19 | pkill -f "mkdocs serve"
20 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Transit Operational Data Standard
2 |
3 | The Transit Operational Data Standard (TODS) is an open standard for describing how to operate scheduled transit operations which can be used to port scheduled operations between software products (e.g. scheduling systems and CAD/AVL systems), agencies, and more. TODS leverages the existing [General Transit Feed Specification](https://gtfs.org) (GTFS) and extends it to include information about personnel and non-revenue service.
4 |
5 | Complete documentation published at:
6 |
7 | ## License to Use
8 |
9 | The TODS Specification is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) (code) and [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/) (sample data, specification, and documentation) as defined in file.
10 |
11 | ## Citation
12 |
13 | If you use the Transit Operational Data Standard in a report or article, please cite it as follows:
14 |
15 | > Transit Operational Data Standard Working Group. 2022. Transit Operational Data Standard. Transit Operational Data Standard Board of Directors. https://tods.mobilitydata.org.
16 |
17 | Additional citation styles can be found in [CITATION](CITATION).
18 |
19 | ## Building the site locally
20 |
21 | 1. In Terminal, change the directory to one where you wish to build the site.
22 | 1. Ensure you have an up-to-date version of pip:
23 | - Linux: `pip install pip` or `pip install --upgrade pip`
24 | - macOS: `pip3 install pip` or `pip3 install --upgrade pip`
25 | 1. Clone this repository:
26 | - `git clone https://github.com/MobilityData/operational-data-standard`
27 | 1. Change the directory to the cloned repository, and create & enable a Python virtual environment:
28 | - `python3 -m venv venv`
29 | - `source venv/bin/activate`
30 | 1. Have [`requirements.txt`](requirements.txt) installed:
31 | - Linux: `pip install --force-reinstall -r requirements.txt`
32 | - macOS: `pip3 install --force-reinstall -r requirements.txt`
33 | 1. To run the site locally (command defined in `MakeFile`):
34 | - `make serve`
35 | - Then you can reach the site at this address: `http://127.0.0.1:8000/`
36 | - To shut down MKdocs from serving the site: `make killserve`
37 | 1. To build the site locally only (command defined in `MakeFile`):
38 | - `make build`
39 | 1. Deactivate the Python virtual environment when done:
40 | - `deactivate`
--------------------------------------------------------------------------------
/config/en/mkdocs.yml:
--------------------------------------------------------------------------------
1 | site_name: "Transit Operational Data Standard"
2 | site_url: https://tods.mobilitydata.org/
3 | repo_url: https://github.com/MobilityData/operational-data-standard
4 | repo_name: TODS Specification
5 | docs_dir: ../../docs/en # Where to find the English markdown files
6 | site_dir: ../../generated/ # Where to put the English HTML files
7 | # edit_uri: edit/main/docs
8 |
9 | theme:
10 | name: material
11 | language: en
12 | custom_dir: ../../overrides/
13 | features:
14 | - navigation.expand
15 | - navigation.tabs
16 | - toc.integrate
17 | palette:
18 | primary: custom
19 | accent: custom
20 | text: custom
21 | background: custom
22 | highlight: custom
23 | logo: assets/images/ods-small-eggshell.png
24 | favicon: assets/images/favicon.ico
25 |
26 | plugins:
27 | - search:
28 | lang:
29 | - en
30 | - awesome-pages
31 |
32 | extra:
33 | # analytics:
34 | # provider: google
35 | # property: G-N7RXJMH84M
36 | consent:
37 | title: Cookie Consent
38 | description: >-
39 | We use cookies to track visits, stored anonymously. With your consent, you're helping us to make our documentation better. See our Privacy Policy.
40 | actions:
41 | - accept
42 | - reject
43 | - manage
44 | social:
45 | - icon: fontawesome/brands/github
46 | link: https://github.com/MobilityData
47 | - icon: fontawesome/brands/linkedin
48 | link: https://www.linkedin.com/company/mobilitydata
49 | - icon: fontawesome/brands/slack
50 | link: https://share.mobilitydata.org/slack
51 | # alternate:
52 | # - name: English
53 | # link: /
54 | # lang: en
55 |
56 | extra_javascript:
57 | - https://unpkg.com/mermaid@8.5.0/dist/mermaid.min.js
58 |
59 | extra_css:
60 | - https://use.fontawesome.com/releases/v5.13.0/css/all.css
61 | - assets/stylesheets/ods.css
62 |
63 | markdown_extensions:
64 | - admonition
65 | - codehilite:
66 | linenums: true
67 | - pymdownx.inlinehilite
68 | - pymdownx.tasklist:
69 | custom_checkbox: true
70 | - pymdownx.tabbed
71 | - pymdownx.superfences:
72 | custom_fences:
73 | - name: mermaid
74 | class: mermaid
75 | format: !!python/name:pymdownx.superfences.fence_div_format
76 | - pymdownx.smartsymbols
77 | - meta
78 | - toc:
79 | # insert a blank space before the character
80 | permalink: " ¶"
81 | - smarty
82 | - pymdownx.emoji:
83 | emoji_index: !!python/name:material.extensions.emoji.twemoji
84 | emoji_generator: !!python/name:material.extensions.emoji.to_svg
85 |
86 | nav:
87 | - Home: index.md
88 | - About:
89 | - about/about.md
90 | - Initial Specification Development Process: about/spec-development.md
91 | - Contributors: about/contributors.md
92 | - Attribution: about/attribution.md
93 | - Specification:
94 | - spec/index.md
95 | - Revision History: spec/revision-history.md
96 | - Examples: spec/examples.md
97 | - Governance:
98 | - governance/governance.md
99 | - Board Actions: governance/actions.md
100 | - Board Meetings: governance/board-meetings.md
101 | - Contributor Meetings: governance/contributor-meetings.md
102 | - Policies:
103 | - Change Management: governance/policies/change-management-versioning.md
104 | - Board Composition: governance/policies/board-composition.md
105 | - Board Decision Making: governance/policies/board-decisionmaking.md
106 | - Code of Conduct: governance/policies/code-of-conduct.md
107 | - Contributor License Agreement: governance/policies/CLA.md
108 | - Repository Access: governance/policies/repository-organization-access.md
109 | - Resources:
110 | - Handouts + Presentations: resources/resources.md
111 | - Frequently Asked Questions: resources/faq.md
112 | - Implementation Guide: resources/implementation-guide.md
113 |
114 | copyright: |
115 |
124 |
--------------------------------------------------------------------------------
/docs/en/about/about.md:
--------------------------------------------------------------------------------
1 | # About TODS
2 |
3 | The Transit Operational Data Standard ("TODS") is managed by [MobilityData](https://mobilitydata.org) serving as the [TODS Manager](../governance/governance.md#tods-manager) under the authority of the [TODS Board](../governance/governance.md#tods-board-of-directors) with basic monetary support through 2025 from the [California Integrated Travel Project (Cal-ITP)](https://cal-itp.org).
4 |
5 | TODS was [initially developed](spec-development.md) in 2021-2022 by the [TODS Working Group](contributors.md) (now known as *contributors*) using resources from the [California Integrated Travel Project (Cal-ITP)](https://cal-itp.org) in order to:
6 |
7 | 1. Create a common standard for transit operational data
8 | 2. Improve efficiency in dispatching, planning, scheduling, driver shift management, and other back-end transit operations
9 | 3. Reduce the burden of generating data for reporting (FTA and other)
10 |
11 | As of 2024:
12 |
13 | * TODS v1.0 is leveraged by several software vendors and transit agencies,
14 | * TODS v2.0 has been adopted and is ready for implementation,
15 | * [Independent governance and ownership](../governance/governance.md) has been established in order to meet the [Mobility Data Interoperability Principles'](https://interoperablemobility.org) definition of an **Open Standard**.
16 | * TODS is specified as a suggested requirement for Scheduling and CAD/AVL systems in the Mobility Data Interoperability Principles' [Procurement Resource](https://interoperablemobility.org/procurement)
17 |
--------------------------------------------------------------------------------
/docs/en/about/attribution.md:
--------------------------------------------------------------------------------
1 | # Attribution
2 |
3 | The project was initiated by the [California Integrated Travel Project](https://calitp.org), a project of the California Department of Transportation.
4 |
5 | The project has been resourced by the [California Integrated Travel Project](https://calitp.org) and the [TODS Working Group](../resources/faq.md#what-is-the-tods-working-group).
6 |
7 | The Transit Operational Data Standard (TODS) project is the property of the TODS Board. As of January 2024, the TODS Project is managed by [MobilityData](https://mobilitydata.org) under the authority of the TODS Board.
8 |
9 | ## Citation
10 |
11 | If you use the Transit Operational Data Standard in a report or article, please cite it as follows:
12 |
13 | > Transit Operational Data Standard Working Group. 2022. Transit Operational Data Standard. Transit Operational Data Standard Board of Directors. https://ods.calitp.org.
14 |
--------------------------------------------------------------------------------
/docs/en/about/contributors.md:
--------------------------------------------------------------------------------
1 | # Contributors
2 |
3 | The Transit Operational Data Standard Contributors Group (formerly known as the TODS Working Group) is convened by [TODS Board](../governance/governance.md#tods-board-of-directors) as part of its goal to provide complete, accurate, and up-to-date transit data to customers and respective agencies.
4 |
5 | Contributors are expected to commit to supporting the adopted TODS v1 specification. Depending on the organization,supporting the TODS v1 specification may entail developing software to produce or consume the specification, or, for transit agencies, encouraging vendors to support the specification.
6 |
7 | ## Membership
8 |
9 | ### Transit Agencies
10 |
11 | [AC Transit, CA](https://www.actransit.org/)
12 | [Clovis Transit, CA](https://cityofclovis.com/general-services/transit/)
13 | [Community Transit, WA](https://www.communitytransit.org/)
14 | [Foothill Transit, CA](http://foothilltransit.org/)
15 | [Golden Empire Transit, CA](https://www.getbus.org/)
16 | [Kings Area Rural Transit (KART), CA](https://www.kartbus.org/)
17 | [Los Angeles DOT, CA](https://www.ladottransit.com/dash/)
18 | [Marin Transit, CA](https://marintransit.org/)
19 | [Massachussets Bay Transit Authority (MBTA), MA](http://mbta.com) :material-check-circle-outline:
20 | [Metrolink, CA](https://metrolinktrains.com/)
21 | [Metro Transit, MN](https://www.metrotransit.org)
22 | [Nevada County Connects, CA](https://www.mynevadacounty.com/2257/Transit-Services)
23 | [OmniTrans, CA](https://omnitrans.org/)
24 | [Pasadena Transit, CA](https://www.cityofpasadena.net/pasadena-transit/)
25 | [SamTrans, CA](https://www.samtrans.com/)
26 | [Sound Transit, WA](https://www.soundtransit.org/)
27 | [Stanislaus Regional Transit Authority, CA](https://www.srt.org/)
28 | [TriMet, OR](https://trimet.org/)
29 |
30 | ### Companies
31 |
32 | [Avail](https://availtec.com/)
33 | [Clever Devices](https://www.cleverdevices.com/)
34 | [Connexionz](https://www.connexionz.com/)
35 | [Cubic](https://www.cubic.com/)
36 | [Dilax](https://www.dilax.com/)
37 | [Engie](https://www.engie.com/en)
38 | [Giro](https://www.giro.com/) :material-check-circle: (on-request)
39 | [GMV Syncromatics](https://gmvsyncromatics.com/)
40 | [Init](https://www.initse.com/enus/start/)
41 | [Keolis](https://www.keolisna.com/)
42 | [MV Transit](https://www.mvtransit.com/)
43 | [Optibus](https://www.optibus.com/)
44 | [Passio](https://passiotech.com/)
45 | [Remix by Via](https://www.remix.com/) :material-check-circle:
46 | [Routematch / Uber](https://www.routematch.com/)
47 | [Swiftly](https://www.goswift.ly/) :material-check-circle:
48 | [The Master Scheduler](https://themasterscheduler.com/) :material-check-circle:
49 | [Trapeze](https://www.trapezegroup.com/)
50 | [Trillium Solutions](https://trilliumtransit.com/)
51 |
52 | ### Other
53 |
54 | [Amalgamated Transit Union](https://www.atu.org/)
55 | [California Association for Community Transportation (CALACT)](http://calact.org)
56 | [California Integrated Travel Project (Cal-ITP)](http://calitp.org)
57 | [Metropolitan Transportation Commission/511.org](http://mtc.ca.gov)
58 |
59 | !!! Note "Implementers"
60 |
61 | :material-check-circle: denotes an organization who has implemented TODS
62 |
63 | :material-check-circle-outline: denotes an organization in the process of implementing TODS
64 |
--------------------------------------------------------------------------------
/docs/en/about/spec-development.md:
--------------------------------------------------------------------------------
1 | # History + Initial Specification Development Process
2 |
3 | The California Integrated Travel Project (Cal-ITP) developed the TODS initiative in response to feedback from local transit providers and vendors. As Cal-ITP has as its core a mission to improve the quality of mobility data and increase the efficiency of transportation service delivery in the state of California, Cal-ITP conducted research and conversations with an eye toward identifying existing pain points. Many tranit agencies identified the lack of a standard format between scheduling and CAD/AVL software as a major source of friction.
4 |
5 | ## Establishing Feasibility + Need
6 |
7 | In 2020, Cal-ITP studied the feasibility and documented the product requirements of a data standard that would reduce the friction between scheduling and operating transit service. The friction between these two activities was particuarlly acute during the height of the COVID Pandemic when transit agency schedules were in a constant state of change due to labor availability and safety precautions.
8 |
9 | ### Landscape Analysis
10 |
11 | We analyzed the current landscape of systems and connections involved in transit operations. The primary focus was on the various interfaces and touchpoints between the Scheduling and CAD/AVL systems. The landscape analysis concluded that a data standard that connected scheduling and CAD-AVL systems was both feasible and not duplicative of any existing standardization efforts.
12 |
13 | :material-chevron-right: [Data Flow Diagrams](https://docs.google.com/document/d/1nNnVgmk29ExZU7_bkoawkpvP_gtn3DSR9eV8BugUY14/edit?usp=sharing)
14 |
15 | :material-chevron-right: [Field Mapping](https://docs.google.com/spreadsheets/d/1P7jLcp9BDx2Q-FVVR0fdc_eH5cEVxXjA1tdpID_uoTM/edit?usp=sharing)
16 |
17 | ### Document Product Requirements
18 |
19 | The Product Requirements Document synthesized the landscape analysis into a realistic set of use cases with associated data model requirements.
20 |
21 | :material-chevron-right: [Product Requirement Document](https://docs.google.com/document/d/1KFLoMAj-XmNrn0MbCVB_IwlK2bILvuVImkjxXrZ9AXk/edit?usp=sharing)
22 |
23 | ### Consulted organizations
24 |
25 | The following organizations were consulted as a part of the feasibility analysis:
26 |
27 | - LADOT
28 | - Santa Barbara MTD
29 | - Santa Rosa:
30 | - Marin Transit
31 | - Golden Empire Transit (GET Bus)
32 | - Chicago Transit Authority
33 | - Massachusetts Bay Transportation Authority
34 | - IBI Group
35 | - GMV Synchromatics
36 | - Optibus
37 | - Clever Devices
38 | - Swiftly
39 | - The Master Scheduler
40 | - Trillium
41 |
42 | ## Initial Development
43 |
44 | In 2021, Cal-ITP convened the [TODS Working Group](../resources/faq.md#what-is-the-tods-working-group), composed of stakeholders throughout the mobility industry, for the purpose of developing and adopting a first version of a Transit Operational Data Standard (TODS). These stakeholders included transit schedule firms, CAD/AVL firms, public transit providers, private transit providers, local governments and metropolitan planning organizations (MPOs), labor unions, and manufacturers of integrated on-vehicle hardware solutions (such as Automated Passenger Counting devices or LED signage).
45 |
46 | Meetings began in Summer of 2021 and continued through the end of 2021, at which point a framework for v1.0.0 had been reached. After spending several months resolving minor issues with the framework, the TODS Working Group approved v1.0.0 on May 3rd, 2022.
47 | For a full list of past meetings and videos, go to the [Contributor Meetings page](../governance/contributor-meetings.md).
48 |
49 | ## Implementation v1.0
50 |
51 | 2022 and 2023 saw the first implementations of TODS at agencies and vendors alike in the wild, including the first implementation by [WETA](https://weta.sanfranciscobayferry.com/) and [Swiftly](https://www.goswift.ly/).
52 |
53 | ## Continued Improvement
54 |
55 | Implementation activities yielded a great deal of excitement about the TODS standard, but also a long wish-list for v2.0. v2.0 is [currently in the works.](https://github.com/cal-itp/operational-data-standard/issues/49).
56 |
57 | ## Evolution of Management
58 |
59 | Recognizing that a State DOT is not the ideal place to manage a data standard, in 2023 Cal-ITP looked outside its walls to identify:
60 |
61 | 1. an organization to assume day-to-day management of TODS; and
62 | 2. a governance and management model which would rest key decisions with the major TODS stakeholders.
63 |
64 | In January 2024:
65 |
66 | - the day-to-day management of the TODS standard will be assumed by [MobilityData](https://mobilitydata.org), the same organization that manages [GTFS](https://gtfs.org) (upon which TODS relies); and
67 | - the ownership and key decisions about TODS will be transfered from Cal-ITP to an [independent board](../governance/governance.md#tods-board-of-directors) composed of transit agencies, and both schedule and CAD/AVL vendors.
68 | - future spec development will be governed by the [change management and versioning policy](../governance/policies/change-management-versioning.md)
69 |
--------------------------------------------------------------------------------
/docs/en/governance/actions.md:
--------------------------------------------------------------------------------
1 | # TODS Board Actions
2 |
3 | Record of actions taken by the TODS Board.
4 |
5 | *Note that routine actions such as approval of meeting minutes are not listed here*
6 |
7 | | **Date** | **Action** | **Record (Yes - No - Abstain)** |
8 | | -------- | ---------- | ---------- |
9 | | 3/26/25 | TODS Change Management and Versioning Policy ammended to stipulate that the TODS Manager will lead at least 1 development cycle annually. | (4 - 0 - 0) |
10 | | 1/22/25 | Member Tollison's resignation from the Board sparks a proposal to follow up with individuals previously expressing interest in serving on the Board as an immediate next step and following up with the Board with additional proposals to expand the pool of Board Member candidates in the future | (3 - 0 - 0) |
11 | | 1/22/25 | Chair Jensen's employment was transfered without issue from his previous employement, to his new. Both positions were in public transit, not private enterprise. | (3 - 0 - 0) |
12 | | 9/18/24 | Board voted to readd TODS 1.0 definitions back to site, with indication that updates were no longer being made based on TODS 1.0 and that all future updates would be based on TODS 2.0| (5 - 0 - 0) |
13 | | 9/18/24 | Board supported a proposal to offer assistance/advice to the development teams for Giro and to collaborate on their implementation of TODS in Hastus and eventual TODS 2.0 based integration.| (5 - 0 - 0) |
14 | | 9/18/24 | Board supported a proposal to offer assistance/advice to the development teams for Optibus and GMV and to collaborate on their TODS 2.0 based integration.| (5 - 0 - 0) |
15 | | 7/24/24 | TODS 2.0 is adopted, now to be implemented. | (5 - 0 - 0) |
16 | | 6/26/24 | ODS Program Manager granted authority to make non-substantive changes to TODS governance to fix typos and change spec branding from ODS to TODS. | (5 - 0 - 0) |
17 | | 6/26/24 | Direct TODS Program Manager to transition TODS versioning to semantic versioning in the format X.X.X representing [breaking change].[non breaking change].[patch]. | (5 - 0 - 0) |
18 | | 6/26/24 | Direct TODS Program Manager to release all adopted proposals for a given development cycle under a single "bundled" version, rather than issuing a version for each adopted proposal individually. | (5 - 0 - 0) |
19 | | 3/11/24 | Erik Jansen elected as Board Chair. | (5 - 0 - 0) |
20 | | 3/11/24 | Scott Frazier elected as Board Coordinator. | (5 - 0 - 0) |
21 | | 3/11/24 | TODS Program Manager granted authority to move TODS repo out of Cal-ITP organization. | (5 - 0 - 0) |
22 |
--------------------------------------------------------------------------------
/docs/en/governance/board-meetings.md:
--------------------------------------------------------------------------------
1 | # TODS Board Meetings
2 |
3 | The TODS Board Meeting Agendas + Minutes are available below.
4 |
5 | ## 2025
6 |
7 | | **Date** | **Minutes** |
8 | | -------- | ---------- |
9 | | 22 January 2025 | [Agenda & Minutes](https://docs.google.com/document/d/18tAwwYKdcqTJ9auGbvVNpY08HnS9kkLUFJbM2i1w718/edit?usp=sharing) |
10 | | 26 March 2025 | [Agenda](https://docs.google.com/document/d/1RUx7vOqt0JUUWA68fUTGEh_bAnERjMsXPkZtRZoOSwA/edit?usp=sharing) & [Minutes](https://docs.google.com/document/d/1lP6kdKpNEFBnD-iuqfZFCfByFEENucQRmNjeEiExrv0/edit?usp=sharing) |
11 |
12 | ## 2024
13 |
14 | | **Date** | **Minutes** |
15 | | -------- | ---------- |
16 | | 11 March 2024 | [Agenda & Minutes](https://docs.google.com/document/d/1Y76UMxpnR0vQm2F8s02s8gIYr7JyHNFOX-lSFQheC8Q/edit?usp=sharing) |
17 | | 26 June 2024 | [Agenda & Minutes](https://docs.google.com/document/d/1Y76UMxpnR0vQm2F8s02s8gIYr7JyHNFOX-lSFQheC8Q/edit?usp=sharing) |
18 | | 24 July 2024 | [Agenda](https://docs.google.com/document/d/1GhQDt39f45WMvLpaBXvOVmZmAbyw-wNhK9ZlDj7Ci3M/edit?usp=sharing) |
19 | | 18 September 2024 | [Agenda & Minutes](https://docs.google.com/document/d/1FyFHIH8IEYflgzyLm3_Zsh67WrdMZixoYZpfvL3wyz8/edit?usp=sharing) |
20 |
--------------------------------------------------------------------------------
/docs/en/governance/contributor-meetings.md:
--------------------------------------------------------------------------------
1 | # Contributor Meetings
2 |
3 | ## TODS Q3 2024 Development Cycle
4 |
5 | | Meeting | Date | Agenda | Minutes | Video |
6 | | :---------- | :---- | :------ | :------- | :----- |
7 | | Q3 2024 Development Priorities | 23 Jul 2024 | [Agenda](https://drive.google.com/file/d/1wY1Mp8tnYxvtGoaGzvTfeB6CaD6r_VbT/view?usp=sharing) | [Minutes](https://drive.google.com/file/d/1DK9hDQxLyQy_f1HEhW7P-N-lAAHTT3Xa/view?usp=drive_link) | [Video](https://drive.google.com/file/d/1UpYKlSiFWJa5mmfu1q6nttWFSd4WT7hn/view?usp=sharing) |
8 |
9 | ## TODS 2.0
10 |
11 | | Meeting | Date | Description |
12 | | :---------- | :---- | :----------------------------------- |
13 | | Working Group Meeting #1
| 4 Apr 2024 | Review of and feedback on Run Events proposal; decide next steps on "GTFS-supplemental" proposal. |
16 |
17 | ## TODS 1.0
18 |
19 | | Meeting | Date | Description |
20 | | :---------- | :---- |:----------------------------------- |
21 | | [Working Group Meeting #1](https://docs.google.com/presentation/d/1y_xF002j0NJxt-pGTO2bR473rKWrNUzWvNZLncsbAXQ/edit?usp=sharing) | 20 Jul 2021 | Confirmation of need. |
22 | | Stakeholder Scoping Meetings | Aug 2021 | Individual meetings with stakeholders to get detailed needs and scoping input. |
23 | | [Working Group Meeting #2](https://docs.google.com/presentation/d/1x5cGNhLIBuYv_VM_Spdy85Vn7rWIDtlGSPsvDHTdjsI/edit?usp=drive_link) | Aug 2021 | Scope confirmation and process confirmation for spec development. |
24 | | [Working Group Meeting #3](https://docs.google.com/presentation/d/1z2sgo3tA7JtLwSz9F6BFbbWrNK23gi8u5TdYsx30loc/edit?usp=drive_link) | 28 Sep 2021 | [Personnel Proposal](https://docs.google.com/document/d/1IL1mKME88M9jLHyyr545E1dLKWTdbRdt7OWihxgRjjI/edit?usp=drive_link) [Meeting #3 notes](https://docs.google.com/document/d/1Fs1eRlKEDyKXCprV8pmDrr3QBMtuLczhvoG7t7Fn72w/edit?usp=drive_link) |
25 | | [Working Group Meeting #4](https://docs.google.com/presentation/d/14A_j6A1ZqsaoNp_POVNWJb4Mu9-d_iO_0mdq-GJ7RSY/edit?usp=drive_link) | 19 Oct 2021 | [Facilities Proposal](https://docs.google.com/document/d/1p-fDePrnLBjJoceXLEbbYR1dPLwt6aoE26osMcp5NsQ/edit?usp=drive_link) [Meeting #4 video](https://drive.google.com/file/d/1XeUm1QTEWUPXkge5GnVVbnwF6AmBY6ER/view?usp=drive_link) |
26 | | Working Group Meeting #5 | 16 Nov 2021 | [Runcutting, Layovers, + Deadheads Proposal](https://docs.google.com/document/d/1GmBdo39QHIqD0MoPGT6RPyvkuxHYWQWXRi_rTOUYhpg/edit?usp=drive_link) |
27 | | Working Group Meeting #6 | 21 Dec 2021 | Adoption of v1 framework [Meeting #6 video](https://drive.google.com/file/d/1LAaAWFUjvPCTMvRs_1PhNT4WZZmcWbsZ/view?usp=drive_link) |
28 | | [Working Group Meeting #7](https://docs.google.com/presentation/d/1p7qJSq5Ray07UZ_BNovW4MViXPZQi0by65ZbLDxNySk/edit?usp=drive_link) | 22 Feb 2022 | Discussion of Upcoming Implementation Steps [Meeting #7 video](https://drive.google.com/file/d/1eiHYiwoUsjXVFFChWB7dqf8fSo1k-mxz/view?usp=drive_link) |
29 | | Working Group Meeting #8 | 3 May 2022 | Reconsideration of v1 framework and adoption of 1.0.0 [Meeting #8 video](https://drive.google.com/file/d/1Eh_DJj1_9Copb0xHiFXSNBaS7My1UUsw/view?usp=drive_link) |
30 |
--------------------------------------------------------------------------------
/docs/en/governance/governance.md:
--------------------------------------------------------------------------------
1 | # TODS Governance
2 |
3 | This page outlines the policies, procedures, and structures that guide the collaborative and transparent development of the Transit Operational Data Standard ("TODS"). The TODS is a critical framework enabling effective dispatching and operations management through a standardized data schema. This document is intended for all members of the TODS Community, including the TODS Board of Directors, TODS Managers, TODS Contributors, and TODS Stakeholders. By clearly defining the principles, roles, and policies, we aim to facilitate the efficient, fair, and responsible advancement of the TODS Project.
4 |
5 | ## Principles
6 |
7 | The TODS Governance is designed with the following principles in mind:
8 |
9 | **Merit**
10 |
11 | - Changes should have a clear purpose.
12 | - Consequences of a change should be evaluated from the perspective of different affected stakeholder groups.
13 | - Changes should be prioritized by the community.
14 |
15 | **Openness + Transparency**
16 |
17 | - Discussion and decisions about changes should be publicly noticed and accessible.
18 | - Change-making process should be straight-forward and easy to follow.
19 | - Change proposals should have a reliable timeline for being decided on and incorporated.
20 | - Each change (or bundled set of changes) should be identified by assigning a new version number.
21 |
22 | **Efficiency**
23 |
24 | - Change-making process should be simple for simple changes.
25 | - Complex changes should be made with careful consideration.
26 | - Streamlined, purpose-driven change management should be applied to maximize stakeholder efficiency.
27 | - Changes should be straightforward to incorporate by existing TODS Stakeholders.
28 | - Significant changes, especially those which are not backwards compatible with existing datasets, should be limited in number and in frequency in order to limit the number of times existing processes and tools need to be re-engineered.
29 | - A significant change merits a new version number.
30 |
31 | ## Definitions
32 |
33 | ### TODS Project
34 |
35 | The TODS Project encompasses:
36 |
37 | - [TODS Specification](#tods-specification)
38 | - [TODS Tools](#tods-tools)
39 | - [TODS Repository](#tods-repository)
40 | - [TODS Documentation](#tods-documentation)
41 | - [TODS Governance](#tods-governance)
42 |
43 | ### TODS Governance
44 |
45 | Who and how decisions are made about the scope and direction of the TODS Project, including but not limited to the approved [roles and responsibilities](#roles) and the following policies:
46 |
47 | - [TODS Change Management and Versioning Policy](#tods-change-management-versioning-policy)
48 | - [TODS Contributor Agreement](#tods-contributor-agreement)
49 | - [TODS Code of Conduct](#tods-code-of-conduct)
50 | - [TODS Use License](#tods-use-license)
51 |
52 | ### TODS Specification
53 |
54 | The data schema documented on the [TODS Repository](#tods-repository) and [TODS Documentation](#tods-documentation) for the purposes of representing planned transit operations for use is dispatching and operations management software.
55 |
56 | ### TODS Community
57 |
58 | The combined members of [TODS Board](#tods-board-of-directors), [TODS Manager](#tods-manager), [TODS Board Coordinator](#tods-board-coordinator), [TODS Contributors](#tods-contributor) and [TODS Stakeholders](#tods-stakeholder).
59 |
60 | ### TODS Contributor Agreement
61 |
62 | Agreement contributors make when contributing to the [TODS Project](#tods-project) as documented at: [`CLA.md`](policies/CLA.md)
63 |
64 | ### TODS Code of Conduct
65 |
66 | Agreement for behavior within the [TODS Community](#tods-community) which must be abided by by all of [TODS Board](#tods-board-of-directors), [TODS Contributors](#tods-contributor) and the [TODS Manager](#tods-manager) and its representatives as documented at [`code-of-conduct.md`](policies/code-of-conduct.md)
67 |
68 | ### TODS Change Management + Versioning Policy
69 |
70 | How content of the [TODS Specification](#tods-specification) may be changed and released as an official [TODS version](policies/change-management-versioning.md#tods-release).
71 |
72 | ### TODS Documentation
73 |
74 | The text and website (and supporting scripts) which describe the [TODS Specification](#tods-specification) and its purpose and usage located on the [TODS Repository](#tods-repository).
75 |
76 | ### TODS Repository
77 |
78 | The version control repository containing the [TODS Specification](#tods-specification) located at:
79 |
80 |
81 | ### TODS Repository Organization
82 |
83 | The version control organization which contains the [TODS Repository](#tods-repository).
84 |
85 | !!! warning "To be migrated"
86 |
87 | The TODS Repository is currently located with the Cal-ITP GitHub organization but will be migrated as part of the process of transitioning management to MobilityData.
88 |
89 | ### TODS Tools
90 |
91 | Any scripts or code released within the [TODS Repository Organization](#tods-repository-organization).
92 |
93 | ### TODS Use License
94 |
95 | The [TODS Specification](#tods-specification) is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) (code) and [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/) (sample data, specification, and documentation) as defined in [`LICENSES`](https://github.com/cal-itp/operational-data-standard/blob/main/LICENSES) file in the [GitHub repository](https://github.com/cal-itp/operational-data-standard).
96 |
97 | ## Roles
98 |
99 | Responsibility for the governance of the TODS Project is divided among the following [roles](#roles) as defined here and fulfilled by the following individuals as noted:
100 |
101 | | **Role** | **Who** |
102 | | -------- | ----- |
103 | | [TODS Board](#tods-board-of-directors) |
[Joshua Fabian](https://www.linkedin.com/in/jfabi/), [Massachusetts Bay Transportation Authority (MBTA)](https://www.mbta.com/)
|
104 | | [TODS Board Coordinator](#tods-board-coordinator) | [Scott Frazier](https://github.com/safrazier17) |
105 | | [TODS Manager](#tods-manager) | [MobilityData](https://mobilitydata.org) |
106 | | [TODS Program Manager](#tods-program-manager) | [Cristhian Hellion](https://github.com/Cristhian-HA), [MobilityData](https://mobilitydata.org) |
107 | | [TODS Contributors](#tods-contributor) | TBD |
108 | | [TODS Stakeholders](#tods-stakeholder) | Anyone interested in or could be directly affected by the TODS Project. |
109 |
110 | ## TODS Owner
111 |
112 | The TODS Project is collectively owned and overseen by the [TODS Board of Directors](#tods-board-of-directors).
113 |
114 | ## TODS Board of Directors
115 |
116 | The TODS Board of Directors ("TODS Board") governs and collectively owns the [TODS Project](#tods-project).
117 |
118 | - The Board MAY select an individual or organization to serve as the [TODS Manager](#tods-manager) to handle the day-to-day management of the [TODS Specification](#tods-specification) and [TODS Project](#tods-project).
119 | - The [TODS Board](#tods-board-of-directors) MUST execute a memorandum of understanding with the [TODS Manager](#tods-manager) (if one is chosen) that outlines the roles, responsibilities, and limitations of the management role.
120 | - The [TODS Board](#tods-board-of-directors) MAY change the [TODS Manager](#tods-manager) at any time for any reason.
121 | - In the event that there is not an active agreement with an [TODS Manager](#tods-manager) the [TODS Board](#tods-board-of-directors) MUST assume the [TODS Manager](#tods-manager) responsibilities.
122 | - The [TODS Board](#tods-board-of-directors) SHOULD ask the [TODS Manager](#tods-manager) to select a new [TODS Program Manager](#tods-program-manager) if there is continued failure to perform and meet expectations.
123 | - [TODS Board](#tods-board-of-directors) membership MUST be determined by the [Board Composition Policy](policies/board-composition.md).
124 | - [TODS Board](#tods-board-of-directors) decisionmaking should be consistent with the [Board Decisionmaking Policy](policies/board-decisionmaking.md).
125 |
126 | TODS Board [meetings](board-meetings.md) and [actions](actions.md).
127 |
128 | ## TODS Board Coordinator
129 |
130 | Chosen by the TODS Board, this individual is responsible for coordinating the actions and activities of the [TODS Board](#tods-board-of-directors).
131 |
132 | - The Board Coordinator MUST schedule, agendize and arrange for Board meetings in consultation with the TODS Board Chair and [TODS Program Manager](#tods-program-manager).
133 | - The Board Coordinator MUST conduct votes by the [TODS Board](#tods-board-of-directors) and document results.
134 | - The Board Coordinator MUST communicate with the [TODS Manager](#tods-manager) / [TODS Program Manager](#tods-program-manager) as needed.
135 |
136 | ## TODS Manager
137 |
138 | Responsible for the daily management of the TODS Project at the direction of the [TODS Board](#tods-board-of-directors) including the:
139 |
140 | - [TODS Change Management Process](policies/change-management-versioning.md),
141 | - [TODS Repository](#tods-repository),
142 | - TODS Project resource management, and
143 | - Internal and external project communications.
144 |
145 | - The [TODS Manager](#tods-manager) MAY be an individual or organization.
146 | - The [TODS Manager](#tods-manager) MUST assign an individual as the [TODS Program Manager](#tods-program-manager).
147 | - The [TODS Manager](#tods-manager) MUST communicate the name of the [TODS Program Manager](#tods-program-manager) to the [TODS Board](#tods-board-of-directors) in writing and notify the Board of any change in this assignment in writing.
148 | - The [TODS Manager](#tods-manager) SHOULD select a new [TODS Program Manager](#tods-program-manager) if asked to do so by the TODS Board.
149 |
150 | ## TODS Program Manager
151 |
152 | Serves as the main contact between the [TODS Board](#tods-board-of-directors) and the [TODS Manager](#tods-manager).
153 |
154 | ## TODS Contributor
155 |
156 | Individuals apply to become Contributors by acknowledging and agreeing to the [TODS Contributor Agreement](#tods-contributor-agreement) and [TODS Code of Conduct](#tods-code-of-conduct).
157 |
158 | - An TODS Contributor MUST abide by the [TODS Code of Conduct](#tods-code-of-conduct) or face removal.
159 | - An TODS Contributor MAY create issues, discussions, and pull requests in the [TODS Repository](#tods-repository).
160 | - An TODS Contributor MAY vote in decisions on changes to the TODS spec and other aspects of TODS.
161 |
162 | ## TODS Stakeholder
163 |
164 | Anyone interested in or could be directly affected by the TODS Project. Interested parties may register for the [TODS distribution list](https://groups.google.com/g/ods-working-group).
165 |
166 | ## Document History
167 |
168 | ### Initial Version
169 |
170 | - Initial release of the TODS Governance document.
171 | - Establishment of governance principles, roles, policies, and procedures.
172 |
--------------------------------------------------------------------------------
/docs/en/governance/policies/CLA.md:
--------------------------------------------------------------------------------
1 | # Contributor License Agreement
2 |
3 | By making a contribution to this project, I certify that:
4 |
5 | > a. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
6 | >
7 | > b. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or
8 | >
9 | > c. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
10 | >
11 | > d. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
12 |
13 | Attribution: This Contributor Agreement is adapted from the node.js project available here: .
14 |
--------------------------------------------------------------------------------
/docs/en/governance/policies/board-composition.md:
--------------------------------------------------------------------------------
1 | # TODS Board Composition Policy
2 |
3 | In standing up and sustaining the TODS Board, the current [TODS Board][board]:
4 |
5 | - MUST decide the number of board positions;
6 | - MUST select individuals to fill open board positions for three-year terms;
7 | - SHOULD stagger board terms to avoid more than half the board turning over in any given year;
8 | - SHOULD aim for geographic, demographic, and organizational diversity; and
9 | - SHOULD aim for the majority of board members to come from transit agencies.
10 |
11 | Individuals serving on the [TODS Board][board]:
12 |
13 | - MUST serve as individuals, not organization representatives;
14 | - SHOULD offer their resignation with significant professional changes, like switching industries;
15 | - MAY be removed by a majority vote of the [TODS Board][board] for infractions including but not limited to not upholding the TODS Code of Conduct or their [TODS Board][board] responsibilities.
16 |
17 | [board]: ../governance.md#tods-board-of-directors
18 |
--------------------------------------------------------------------------------
/docs/en/governance/policies/board-decisionmaking.md:
--------------------------------------------------------------------------------
1 | # TODS Board Decision Policy
2 |
3 | The [TODS Board][board] will be required to act from time-to-time in order to make official [TODS Project][project] decisions such as (but not limited to):
4 |
5 | - executing a memorandum of understanding ("MOU"),
6 | - choosing the [TODS Manager][manager], and
7 | - resolving stalemates in [TODS Change Management](change-management-versioning.md) process
8 |
9 | [TODS Board][board] Decisionmaking shall be subject to:
10 |
11 | - A vote MAY be called by any [TODS Board][board] member, the [TODS Board Coordinator][coordinator], or the [TODS Program Manager][program-manager] at any time.
12 | - [TODS Board][board] decisions MUST be approved by two thirds of the non-abstaining members at the time of the vote.
13 | - Voting MAY be done by email or other written form of communication.
14 | - [TODS Board][board] members MAY abstain from any vote.
15 | - [TODS Board][board] members MUST abstain from any vote where they have a direct conflict of interest where they would personally financially benefit; although they are encouraged to state their position on a topic at hand.
16 |
17 | ## Governance Documentation
18 |
19 | The [TODS Board Coordinator][coordinator], MUST make sure all governance documents and TODS Board Decisions are up-to-date and stored in the [TODS Repository][repository].
20 |
21 | [board]: ../governance.md#tods-board-of-directors
22 | [manager]: ../governance.md#tods-manager
23 | [coordinator]: ../governance.md#tods-board-coordinator
24 | [repository]: ../governance.md#tods-repository
25 | [program-manager]: ../governance.md#tods-program-manager
26 | [project]: ../governance.md#tods-project
27 |
--------------------------------------------------------------------------------
/docs/en/governance/policies/change-management-versioning.md:
--------------------------------------------------------------------------------
1 | # TODS Versioning and Change Management Policy
2 |
3 | !!! tip
4 |
5 | When capitalized in this document, the words “MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" refer to their respective definitions in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).
6 |
7 | ## Definitions
8 |
9 | !!! tip
10 |
11 | Definitions of various roles such as [TODS Board][board], [TODS Manager][manager], and [TODS Contributors][contributors] refer to their respective definitions in the [TODS Governance][governance].
12 |
13 | The following definitions build on the overall [TODS Governance][governance] definitions and exist within the purpose of the TODS Versioning and Change Management Policy.
14 |
15 | ### TODS Release
16 |
17 | An official version of the [TODS Specification][tods-spec] which can be referenced in perpetuity by a version number. The process by which a new release is made and determination of a version number is discussed below.
18 |
19 | Each change to normative content in the main branch of the TODS Repository MUST be considered a new release and assigned a version number.
20 |
21 | ### Normative Content
22 |
23 | Normative Content is the prescriptive part of a standard. It sets the rules to be followed in order to be evaluated as compliant with the standard, and from which no deviation is permitted.
24 |
25 | ### Non-Normative Content
26 |
27 | Non-normative content is the non-prescriptive, or ‘descriptive’, part of a standard. This may include analogies, synonyms, explanations, illustrations, context, and examples. In the event non-normative content contradicts normative content, the normative content is to be followed.
28 |
29 | ### Issue Working Group
30 |
31 | Tasked by the [TODS Manager][manager] with resolving a specific issue with respect to the [TODS Specification][tods-spec].
32 |
33 | ### Urgent Needs
34 |
35 | Urgent needs MUST pose significant risks to security, compliance, or the operational integrity of stakeholder systems. These MAY include necessary revisions due to legal mandates, critical security vulnerabilities, or severe technical inaccuracies that directly impair system functionalities. Urgent needs SHOULD necessitate an implementation timeline which is inconsistent with the normal change-making process.
36 |
37 | ## Change-Making Process
38 |
39 | This change-making process covers [all normative content changes](#normative-content) to the [TODS Specification][tods-spec] and occurs in the following stages:
40 |
41 | | Stage | When | Who (led by) |
42 | |-----|-----|-----|
43 | | Need Identification | Anytime | Anyone |
44 | | Need Prioritization | Quarterly | Contributors ([TODS Manager][manager]) |
45 | | Initial Proposal Development | Prioritized quarter | Issue Working Group ([TODS Manager][manager]r) |
46 | | Contributor Review + Adoption | Pull request for proposed change submitted after consensus in the Working Group | Issue Working Group ([TODS Manager][manager]) |
47 | | Implementation | When decision made to consensus achieved on proposal | Issue Working Group ([TODS Manager][manager]) |
48 | | Released | Next quarterly release | [TODS Manager][manager] |
49 |
50 | Each of these stages is discussed in more detail below.
51 |
52 | ### Need Identification
53 |
54 | Initiated when Any TODS Contributor identifies a need that should be addressed in the [TODS Specification][tods-spec].
55 |
56 | Actions:
57 |
58 | * An TODS Contributor submits an issue to the TODS Repository which identifies the need that they would like addressed and a rough assessment of its addressable audience.
59 | * An [TODS Manager][manager] triages issue and asks for more detail from the Contributor if needed.
60 | * An [TODS Manager][manager] determines if issue resolution would require a normative change.
61 |
62 | Resolution: [TODS Manager][manager] puts issue into consideration for next quarterly issue prioritization
63 |
64 | ### Prioritization
65 |
66 | Initiated when the [TODS Manager][manager] starts a development cycle after or near the end of a quarterly release.
67 |
68 | Actions:
69 |
70 | * [TODS Manager][manager] to solicit feedback from TODS Contributors on which needs to prioritize.
71 | * [TODS Manager][manager] to propose a set of needs that the community will focus on resolving based on feedback and available community capacity.
72 | * [TODS Board][board] will approve a set of needs to focus on based on [TODS Manager][manager]’s proposal and TODS Contributors’ feedback.
73 |
74 | Resolution: [TODS Manager][manager] will create a Milestone for the next release in the TODS Repository and fill it with the issues the [TODS Board][board] prioritized.
75 |
76 | ### Initial Proposal Development
77 |
78 | Initiated [for each need] when [TODS Manager][manager], in consultation with the [TODS Board][board] and [TODS Contributors][contributors], convenes an Issue Working Group to address a prioritized issue or set of interrelated issues.
79 |
80 | Actions:
81 |
82 | * [TODS Manager][manager] convenes an Issue Working Group to develop a resolution to the issue.
83 | Working Group members document discussion points about approach in the relevant github issue.
84 | * While consensus will be sought, if the Issue Working Group members cannot come to a unanimous agreement about the solution, the [TODS Manager][manager] may ask the [TODS Board][board] to make a decision after hearing feedback from various perspectives.
85 | * Issue Working Group members update the schema and documentation according to the proposal on a feature branch.
86 |
87 | Resolution: Issue Working Group submits a pull request to the develop branch.
88 |
89 | ### Contributor Review + Adoption
90 |
91 | Initiated [for each need] when: [TODS Manager][manager] invites TODS Stakeholders outside of the Working Group to review and comment on the proposal
92 |
93 | Actions:
94 |
95 | * The [TODS Manager][manager] MUST invite people outside of the Working Group to review and comment on the proposal for a minimum of two weeks, making sure [TODS Contributors][contributors] with different roles and backgrounds have had a chance to consider it.
96 | * The [TODS Manager][manager] MUST review the proposal for consistency with the [Open Standards](https://www.interoperablemobility.org/definitions) definition maintained by the [Mobility Data Interoperability Principles](https://interoperablemobility.org).
97 | * The [TODS Manager][manager] MUST offer tools, services and assistance to any [TODS Contributor][contributors] who is unable to fluidly interact with the tooling used in the review process.
98 | * A minimum of three [TODS Contributors][contributors] outside the Working Group MUST publicly comment on each proposal for it to move forward and indicate a score of:
99 | * Accepted;
100 | * Accepted with minor changes; or
101 | * Substantially revised.
102 | * If 100% of reviewers accept, the proposal is adopted without need for further discussion.
103 | * If any reviewer accepts with minor changes, the suggested change must be considered by the Working Group.
104 | * If the Working Group decides to incorporate the edited proposal will be re-circulated for some period time greater than 72 hours and previous reviewers notified. If nobody objects to the change in that time, it is adopted.
105 | * If the Working Group does not agree with the suggested change, they may appeal to the [TODS Board][board]to make a final decision about its necessity.
106 | * If any reviewer requests substantial changes, they must also agree to work with the working group on developing an alternative solution to the need.
107 | * If the working group believes the substantial change request is invalid or without merit, they may appeal to the [TODS Board][board] to make a final decision about if revisions are necessary.
108 |
109 | Resolution: Change as represented in the pull request from the feature branch is approved and merged into the develop branch.
110 |
111 | ### Full Implementation
112 |
113 | Initiated [for each need] when: Final change proposal is approved - although initial work can begin ahead of this.
114 |
115 | Actions:
116 |
117 | * [TODS Manager][manager] MUST ensure the relevant accompanying documentation fleshed out.
118 | * [TODS Manager][manager] MUST ensure Changelog fully documented.
119 | * [TODS Manager][manager] MUST ensure sample datasets updated or added that support the new feature.
120 | * [TODS Manager][manager] MUST ensure any relevant updates to continuous integration and testing are completed.
121 | * [TODS Manager][manager] MAY make any number of [pre-release(s)](#pre-releases).
122 | * [TODS Manager][manager] MUST identify and ensure resolution of relevant conflicts among proposals as overseen by the [TODS Board][board] or their designee.
123 |
124 | Resolution: Requirements for [release](#releases) are met.
125 |
126 | ### Release
127 |
128 | Initiated: On a quarterly schedule maintained by the [TODS Manager][manager].
129 |
130 | Actions: See [Release Management](#releases).
131 |
132 | ## Expedited Change Management
133 |
134 | This section outlines an expedited process for implementing changes in response to urgent needs which are critical to maintaining the security, compliance, or operational functionality of [TODS Specification][tods-spec] balancing rapid response with informed, transparent decision-making.
135 |
136 | ### Process
137 |
138 | 1. **Identification**: Stakeholders SHOULD promptly report urgent needs to the [TODS Manager][manager], detailing the problem and its potential impact.
139 | 2. **Rapid Evaluation**: The [TODS Manager][manager] MUST convene a group of at least 2 TODS Contributors of their choosing to swiftly assess the issue's urgency and validity.
140 | * If it meets their threshold for an urgent need, they forward a list of their proposed Urgent Working Group Members to the [TODS Board][board].
141 | * The Urgent Working Group Members SHOULD contain representatives of TODS Contributors affected stakeholder groups.
142 | * The Urgent Working Group size SHOULD be at least three and reflect the scale of the problem and also need for agile decision making.
143 | * The [TODS Board][board] MAY object to their characterization of the need as urgent.
144 | * The [TODS Board][board] MAY make changes to the Urgent Working Group members.
145 | * If the [TODS Board][board] fails to respond within 48 hours, the Urgent Working Group MAY proceed with their implicit approval.
146 | 3. **Solution Identification**: The Urgent Working Group, managed by the [TODS Manager][manager], MUST identify a solution that meets the urgent need and document it as a PR to the `main` branch of the TODS Repository – outside the normal release cycle.
147 | 4. **Decision-Making**: A supermajority (two-thirds) of the Urgent Working Group members MUST approve the proposed change to meet the urgent need. If the decision is deadlocked, the decision is escalated to the [TODS Board][board].
148 | 5. **Implementation**: The rest of the implementation and release cycle mirrors the main change-making process.
149 |
150 | ## Versions and Release Management
151 |
152 | ### Releases
153 |
154 | Each change to normative content in the main branch of the TODS Repository MUST be considered a new release and assigned a version number.
155 |
156 | * Each release MUST contain one or more changes to normative content which have been approved through the change-making process.
157 | * Each release MUST be reviewed and approved in the TODS Repository by 2+ members of the [TODS Board][board] – or their designees – for accuracy and consistency with the intent of the change.
158 | * Each release MUST be tagged with its version number.
159 | * Each release MUST have documentation available.
160 | * Each release MUST have an entry in `CHANGELOG.md``.
161 | * Each release MUST be specified as a release on Github.
162 | * Each release MUST be noticed to any TODS mailing lists or discussion groups.
163 | * Each release SHOULD have sample datasets (real or exemplary) which cover the normative changes in the release.
164 |
165 | #### Pre-releases
166 |
167 | Each approved change to normative content in the develop branch of the TODS Repository MAY be considered a pre-release and assigned a pre-release version number.
168 |
169 | Pre-releases MAY be made in order to evaluate and work on incrementally-approved changes.
170 |
171 | * Each pre-release MUST contain one or more changes to normative content which have been approved through the change-making process.
172 | * Each pre-release MUST be reviewed and approved in GitHub by 1+ members of the [TODS Board][board] – or their designees – for accuracy and consistency with the changes’ intent.
173 | * Pre-releases MUST be tagged with an appropriate pre-release version number:
174 | * Pre-releases that have incorporated all the normative changes for the target-release MUST have a beta version number;
175 | * otherwise, they MUST receive an alpha version number.
176 | * Each pre-release MUST have documentation available.
177 | * Each pre-release MUST have an entry in `CHANGELOG.md``.
178 | * Each pre-release MAY be specified as a pre-release on Github.
179 |
180 | ### Release Schedule
181 |
182 | Barring significant unexpected events:
183 |
184 | * Major releases SHOULD be limited to no more than once per year;
185 | * Minor releases MAY be expected approximately quarterl .
186 |
187 | ### Version Numbering
188 |
189 | TODS Releases MUST be reflected by an incremental version number based on a semantic versioning policy as detailed below.
190 |
191 | * Release versions MUST be named with incremental increases to the format `.` where:
192 | * Major versions reflect backwards-incompatible changes
193 | * Minor versions change the normative content in a way that is backwards-compatible
194 |
195 | Pre-release versions MUST be named with the `.` of their target release name and appended with either:
196 | `-alpha.` where NUMBER starts at 1 and increases by 1 for each alpha release of that target release.
197 | `-beta.` where NUMBER starts at 1 and increases by 1 for each beta release of that target release.
198 |
199 | Non-normative changes MUST NOT increment the TODS Version Number even though they are represented by updates in the `main` branch of the [TODS Repository][repository].
200 |
201 | [governance]: ../governance.md
202 | [tods-spec]: ../governance.md#tods-specification
203 | [repository]: ../governance.md#tods-repository
204 | [manager]: ../governance.md#tods-manager
205 | [board]: ../governance.md#tods-board-of-directors
206 | [contributors]: ../governance.md#tods-contributor
207 |
--------------------------------------------------------------------------------
/docs/en/governance/policies/code-of-conduct.md:
--------------------------------------------------------------------------------
1 | # TODS Code of Conduct
2 |
3 | ## Our Pledge
4 |
5 | We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
6 |
7 | We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
8 |
9 | ## Our Standards
10 |
11 | Examples of behavior that contributes to a positive environment for our community include:
12 |
13 | * Demonstrating empathy and kindness toward other people
14 | * Being respectful of differing opinions, viewpoints, and experiences
15 | * Giving and gracefully accepting constructive feedback
16 | * Accepting responsibility and apologizing to those affected by our mistakes,
17 | and learning from the experience
18 | * Focusing on what is best not just for us as individuals, but for the overall
19 | community
20 |
21 | Examples of unacceptable behavior include:
22 |
23 | * The use of sexualized language or imagery, and sexual attention or advances of
24 | any kind
25 | * Trolling, insulting or derogatory comments, and personal or political attacks
26 | * Public or private harassment
27 | * Publishing others' private information, such as a physical or email address, without their explicit permission
28 | * Other conduct which could reasonably be considered inappropriate in a
29 | professional settin
30 |
31 | ## Enforcement Responsibilities
32 |
33 | The community leaders for this effort include the TODS Manager and the TODS Board.
34 |
35 | Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
36 |
37 | Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
38 |
39 | ## Scope
40 |
41 | This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
42 |
43 | ## Enforcement
44 |
45 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [`odstransit@gmail.com`](mailto:odstransit@gmail.com).
46 |
47 | All complaints will be reviewed and investigated promptly and fairly.
48 |
49 | All community leaders are obligated to respect the privacy and security of the reporter of any incident.
50 |
51 | ## Enforcement Guidelines
52 |
53 | Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
54 |
55 | ### 1. Correction
56 |
57 | **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
58 |
59 | **Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
60 |
61 | ### 2. Warning
62 |
63 | **Community Impact**: A violation through a single incident or series of actions.
64 |
65 | **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
66 |
67 | ### 3. Temporary Ban
68 |
69 | **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
70 |
71 | **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
72 |
73 | ### 4. Permanent Ban
74 |
75 | **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
76 |
77 | **Consequence**: A permanent ban from any sort of public interaction within the community.
78 |
79 | ## Attribution
80 |
81 | * This Code of Conduct is adapted from the TIDES Code of Conduct: https://github.com/TIDES-transit/TIDES/blob/main/CODE_OF_CONDUCT.md
82 | * The TIDES Code of Conduct was in turn influenced by the following projects:
83 | * Contributor Covenant version 2.1: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
84 | * Mozilla's code of conduct enforcement ladder: https://github.com/mozilla/diversity
85 | * For answers to common questions about this code of conduct, see the FAQ at: https://www.contributor-covenant.org/faq
86 | * Translations are available at: https://www.contributor-covenant.org/translations
87 |
--------------------------------------------------------------------------------
/docs/en/governance/policies/repository-organization-access.md:
--------------------------------------------------------------------------------
1 | # TODS Repository Organization Access Policy
2 |
3 | The [TODS Repository Organization][repository-organization], and its respective repositories and teams MUST be open and transparent to the general public to view and use under a permissive license.
4 |
5 | ## Owners
6 |
7 | The following individuals MUST be invited as [TODS Repository Organization][repository-organization] owners:
8 |
9 | - Each [TODS Board][board] member
10 | - [TODS Program Manager][program-manager]
11 |
12 | ## Contributor-Level
13 |
14 | Contributor-level capabilities to the [TODS Repository][repository] shall be considered the ability to:
15 |
16 | - Create issues
17 | - Add to discussions
18 | - Create pull-requests
19 | - Review pull-requests
20 |
21 | The [TODS Program Manager][program-manager] MUST invite the following individuals to have contributor-level capabilities:
22 |
23 | - [TODS Contributors][contributor]
24 |
25 | ## Triage-Level
26 |
27 | Triage-level capabilities to the TODS Repository shall be considered the ability to to everything in contributor-level capabilities as well as:
28 |
29 | - Assignment of tags to issues
30 | - Managing TODS Repository projects
31 | - Assigning reviewers to pull requests
32 | - Merging pull-requests that abide by branch policies
33 | - Closing pull-requests
34 | - Closing issues
35 |
36 | The [TODS Program Manager][program-manager] MAY invite the following individuals to have triage-level capabilities:
37 |
38 | - Additional individuals within the [TODS Manager][manager] organization; and
39 | - [TODS Board Coordinator][board-coordinator],
40 |
41 | [program-manager]: ../governance.md#tods-program-manager
42 | [manager]: ../governance.md#tods-manager
43 | [board-coordinator]: ../governance.md#tods-board-coordinator
44 | [repository]: ../governance.md#tods-repository
45 | [repository-organization]: ../governance.md#tods-repository-organization
46 | [contributor]: ../governance.md#tods-contributor
47 | [board]: ../governance.md#tods-board-of-directors
48 |
--------------------------------------------------------------------------------
/docs/en/index.md:
--------------------------------------------------------------------------------
1 | # Transit Operational Data Standard
2 |
3 | The Transit Operational Data Standard (TODS) is an open standard for describing how to operate scheduled transit operations which can be used to port scheduled operations between software products (e.g. scheduling systems and CAD/AVL systems), agencies, and more. TODS leverages the existing General Transit Feed Specification (GTFS) and extends it to include information about personnel and non-revenue service.
4 |
5 | View the [full TODS specification](./spec/index.md).
6 |
7 | ```mermaid
8 | graph LR
9 | subgraph Scheduling
10 | I[Schedules]
11 | M[Run Cutting]
12 | N[Bidding/Driver Assignment]
13 | M --> N
14 | end
15 | style Scheduling fill:#f4f1deff, stroke:#333, stroke-width:2px
16 | style I fill:#81b29aff,stroke:#333,stroke-width:2px
17 | style M fill:#81b29aff,stroke:#333,stroke-width:2px
18 | style N fill:#81b29aff,stroke:#333,stroke-width:2px
19 |
20 | P[GTFS Schedule]
21 | S[TODS]
22 | style P fill:#f2cc8fff,stroke:#333,stroke-width:2px
23 | style S fill:#f2cc8fff,stroke:#333,stroke-width:2px
24 |
25 | subgraph Operations
26 | R[Dispatch]
27 | end
28 | style Operations fill:#f4f1deff, stroke:#333, stroke-width:2px
29 | style R fill:#81b29aff,stroke:#333,stroke-width:2px
30 |
31 | I --> P
32 | P --> R
33 | I -->|Vehicle Blocks| M
34 | N --> S
35 | S --> R
36 | linkStyle 3 stroke:#f2cc8fff,stroke-width:4px,stroke-dasharray: 5, 5
37 | linkStyle 4 stroke:#f2cc8fff,stroke-width:4px,stroke-dasharray: 5, 5
38 |
39 | ```
40 |
41 | ## Motivation
42 |
43 | Transit providers need the systems they use to schedule and operate their service to be [interoperable](https://www.interoperablemobility.org/) so that they have the flexibility to use various software products and exchange information with other transit operators. Interoperability is best achieved through open standards. The [GTFS](https://gtfs.org) open standard successfully transmits information useful to transit riders, but is missing key concepts that are necessary for transit providers to operate the service. TODS fills this gap.
44 |
45 | TODS is an open standard which extends GTFS to define additional operational details necessary to operate the service such as deadheads and runs.
46 |
47 | !!! warning "Does TODS Data has to be Open data?"
48 |
49 | While GTFS data can and should be public so that riders can learn about service, TODS data is typically not published in order to preserve the privacy of internal operations data.
50 |
51 | While the TODS standard itself is an "open standard", this doesn't necessitate the data described in TODS to be open.
52 |
53 | ## Who uses TODS?
54 |
55 | TODS is used by transit agencies and the software which supports them including:
56 |
57 | TODS 1.0
58 |
59 | :material-check-circle: [WETA](https://weta.sanfranciscobayferry.com/)
60 |
61 | :material-check-circle: [Swiftly](https://www.goswift.ly/)
62 |
63 | :material-check-circle: [Equans Navineo](https://navineo.co/about-navineo/)
64 |
65 | :material-check-circle: [The Master Scheduler](https://themasterscheduler.com/)
66 |
67 | :material-check-circle: [Remix by Via](https://www.remix.com/)
68 |
69 | :material-check-circle: [Optibus](https://optibus.com/)
70 |
71 | :material-check-circle-outline: [Giro Hastus](https://www.giro.ca/) (on request)
72 |
73 | TODS 2.0
74 |
75 | :material-check-circle-outline: [MBTA](http://mbta.com) (in progress)
76 |
77 | ## How do I implement TODS?
78 |
79 | If you are transit agency:
80 |
81 | 1. Talk to your current Scheduling and CAD/AVL vendors or
82 | 2. Include a requirement to use TODS in your next procurement. The Mobility Data Interoperability Principles has sample text for adding TODS and other key interoperability features as RFP requirements in their [Interoperable Procurement Resource](https://www.interoperablemobility.org/procurement/).
83 |
84 | If you are vendor:
85 |
86 | 1. Review the [specification](./spec/index.md) and
87 | 2. Create an development roadmap to adopting it.
88 |
89 | Most vendors already read and write to GTFS, so this should be a marginal lift to implement.
90 |
91 | ## Citation
92 |
93 | If you use the Transit Operational Data Standard in a report or article, please cite it as follows:
94 |
95 | > Transit Operational Data Standard Working Group. 2022. Transit Operational Data Standard. Transit Operational Data Standard Board of Directors. https://ods.calitp.org.
96 |
--------------------------------------------------------------------------------
/docs/en/resources/faq.md:
--------------------------------------------------------------------------------
1 | # Frequently Asked Questions
2 |
3 | ## What is "operational data?"
4 |
5 | Operational data refers to everything a transit provider needs to know "behind the scenes" in order to provide service to riders. Operational data can include the following information:
6 |
7 | * Vehicle blocking (which vehicles run which routes)
8 | * Driver shift management (which vehicle operators work on which routes)
9 | * Vehicle shift start/end time and location (when and where vehicles pull in and out of service)
10 | * Nonrevenue vehicle service (deadheading)
11 | * Service disruptions
12 |
13 | ## Why is a standard for operational data needed?
14 |
15 | Operational data is critical for transit providers, but currently it exists primarily in proprietary formats created and maintained by various scheduling and CAD/AVL companies. The use of proprietary formats leads to wide disparities in the experiences that agencies have in trying to create a schedule and then utilizing that schedule in a CAD/AVL software. Agencies often find that their CAD/AVL and scheduling vendors prepare data in different formats, or they use different nomenclature to refer to route and stop names, which results in time-consuming manual processes to align incompatible data sources.
16 |
17 | The availability of information in the GTFS standard format has not only resulted in better information being available to riders, but it has also led to innovation in features and functionality for use by transit providers themselves. Similarly, creating a standard format for operational data will help transit providers with easier, less expensive, and enhanced scheduling functionality.
18 |
19 | ## Isn’t operational data already covered by … GTFS?
20 |
21 | Not entirely. GTFS provides what can be thought of as a rider-centric view of transit service. By that, we mean it is built around trip (or journey) planning and the information that riders need to know to complete a trip. While GTFS contains information about where vehicles should be at specified times, most transit agencies could not determine where a specific driver or operator should be at that time using a standard GTFS feed. Critical information for operators—for example, which driver is scheduled to serve a given trip, when and where to layover, or how deadheads should be completed—is not included in GTFS at present. But just because GTFS doesn’t get us all the way there, that doesn’t mean we are planning to start from scratch: TODS is intended to work with GTFS and could ultimately be developed as an extension to GTFS.
22 |
23 | ## Isn’t operational data already covered by … NeTEx/SIRI?
24 |
25 | Yes. The Network Timetable Exchange, or NeTEx, does cover use cases that are being considered for use in TODS. However, because NeTEx has no foothold in the North American market, a major, coordinated about-face in the industry would be required to move toward the NeTEx/SIRI schema. While NeTEx is one way to represent the operational data that makes up transit schedules, it is neither the only nor even necessarily the easiest way to do so. GTFS is the dominant standard in use for defining transit trips in North America, and research by the California Integrated Travel Project (Cal-ITP) has found that vendors favor GTFS’s flexible and simpler approach to representing transit data. Given the shifts that would need to occur within the industry to move toward NeTEx, Cal-ITP is privileging compatibility with GTFS and taking a GTFS-like approach to developing TODS.
26 |
27 | ## Isn’t operational data already covered by … TCIP?
28 |
29 | Yes. The Transit Communications Interface Profiles (TCIP) is a standard developed by the American Public Transportation Association approximately 20 years ago to serve as a standard interface between transit systems and the individual subsystems, like scheduling and CAD/AVL, that they rely on. TCIP has never achieved significant adoption in the United States or elsewhere and has been surpassed by the popularity of the simpler and more constrained GTFS family of standards. Without adoption, development of TCIP has not kept pace with extensions and proposed extensions of GTFS, nor with broader changes in the mobility landscape as a whole. Given the shifts that would need to occur within the industry to move toward TCIP, Cal-ITP is privileging compatibility with GTFS and taking a GTFS-like approach to developing TODS.
30 |
31 | ## What is Cal-ITP?
32 |
33 | Cal-ITP is a statewide initiative of the California State Transportation Agency (CalSTA) and the California Department of Transportation (Caltrans) to simplify travel by increasing access to public transportation—including easier, faster payments via contactless credit/debit/prepaid cards and mobile wallets on smart devices, high-quality data standards, and seamless verification of eligibility for transit discounts. Learn more at [calitp.org](https://www.calitp.org/). And visit Cal-ITP's [CAMobilityMarketplace.org](https://www.camobilitymarketplace.org/) for a catalog of code-compliant products and services for transit agencies.
34 |
35 | ## What is the TODS Working Group?
36 |
37 | The Transit Operational Data Standard working group was convened by staff from the California Integrated Travel Project (Cal-ITP) as part of its goal to provide complete, accurate, and up-to-date transit data to customers and respective agencies. Working group members include major transit agencies across the United States and many of the largest transit software companies in North America. Visit our [Working Group page](../resources/faq.md#what-is-the-tods-working-group) for a full list of members.
38 |
39 | ## Why is Cal-ITP leading this effort?
40 |
41 | Cal-ITP developed the TODS initiative in response to feedback from local transit providers and vendors. As Cal-ITP has as its core a mission to improve the quality of mobility data and increase the efficiency of transportation service delivery in the state of California, we have conducted research and conversations with an eye toward identifying existing pain points. The gap that exists between scheduling software and CAD/AVL software was identified by respondents as a major source of friction. Even as GTFS has seen increasingly widespread adoption, operational data is subject to proprietary formats, overlapping use cases, and manual processes that inefficiently transfer data from one system to another. Cal-ITP’s conversations with partners have demonstrated that there is a clear desire among vendors and transit providers to come together around a standard representation of operational data built in the GTFS model.
42 |
43 | ## Have more questions?
44 |
45 | For additional information, please email [hello@calitp.org Attn: Scott Frazier / TODS](mailto:hello@calitp.org?subject=Scott Frazier / TODS).
46 |
--------------------------------------------------------------------------------
/docs/en/resources/implementation-guide.md:
--------------------------------------------------------------------------------
1 | # TODS Implementation Guide
2 |
3 | Forthcoming.
4 |
--------------------------------------------------------------------------------
/docs/en/resources/resources.md:
--------------------------------------------------------------------------------
1 | # Handouts + Presentations
2 |
3 | Forthcoming.
4 |
--------------------------------------------------------------------------------
/docs/en/spec/examples.md:
--------------------------------------------------------------------------------
1 | # Examples
2 |
3 | The following sections provide examples of how TODS can represent specific use cases. The inclusion of these examples should not
4 | be as an indication that this is the only way to represent these use cases with TODS. If you have questions about a use case not
5 | represented here, please feel free to [create an issue in GitHub](https://github.com/cal-itp/operational-data-standard/issues/new).
6 |
7 | ## Single Run with Pull-Out and Lunch Break
8 |
9 | In this example, a bus driver is assigned to run 10000, which has four revenue trips on two pieces, all on the same block. The run also includes a pull-out, a pull-back, a pre-trip inspection, and a lunch break between the two pieces.
10 |
11 | 
12 |
13 | ### GTFS Files
14 |
15 | These are the same files that would be published in the agency's public GTFS file, and contains only revenue trips and public information.
16 |
17 | Some irrelevant files are ommitted for brevity.
18 |
19 | #### `stops.txt`
20 |
21 | ```csv
22 | stop_id,location_type
23 | stop-1,0
24 | stop-2,0
25 | stop-3,0
26 | ```
27 |
28 | #### `routes.txt`
29 |
30 | ```csv
31 | route_id,route_short_name,route_type
32 | 12,12,3
33 | ```
34 |
35 | #### `trips.txt`
36 |
37 | ```csv
38 | route_id,service_id,trip_id,trip_headsign,direction_id,block_id
39 | 12,daily,101,North,0,BLOCK-A
40 | 12,daily,102,South,1,BLOCK-A
41 | 12,daily,103,North,0,BLOCK-A
42 | 12,daily,104,South,1,BLOCK-A
43 | ```
44 |
45 | #### `stop_times.txt`
46 |
47 | ```csv
48 | trip_id,arrival_time,stop_id,stop_sequence
49 | 101,10:00,stop-1,1
50 | 101,10:25,stop-2,2
51 | 101,10:50,stop-3,3
52 | 102,11:00,stop-3,1
53 | 102,11:25,stop-2,2
54 | 102,11:50,stop-1,3
55 | 103,13:00,stop-1,1
56 | 103,13:25,stop-2,2
57 | 103,13:50,stop-3,3
58 | 104,14:00,stop-3,1
59 | 104,14:25,stop-2,2
60 | 104,14:50,stop-1,3
61 | ```
62 |
63 | ### TODS Files
64 |
65 | These are the new files that are published in TODS. In this example, the TODS files do not delete or modify any rows that were published in GTFS.
66 |
67 | #### `stops_supplement.txt`
68 |
69 | ```csv
70 | stop_id,location_type,TODS_location_type
71 | garage,0,garage
72 | garage-waypoint,0,
73 | ```
74 |
75 | #### `routes_supplement.txt`
76 |
77 | ```csv
78 | route_id,route_long_name
79 | deadheads,Deadheads
80 | ```
81 |
82 | In this example, the agency puts all of its deadheads on this new route, though agencies may have other ways to assign deadheads to routes.
83 |
84 | #### `trips_supplement.txt`
85 |
86 | ```csv
87 | route_id,service_id,trip_id,block_id,TODS_trip_type
88 | deadheads,daily,deadhead-1,BLOCK-A,pull-out
89 | deadheads,daily,deadhead-2,BLOCK-A,pull-back
90 | ```
91 |
92 | In this example, consumers know that these trips aren't in revenue service because of the `route_id` and `TODS_trip_type`.
93 |
94 | #### `stop_times_supplement.txt`
95 |
96 | ```csv
97 | trip_id,arrival_time,stop_id,stop_sequence
98 | deadhead-1,09:45:00,garage,1
99 | deadhead-1,09:50:00,garage-waypoint,2
100 | deadhead-1,09:55:00,stop-1,3
101 | deadhead-2,14:50:00,stop-1,1
102 | deadhead-2,14:55:00,garage-waypoint,2
103 | deadhead-2,15:00:00,garage,3
104 | ```
105 |
106 | #### `run_events.txt`
107 |
108 | ```csv
109 | service_id,run_id,event_sequence,piece_id,block_id,job_type,event_type,trip_id,start_location,start_time,start_mid_trip,end_location,end_time,end_mid_trip
110 | daily,10000,10, , ,Operator,Report Time, ,garage,09:30:00,,garage,09:30:00,
111 | daily,10000,20, , ,Operator,Pre-Trip Inspection,,garage,09:35:00,,garage,09:45:00,
112 | daily,10000,30,10000-1,BLOCK-A,Operator,Pull-Out,deadhead-1 ,garage,09:45:00,2,stop-1,09:55:00,2
113 | daily,10000,40,10000-1,BLOCK-A,Operator,Operator,101 ,stop-1,10:00:00,2,stop-3,10:50:00,2
114 | daily,10000,50,10000-1,BLOCK-A,Operator,Operator,102 ,stop-3,11:00:00,2,stop-1,11:50:00,2
115 | daily,10000,60, , ,Operator,Break, ,stop-1,11:50:00,,stop-1,13:00:00,
116 | daily,10000,70,10000-2,BLOCK-A,Operator,Operator,103 ,stop-1,13:00:00,2,stop-3,13:50:00,2
117 | daily,10000,80,10000-2,BLOCK-A,Operator,Operator,104 ,stop-3,14:00:00,2,stop-1,14:50:00,2
118 | daily,10000,90,10000-2,BLOCK-A,Operator,Pull-Back,deadhead-2,stop-1,14:50:00,2,garage,15:00:00,2
119 | ```
120 |
121 | ## Multiple Runs on a Single Block with Mid-Trip Relief
122 |
123 | In this example, the bus driver assigned to run 10000 pulls out a bus, does trip 101 and part of trip 102, and then ends their day at `stop-2`. A new driver on run 20000 boards the bus, completes trip 102, then does trip 103 and trip 104, and pulls back to the garage.
124 |
125 | 
126 |
127 | This example uses the [exact same GTFS files as the previous example](#gtfs-files). Deadheads and nonrevenue locations are omitted in order to focus on the revenue trip assignments, so no `_supplement.txt` files are needed for this example. Only `run_events.txt` needs to change to reflect the multiple runs and mid-trip relief.
128 |
129 | ### `run_events.txt`
130 |
131 | ```csv
132 | service_id,run_id,event_sequence,piece_id,block_id,job_type,event_type,trip_id,start_location,start_time,start_mid_trip,end_location,end_time,end_mid_trip
133 | daily,10000,10,10000-1,BLOCK-A,Operator,Operator,101,stop-1,10:00:00,2,stop-3,10:50:00,2
134 | daily,10000,20,10000-1,BLOCK-A,Operator,Operator,102,stop-3,11:00:00,2,stop-2,11:25:00,1
135 | daily,20000,10,20000-1,BLOCK-A,Operator,Operator,102,stop-2,11:25:00,1,stop-1,11:50:00,2
136 | daily,20000,20,20000-1,BLOCK-A,Operator,Operator,103,stop-1,13:00:00,2,stop-3,13:50:00,2
137 | daily,20000,30,20000-1,BLOCK-A,Operator,Operator,104,stop-3,14:00:00,2,stop-1,14:50:00,2
138 | ```
139 |
140 | ## Multiple operators on the same trip
141 |
142 | In this example (unrelated to the previous examples), a two-car train does a round trip, and requires two operators, one in the first car and one in the second car. The `event_type` field distinguishes whether an operator is in the front car or the rear car. The operators swap for the return trip.
143 |
144 | ### `run_events.txt`
145 |
146 | ```csv
147 | service_id,run_id,event_sequence,job_type,event_type,trip_id,start_location,start_time,end_location,end_time
148 | weekday,10000,10,Operator,Operate 1st Car,trip-1,stop-1,10:00:00,stop-2,10:58:00
149 | weekday,10000,20,Operator,Operate 2nd Car,trip-2,stop-2,11:00:00,stop-1,11:58:00
150 | weekday,20000,10,Operator,Operate 2nd Car,trip-1,stop-1,10:00:00,stop-2,10:58:00
151 | weekday,20000,20,Operator,Operate 1st Car,trip-2,stop-2,11:00:00,stop-1,11:58:00
152 | ```
153 |
154 | ## Run as Directed work
155 |
156 | In this example (unrelated to the previous examples), an operator signs in for their shift, pulls out, and then operates a bus for several hours. They are not scheduled to do specific trips, but instead do trips as directed to by dispatch. This approach could apply in several situations:
157 |
158 | - An agency uses `frequencies.txt` (`frequencies.trip_id` may be able to be referenced in `run_events.trip_id`).
159 | - An agency publishes specific times in GTFS `trips.txt`, but in practice operates the service according to a headway, or doesn't schedule operators to specific trips.
160 | - The operator is assigned to cover or strategic work, and is positioned somewhere where they can cover absences or gaps in service on any route throughout the day.
161 |
162 | ### `run_events.txt`
163 |
164 | ```csv
165 | service_id,run_id,event_sequence,block_id,event_type,trip_id,start_location,start_time,end_location,end_time
166 | weekday,10000,10, ,sign-in ,,garage,08:45:00,garage,08:50:00
167 | weekday,10000,20,BLOCK-A,deadhead ,,garage,08:50:00,stop-1,09:00:00
168 | weekday,10000,30,BLOCK-A,run-as-directed,,stop-1,09:00:00,stop-1,12:00:00
169 | weekday,10000,30,BLOCK-A,deadhead ,,stop-1,12:00:00,garage,12:10:00
170 | ```
171 |
172 | ## Employee Assignments
173 |
174 | This example uses [`employee_run_dates.txt`](index.md#employee_run_datestxt) to assign employees to runs (and trips).
175 |
176 | In this example, `A` and `B` work Monday-Wednesday and Sunday. `C` and `D` work Thursday-Saturday.
177 |
178 | On Wedneday, July 3, `A` has scheduled vacation, so a substitute is assigned instead.
179 |
180 | **[`calendar.txt`](https://gtfs.org/documentation/schedule/reference/#calendartxt)**
181 |
182 | ```csv
183 | service_id,monday,tuesday,wednesday,thursday,friday,saturday,sunday,start_date,end_date
184 | weekday,1,1,1,1,1,0,0,20240701,20240707
185 | weekend,0,0,0,0,0,1,1,20240701,20240707
186 | ```
187 |
188 | July 1, 2024 was a Monday.
189 |
190 | **[`run_events.txt`](index.md#run_eventstxt)**
191 |
192 | For this example, the purpose of this file is just to show which runs exist. Real runs would have more interesting data.
193 |
194 | ```csv
195 | service_id,run_id,event_sequence,event_type,trip_id,start_location,start_time,end_location,end_time
196 | weekday,101,1,work,trip1,station,09:00:00,station,17:00:00
197 | weekday,102,1,work,trip2,station,09:00:00,station,17:00:00
198 | weekend,103,1,work,trip3,station,09:00:00,station,17:00:00
199 | weekend,104,1,work,trip4,station,09:00:00,station,17:00:00
200 | ```
201 |
202 | **[`employee_run_dates.txt`](index.md#employee_run_datestxt)**
203 |
204 | ```csv
205 | date,service_id,run_id,employee_id
206 | 20240701,weekday,101,A
207 | 20240701,weekday,102,B
208 | 20240702,weekday,101,A
209 | 20240702,weekday,102,B
210 | 20240703,weekday,101,A
211 | 20240703,weekday,102,B
212 | 20240704,weekday,101,C
213 | 20240704,weekday,102,D
214 | 20240705,weekday,101,C
215 | 20240705,weekday,102,D
216 | 20240706,weekend,103,C
217 | 20240706,weekend,104,D
218 | 20240707,weekend,103,A
219 | 20240707,weekend,104,B
220 | ```
221 |
--------------------------------------------------------------------------------
/docs/en/spec/examples/mid-trip-relief-diagram.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MobilityData/operational-data-standard/abcee7c5901f82cf419a0fc9977f45e347450462/docs/en/spec/examples/mid-trip-relief-diagram.png
--------------------------------------------------------------------------------
/docs/en/spec/examples/single-run-diagram.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MobilityData/operational-data-standard/abcee7c5901f82cf419a0fc9977f45e347450462/docs/en/spec/examples/single-run-diagram.png
--------------------------------------------------------------------------------
/docs/en/spec/index.md:
--------------------------------------------------------------------------------
1 |
2 | # Reference
3 |
4 | The Transit Operational Data Standard was last updated on April 3, 2024 (v2.0 DRAFT). View the full [revision history](./revision-history.md).
5 |
6 | ## Dataset Files
7 |
8 | ### Structure
9 |
10 | There are two types of files used in the TODS standard:
11 |
12 | - **Supplement files**, used to add, modify, and delete information from public GTFS files to model the operational service for internal purposes (with a `_supplement` filename suffix).
13 | - **TODS-Specific files**, used to model operational elements not currently defined in the GTFS standard.
14 |
15 | All files are optional.
16 |
17 | ### Files
18 |
19 | | **File Name** | **Type** | **Description** |
20 | | --- | --- | --- |
21 | | trips_supplement.txt | Supplement | Supplements and modifies GTFS [trips.txt](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#tripstxt) with deadheads and other non-public trip information. |
22 | | stops_supplement.txt | Supplement | Supplements and modifies GTFS [stops.txt](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#stopstxt) with internal stop locations, waypoints, and other non-public stop information.|
23 | | stop_times_supplement.txt | Supplement | Supplements and modifies GTFS [stop_times.txt](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#stop_timestxt) with non-public times at which trips stop at locations, `stop_times` entries for non-public trips, and related information. |
24 | | routes_supplement.txt | Supplement | Supplements and modifies GTFS [routes.txt](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md#routestxt) with internal route identifiers and other non-public route identification. |
25 | | run_events.txt | TODS-Specific | Lists all trips and other scheduled activities to be performed by a member of personnel during a run. |
26 | | employee_run_dates.txt | TODS-Specific | Assigns employees to runs. |
27 |
28 | _The use of the Supplement standard to modify other GTFS files is not yet formally adopted into the specification and remains subject to change. Other files may be formally adopted in the future._
29 |
30 | ## Supplement Files
31 |
32 | ### Structure
33 |
34 | The fields in all Supplement files match those defined in the corresponding file's [GTFS specification](https://github.com/google/transit/blob/master/gtfs/spec/en/reference.md).
35 |
36 | The overall premise is to update and add data to GTFS, which is accomplished by either updating matching values or adding rows entirely.
37 |
38 | Each entry in a Supplement file is paired with its matching entry in the corresponding GTFS file using the [GTFS file's Primary Key](https://gtfs.org/schedule/reference/#dataset-attributes), i.e. the fields that uniquely identify the row. If no match is found, the Supplement file's entry is added to the GTFS file in its entirety.
39 |
40 | The standard also supports the removal of rows in their entirety.
41 |
42 | ### Evaluation
43 |
44 | Each row in a Supplement file shall be evaluated as follows:
45 |
46 | 1. If the row's Primary Key is defined in the corresponding GTFS file, and the `TODS_delete` field is defined and equal to `1`, remove the corresponding row from the GTFS file.
47 | 2. If the row's Primary Key is defined in the corresponding GTFS file, and the `TODS_delete` field is not defined or not equal to `1`, set or update any fields with defined values in the Supplement file to those values in the corresponding GTFS file.
48 | 3. If the row's Primary Key is NOT defined in the corresponding GTFS file, add the row to the corresponding GTFS file.
49 |
50 | In other words, where a Primary Key matches, the row is either removed or any non-empty values in the row are used to _update_ the corresponding GTFS values. Where a Primary Key match does not exist, the entire row is added.
51 |
52 | ### Example
53 |
54 | GTFS `stops.txt`:
55 |
56 | ```csv
57 | stop_id,stop_name,stop_desc,stop_url
58 | 1,One,Unmodified in TODS,example.com/1
59 | 2,Two,Deleted in TODS,example.com/2
60 | 3,Three,Will be modified in TODS,example.com/3
61 | ```
62 |
63 | TODS `stops_supplement.txt`:
64 |
65 | ```CSV
66 | stop_id,stop_name,stop_desc,TODS_delete
67 | 2,,,1
68 | 3,,Has been modified by TODS,
69 | 4,Four,New in TODS,
70 | ```
71 |
72 | Effective `stops.txt` after merging the supplement file:
73 |
74 | ```CSV
75 | stop_id,stop_name,stop_desc,stop_url
76 | 1,One,Unmodified in TODS,example.com/1
77 | 3,Three,Has been modified by TODS,example.com/3
78 | 4,Four,New in TODS,
79 | ```
80 |
81 | _Note that the station name "Three" was not modified, and the whole column stop_url was omitted and not modified._
82 |
83 | ### Implications and Guidance
84 |
85 | - As blank fields are ignored, data to be removed should either be overwritten with a new value or have their entire row deleted using the `TODS_delete` field.
86 | - As processing of files is non-sequential, it is prohibited to both delete and re-add a row with identical Primary Keys in the same Supplement file.
87 | - If a row contains defined values besides the Primary Key and a `TODS_delete` value of `1`, the row shall be removed and other values in that row will be ignored.
88 | - When adding rows and updating values, be certain to ensure the values are being updated based on their column values (e.g. if GTFS has fields of `trip_id,route_id,trip_short_name` and the TODS Supplement file has fields of `trip_id,trip_short_name`, be certain that values are mapping to the correct fields without assuming column headers are identical).
89 | - When deleting a row in a file, any references to that field/value shall be ignored. Thus, it is important to ensure references to that row are either redefined or are being intentionally omitted. For example:
90 | - When deleting a trip via `trips_supplement.txt`, all of that trip's entires in `stop_times.txt` will not be associated with a valid trip and would thus be ignored.
91 | - When deleting a route via `routes_supplement.txt`, all trips using that route would not be associated with a valid route and would thus be ignored _UNLESS_ the `route_id` on the affected trips is updated via the `trips_supplement.txt` file.
92 | - After modifying static GTFS content to incorporate the TODS Supplement modifications, the resulting data ("TODS-Supplemented GTFS") should form a valid GTFS dataset, with the limited exception of missing data that should be ignored per the above.
93 |
94 | ### TODS-Specific Fields
95 |
96 | In addition to the fields defined in GTFS, specific fields for use within TODS are denoted by a `TODS_` field prefix.
97 |
98 | | **File** | **Field Name** | **Type** | **Required** | **Description** |
99 | | --- | --- | --- | --- | --- |
100 | | Any Supplement file | `TODS_delete` | Enum | Optional | (blank) - Update other fields; do not delete. `1` - Deletes the GTFS row in the corresponding file whose Primary Key matches the value in the Supplement file's row. |
101 | | `trips_supplement.txt` | `TODS_trip_type` | Text | Optional | Defines the type of the trip if distinct from a standard revenue trip. |
102 | | `stops_supplement.txt` | `TODS_location_type` | Text | Optional | Defines the type of the location if distinct from a standard GTFS location type. Where defined, the GTFS `location_type` shall be ignored. |
103 |
104 | ## TODS-Specific File Definitions
105 |
106 | ### `run_events.txt`
107 |
108 | Primary Key: (`service_id`, `run_id`, `event_sequence`)
109 |
110 | | **Field Name** | **Type** | **Required** | **Description** |
111 | | --- | --- | --- | --- |
112 | | `service_id` | ID referencing `calendar.service_id` or `calendar_dates.service_id` | Required | Identifies a set of dates when the run is scheduled to take place. |
113 | | `run_id` | ID | Required | A run is uniquely determined by a `service_id`, `run_id` pair. Runs with the same `run_id` on different `service_id`s are considered different runs. |
114 | | `event_sequence` | Non-negative integer | Required | The order of this event within a run. Must be unique within one (`service_id`, `run_id`). See [more detail below](#event_sequence-and-event-times) about how order is defined. |
115 | | `piece_id` | ID | Optional | Identifies the piece within the run that the event takes place.
May be blank if the event takes place out of a piece, like a break, or if the agency does not use piece IDs. |
116 | | `block_id` | ID referencing `trips.block_id` | Optional | Identifies the block to which the run event belongs.
This field is always optional. May exist even if `trip_id` does not (e.g. if an event represents a run-as-directed block with no scheduled trips). May exist even if `trip_id` exists and the associated trip in `trips.txt` doesn't have a `block_id`. May be omitted even if `trip_id` exists and the associated trip in `trips.txt` has a `block_id`.
If `block_id` is set, `trip_id` is set, and the associated trip in `trips.txt` has a `block_id`, then the two `block_id`s must not be different. |
117 | | `job_type` | Text | Optional | The type of job that the employee is doing, in a human-readable format. e.g. "Assistant Conductor". Producers may use any values, but should be consistent.
A single run may include more than one `job_type` throughout the day if the employee has multiple responsibilities, e.g. an "Operator" in the morning and a "Shifter" in the afternoon. |
118 | | `event_type` | Text | Required | The type of event that the employee is doing, in a human-readable format. e.g. "Sign-in". Producers may use any values, but should be consistent. Consumers may ignore events with an `event_type` that they don't recognize. |
119 | | `trip_id` | ID referencing `trips.trip_id` | Optional | If this run event corresponds to working on a trip, identifies that trip. |
120 | | `start_location` | ID referencing `stops.stop_id` | Required | Identifies where the employee starts working this event.
If `trip_id` is set (and `mid_trip_start` is not `1`), this should be the `stop_id` of the first stop of the trip in `stop_times.txt` (after applying any trip supplement). If `start_mid_trip` is `1`, this should be the location where the employee starts working, matching a `stop_id` in the middle of the supplemented trip. |
121 | | `start_time` | Time | Required | Identifies the time when the employee starts working this event.
If `trip_id` is set (and `mid_trip_start` is not `1`), this corresponds to the time of the first stop of the trip in `stop_times.txt` (after applying any trip supplement). If `start_mid_trip` is `1`, this time corresponds to a stop time in the middle of the supplemented trip, when the employee starts working on the trip. Note that this time may not exactly match `stop_times.txt` `arrival_time` or `departure_time` if the employee is considered to be working for a couple minutes before the trip departs. This field is about when the employee is working, and consumers who care about the the trip times should check `stop_times.txt` instead. |
122 | | `start_mid_trip` | Enum | Optional | Indicates whether the event begins at the start of the trip or in the middle of the trip (after applying any trip supplement).
`0` (or blank) - Run event is not associated with a trip, or no information about whether the run event starts mid-trip `1` - Run event starts mid-trip `2` - Run event does not start mid-trip |
123 | | `end_location` | ID referencing `stops.stop_id` | Required | Identifies where the employee stops working this event.
If `trip_id` is set (and `mid_trip_end` is not `1`), this should be the `stop_id` of the last stop of the trip in `stop_times.txt` (after applying any trip supplement). If `end_mid_trip` is `1`, this should be the location where the employee stops working, matching a `stop_id` in the middle of the supplemented trip. |
124 | | `end_time` | Time | Required | Identifies the time when the employee stops working this event.
If `trip_id` is set (and `mid_trip_end` is not `1`), this corresponds to the time of the last stop of the trip in `stop_times.txt` (after applying any trip supplement). If `end_mid_trip` is `1`, this time corresponds to a stop time in the middle of the supplemented trip, when the employee stops working on the trip. Note that this time may not exactly match `stop_times.txt` `arrival_time` or `departure_time` if the employee is considered to be working for a couple minutes after the trip finishes. This field is about when the employee is working, and consumers who care about the the trip times should check `stop_times.txt` instead. |
125 | | `end_mid_trip` | Enum | Optional | Indicates whether the event ends at the end of the trip or in the middle of the trip (after applying any trip supplement).
`0` (or blank) - Run event is not associated with a trip, or no information about whether the run event ends mid-trip `1` - Run event ends mid-trip `2` - Run event does not end mid-trip |
126 |
127 | #### `event_sequence` and Event Times
128 |
129 | `event_sequence` is required and unique within a run so it can be used in the Primary Key to uniquely identify events.
130 |
131 | Within one run, `event_sequence` values should increase throughout the day but do not have to be consecutive.
132 |
133 | Within one run, if two events both have `trip_id` set, they must not overlap in time (based on `start_time` and `end_time`). Employees cannot be on two trips at once, or have multiple duties on the same trip at the same time. Having a zero-minute overlap is allowed, to allow consecutive trips without layovers, and to allow trips with 0-minute durations, which some agencies use for bookkeeping reasons.
134 |
135 | Events that don't have `trip_id` set may overlap in time with any other events. This is to allow events that represent a large portion of a day (such as time that an employee is available to work), regardless of what other duties or trips they have during that time.
136 |
137 | Because some events may overlap in time, it may not be possible to choose a single order for events within a run that's correct for all uses. Producers should use `event_sequence` to define a reasonable order. If a consumer cares about exactly how overlapping events are ordered, they should sort based on the time fields and `event_type` instead.
138 |
139 | #### Run ID Uniqueness
140 |
141 | Run IDs may be non-unique. E.g. E.g. there may be a "Run 100" on both Weekday and Weekend service. There may even be a Run 100 on both `garage1-weekday` and `garage2-weekday` services, happening on the same day. Runs are uniquely referred to by a `(service_id, run_id)` pair. This is why the service ID is required on this file and other files that refer to run IDs.
142 |
143 | #### `run_events` Notes
144 |
145 | - Multiple `run_event`s may refer to the same `trip_id`, if multiple employees work on that trip.
146 | - Events may have gaps between the end time of one event and the start time of the next. e.g. if an operator's layovers aren't represented by an event.
147 | - `start_time` may equal `end_time` for an event that's a single point in time (such as a report time) without any duration.
148 | - Recommended sort order: `service_id`, `run_id`, `event_sequence`.
149 |
150 | ### `employee_run_dates.txt`
151 |
152 | Describes which employees are scheduled to which runs on which dates.
153 |
154 | This file should represent the schedule after holidays, vacations, and other scheduled exceptions have been applied.
155 |
156 | Each run and date combination may appear 0 times in this file (if there's no assigned employee), 1 time, or multiple times (if multiple employees are assigned to the same run on the same date).
157 |
158 | Primary Key: `*`
159 |
160 | | **Field Name** | **Type** | **Required** | **Description** |
161 | | --- | --- | --- | --- |
162 | | `date` | Date | Required | Service date. |
163 | | `service_id` | ID referencing [`run_events.txt`](#run_eventstxt) | Required | Part of the Run ID, which is refered to as `(service_id, run_id)`. See [Run ID Uniqueness](#run-id-uniqueness). |
164 | | `run_id` | ID referencing [`run_events.txt`](#run_eventstxt) | Required | The run that's added to this employee's schedule. |
165 | | `employee_id` | ID | Required | References an agency's external systems. Employee IDs are not used elsewhere in TODS. |
166 |
--------------------------------------------------------------------------------
/docs/en/spec/revision-history.md:
--------------------------------------------------------------------------------
1 | # Revision History
2 |
3 | ## 24 July 2025
4 |
5 | TODS 2.0.0 is adopted, now to be implemented.
6 |
7 | ## 20 June 2024
8 |
9 | TODS v2.0.0-alpha.1 is adopted.
10 |
11 | * Removes files `deadheads.txt`, `ops_locations.txt`, `deadhead_times.txt`.
12 | * Adds new files `trips_supplement.txt`, `stops_supplement.txt`, `stop_times_supplement.txt`, and `routes_supplement.txt`.
13 | * Allows for supplementation, modification, and/or deletion of data in existing GTFS feed.
14 |
15 | ## 3 May 2022
16 |
17 | TODS v1.0.0 is adopted by the TODS Working Group
18 |
--------------------------------------------------------------------------------
/mlc_config.json:
--------------------------------------------------------------------------------
1 | // config file for markdown-link-check
2 | // see: https://github.com/tcort/markdown-link-check
3 | {
4 | "ignorePatterns": [
5 | {
6 | "pattern": "localhost"
7 | }
8 | ]
9 | }
10 |
--------------------------------------------------------------------------------
/overrides/assets/images/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MobilityData/operational-data-standard/abcee7c5901f82cf419a0fc9977f45e347450462/overrides/assets/images/favicon.ico
--------------------------------------------------------------------------------
/overrides/assets/images/ods-small-eggshell.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/MobilityData/operational-data-standard/abcee7c5901f82cf419a0fc9977f45e347450462/overrides/assets/images/ods-small-eggshell.png
--------------------------------------------------------------------------------
/overrides/assets/stylesheets/ods.css:
--------------------------------------------------------------------------------
1 | /* Define CSS variables based on theme colors */
2 |
3 | /* Palette source: https://coolors.co/palette/f4f1de-e07a5f-3d405b-81b29a-f2cc8f*/
4 | :root {
5 | --md-primary-fg-color: #3d405bff;/*delft-blue*/
6 | --md-accent-fg-color: #81b29aff; /*cambridge-blue*/
7 | --md-primary-bg-color: #f4f1deff; /*eggshell*/
8 | --text-color: #3d405bff; /*delft-blue:*/
9 | --md-code-hl-color: #e07a5fff; /*burnt-sienna*/
10 | --highlight-outline: #f2cc8fff; /*sunset*/
11 | }
12 |
13 | .md-header__button.md-logo img, .md-header__button.md-logo svg {
14 | height: 2.5rem;
15 | }
16 |
17 | .md-header {
18 | overflow: visible; /* Allow overflow */
19 | background-color: var(--md-primary-fg-color);
20 | }
21 |
22 | .md-footer {
23 | background-color: var(--text-color);
24 | color: var(--md-default-bg-color);
25 | }
26 |
27 | .md-tabs {
28 | position: relative; /* Make sure .md-tabs is positioned */
29 | overflow: visible; /* Allow overflow */
30 | margin-bottom: 60px;
31 | }
32 |
33 | /* Body and Link Styling for Readability */
34 | body {
35 | font-family: 'Roboto', sans-serif;
36 | color: var(--text-color);
37 | background-color: var(--md-primary-bg-color);
38 | }
39 |
40 | a:hover {
41 | color: var(--md-accent-fg-color); /* Sky Blue on hover */
42 | }
43 |
44 | /* Code Block Styling */
45 | code {
46 | background-color: var(--md-accent-fg-color); /* No border for a cleaner look */
47 | }
48 |
49 | /* Table Styling */
50 | table {
51 | border-collapse: collapse;
52 | width: 100%;
53 | }
54 |
55 | th, td {
56 | border: 1px solid var(--md-primary-fg-color);
57 | padding: 8px;
58 | text-align: left;
59 | }
60 |
61 | th {
62 | background-color: var(--md-primary-fg-color);
63 | color: var(--md-default-bg-color);
64 | }
65 |
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
1 | fontawesome_markdown==0.2.6
2 | mkdocs==1.6.1
3 | mkdocs-awesome-pages-plugin==2.10.1
4 | mkdocs-macros-plugin==1.3.7
5 | mkdocs-material==9.6.14
6 | mkdocs-material-extensions==1.3.1
7 | mkdocstrings==0.29.1
8 |
--------------------------------------------------------------------------------