You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Optional Stanzas and Tags](#optional-stanzas-and-tags)
13
14
-[License](#license)
14
15
-[Authentication](#authentication)
15
16
-[Tags](#tags)
17
+
-[Languages](#languages)
18
+
-[Superceding lineage](#superceding-lineage)
16
19
17
20
## Introduction
18
21
19
22
This is a set of guidelines for data publishers providing machine readable lists of their feeds _and_ for data aggregation platforms providing machine readable lists of their feed contents to each other. This project is rooted in publishing and sharing lists of GTFS feeds for fixed-route public-transit networks. It's also applicable to real-time transit, bike-share, e-scooter, and other mobility datasets that take the form of "feeds" published at stable URLs:
1.**Publishers provide their own small registries** To provide data creators (e.g., transit agencies and data vendors) a means of posting a list of their public feeds online. The format should be light-weight (no server required to power an API). The registry should also be machine readable, making it simple for data aggregation platforms to automatically recognize and consume newly added feeds.
29
32
2.**Aggregator platforms share their registries** To provide data aggregation platforms (e.g., Transitland, OpenMobilityData, Navitia) a means of sharing their feed registries with each other. Each platform may have a particular focus in terms of functionality provided on top of their feed registries. By distributing feed lists among any and all platforms, open data is shared my widely and the burden of data curation is (hopefully) reduced for each platform.
30
-
3.**Related feeds are linked** Different feed types reference each other (e.g., GTFS-realtime references a static GTFS feed, an MDS e-scooter feed references a GBFS bike-share feed). This registry format will provide a light-weight means for data publishers and aggregator platforms to identify these linkages.
33
+
3.**Related feeds are linked** Different feed types reference each other (e.g., GTFS Realtime references a static GTFS feed, an MDS e-scooter feed references a GBFS bike-share feed). This registry format will provide a light-weight means for data publishers and aggregator platforms to identify these linkages.
31
34
4.**Put it into practice and experiment**
32
35
-~~The more contributors to these guidelines, the better! Let's consider many options and discuss the pros/cons of each of the registry specifics. Let's also be pragmatic. Our goal at Transitland will be to implement this registry format for both incoming feed submissions (to complement the existing Transitland Feed Registry [add a feed](https://transit.land/documentation/feed-registry/add-a-feed.html) process) and outputting lists of known feeds (the Datastore API [feeds endpoint](https://transit.land/documentation/datastore/feeds.html)).~~
33
36
- DMFR now powers the new [Transitland Atlas](https://github.com/transitland/transitland-atlas), which is the source of truth for both Transitland v1 and [Transitland v2](https://transit.land/news/2019/10/17/tlv2.html)'s Feed Registry.
@@ -41,91 +44,59 @@ The stands on the shoulders of:
"name":"West Virginia University Morgantown Personal Rapid Transit",
157
+
"short_name":"WVU PRT",
158
+
"website":"http://transportation.wvu.edu/"
159
+
}
160
+
]
161
+
}
162
+
],
163
+
"license_spdx_identifier":"CDLA-Permissive-1.0"
164
+
}
165
+
```
166
+
167
+
The root-level `operators` array is typically used when:
168
+
- An operator has three or more feeds
169
+
- You want to organize feeds across multiple files
170
+
171
+
The nested `operators` array within a feed is typically used when:
172
+
- There is a one-to-one relationship between a feed and an operator
173
+
- You want to keep the feed and operator information together for simplicity
174
+
175
+
Note: The `name` field is required for operators, while `short_name` and `website` are optional.
176
+
165
177
## Fields
166
178
167
179
### IDs
168
180
169
-
Feed IDs can be any strings that are unique with a given DMFR file. These feed IDs can be [Onestop IDs](https://transit.land/documentation/onestop-id-scheme/), although that is not required by the DMFR spec. In the [Transitland Atlas](https://github.com/transitland/transitland-atlas) repository, DMFR files are required to use Onestop IDs.
181
+
Feed IDs can be any strings that are unique with a given DMFR file. These feed IDs can be [Onestop IDs](https://transit.land/documentation/onestop-id-scheme/), although that is not required by the DMFR spec.
182
+
183
+
In the [Transitland Atlas](https://github.com/transitland/transitland-atlas) repository, DMFR files are required to use Onestop IDs.
184
+
185
+
### Feed specs and URLs
186
+
187
+
Each feed must specify a `spec` field that indicates the type of data contained in the feed. The following specs are supported, along with the following urls:
188
+
189
+
-`gtfs`: Static GTFS feed containing schedule data
190
+
-`static_current`: URL for the current version of the feed
191
+
-`static_historic`: Array of URLs for previous versions of the feed
192
+
-`static_planned`: Array of URLs for future service changes
193
+
-`static_hypothetical`: Array of URLs for potential future scenarios
-`gbfs_auto_discovery`: URL for GBFS auto-discovery file that links to all other GBFS files
202
+
203
+
-`mds`: MDS (Mobility Data Specification) feed
204
+
-`mds_provider`: URL for MDS provider API endpoints
170
205
171
206
### Extended URLs
172
207
173
208
For static feeds contained in a zip archive, ideally the feed files are all in the root directory of the archive. However, this is not always the case.
174
209
175
-
Transitland Feed Registry supports an extended URL format that can reference files nested within a subdirectory. The extended URL format can also reference a zip file nested within another zip file.
210
+
[transitland-lib](https://github.com/interline-io/transitland-lib) supports an extended URL format that can reference files nested within a subdirectory. The extended URL format can also reference a zip file nested within another zip file.
"attribution_text":"", // if license requires that data consumers display specific text
233
+
"attribution_instructions":""// if license provides specific guidance to how data consumers should provide attribution
195
234
}
196
235
```
197
236
198
237
### Authentication
199
238
200
-
Requiring authentication for public data feeds is typically not a good idea. However, it's reasonable to require an API key for a GTFS-realtime endpoints and other feeds that involve active queries.
239
+
Requiring authentication for public data feeds is typically not a good idea. However, it's reasonable to require an API key for a GTFS Realtime endpoints and other feeds that involve active queries.
"param_name":"",// When type=query_param, this specifies the name of the query parameter
245
+
"info_url":""// Website to visit to sign up for an account
207
246
}
208
247
```
209
248
249
+
The following authentication types are supported:
250
+
251
+
-`header`: API key or token is sent in an HTTP header
252
+
-`basic_auth`: Username and password are sent using HTTP Basic Authentication
253
+
-`query_param`: API key or token is sent as a URL query parameter
254
+
-`path_segment`: API key or token is included as a segment in the URL path. Indicate where the key/token should be injected using `{}`
255
+
-`replace_url`: The entire URL should be replaced with a different URL that includes authentication
256
+
257
+
Auth credentials are not stored in a DMFR file. It's up to each software package that reads the DMFR format to implement its own way of reading auth credentials from a separate file or from environment variables and using them when fetching each feed.
258
+
210
259
### Tags
211
260
212
261
Tags allow extra information to be added to feeds and operators. Keys and values must both be strings.
"unstable_url":"true"// note the quotes around true to specify a string value
273
+
}
274
+
}
275
+
],
215
276
"operators": [
216
277
{
217
278
"onestop_id":"o-9q9-bart",
218
279
"tags": {
219
-
"us_ntd_id":"90003",
220
-
"omd_provider_id":"bart",
221
-
"wikidata_id":"Q610120",
222
-
"twitter_general":"sfbart",
223
-
"twitter_service_alerts":"SFBARTalert"
280
+
"us_ntd_id":"90003",// an identifier from the US National Transit Database
281
+
"omd_provider_id":"bart",// an identifier from OpenMobilityData.org
282
+
"wikidata_id":"Q610120",// an identifier from Wikidata
283
+
"twitter_general":"sfbart",// a Twitter handle
284
+
"twitter_service_alerts":"SFBARTalert"// a Twitter handle
224
285
}
225
286
}
226
287
]
227
-
```
288
+
```
289
+
290
+
### Languages
291
+
292
+
The `languages` field is an optional array of IETF language tags that specify the languages used in the feed. This is particularly useful for feeds that contain multilingual content.
293
+
294
+
```jsonc
295
+
{
296
+
"languages": ["en-US", "es-MX"], // IETF language tags, see https://tools.ietf.org/html/bcp47
297
+
// ...
298
+
}
299
+
```
300
+
301
+
### Superceding lineage
302
+
303
+
The `supersedes_ids` field is an optional way to indicate when a feed or operator record replaces previous ones. This is useful when:
304
+
- An operator changes their name or organizational structure
305
+
- Multiple feeds or operators are merged into a single record
306
+
307
+
Alternatively, when a static GTFS feed is substantially the same but published at a different URL, its old URL(s) may be retained under `urls.static_historic`.
0 commit comments