Agency registry

The scorecard loads the shards listed, in order, by index.yaml. The manifest is authoritative: every listed file must exist, every YAML shard under this directory must be listed, and agency ids must be unique across the merged registry. This explicit list prevents a stray or partially generated YAML file from silently entering production.

New agency submissions go to intake.yaml. Once a curator has verified the agency's primary location, move its complete YAML block to the matching registry/<country>/<subdivision>.yaml shard and add a new shard to index.yaml when necessary. Move the block textually so comments and field ordering survive. A submission and a routine feed-URL update should each touch only the relevant small shard.

Required fields

• id: stable lowercase slug containing letters, digits, -, or _.
• name: public agency or service name.
• static_gtfs_url: direct http(s) URL for the GTFS Schedule feed.

Location fields

• country: assigned ISO 3166-1 alpha-2 code. State it on every new entry; omitted legacy entries default to US for compatibility.
• subdivision_code and subdivision_name: portable primary jurisdiction, normally an ISO 3166-2 code and its canonical name. Supply them together.
• state: deprecated US-only compatibility input retained on older records. Do not add it to new entries; portable location fields are canonical.

An agency that cannot yet be located honestly stays in intake.yaml; location must not be guessed merely to choose a shard.

Optional feed and curation fields

• rt_urls: mapping whose supported keys are trip_updates, vehicle_positions, and service_alerts; every value is an http(s) URL.
• rt_note, license_note, operating_note, ntd_note: curator-facing explanatory text shown on the relevant scorecard surfaces.
• mdb_id: Mobility Database source id used for exact feed rediscovery.
• ntd_id: four- or five-digit US National Transit Database id.
• organization_id: stable operator slug shared by related feeds.
• alias_of: id of another registry entry when this is a retained alias.
• feed_variant: descriptive variant label for one operator's multiple feeds.
• feed_status: active, deprecated, inactive, or development.
• is_official: true or false when catalog provenance establishes it.
• service_type: fixed (default), seasonal, or demand_response.
• fare_free: true only when fare-free operation is a verified policy.

A replaced endpoint may remain in the registry as feed_status: deprecated with alias_of pointing to its active successor. It is then excluded from batch scoring and the current catalog, while its dated artifacts remain available for reproducibility and its former scorecard URL redirects to the successor. Do not infer this relationship from similar names; record it only from a reviewed catalog redirect or provider evidence.

scorecard supersessions reads that catalog redirect for you. The Mobility Database marks a replaced feed record deprecated and names its successor in redirect.id; the command pairs the two, writes alias_of and feed_status: deprecated on the retired record with a comment naming the catalog ids, and lists what it could not resolve in docs/feed-supersessions.md. It reports on its own and only edits with --apply, and the weekly discover workflow runs it into a review pull request. A retirement whose successor publishes under a different agency name is called out separately in that report: the catalog is usually right about it, and it is still the case to read before merging.

Two of those cases are not left to a reader noticing them. A retirement whose successor sits in a different state or country, or whose successor's name does not read as a rename of the record retiring into it, is held: the command will not write it, and pipeline/scripts/check_supersession_review.py fails the build if it is written by hand, until the decision is recorded in supersession-review.yaml at the repository root. A decision there is either retire (one agency, or a real merger) or keep_separate (not the same agency, and the automation must not re-apply the redirect), and each one states its evidence. See docs/supersession-flagging.md.

Reviewed reuse evidence

reuse_evidence is an optional, curator-approved record used by bounded coverage gates. It is deliberately separate from license_note, catalog is_official flags, and Mobility Database metadata. Those fields can point a reviewer toward evidence, but they never grant permission by themselves.

reuse_evidence:
  decision: approved
  source_kind: official_portal
  provider_source_url: https://provider.example/dataset
  terms_url: https://provider.example/terms
  scope: [gtfs_schedule]
  attribution: Provider name.
  reviewed_by: curator-handle
  reviewed_on: "2026-07-16"
  identity_reviewed: true

The parser accepts only an approved decision, official_portal or provider source kind, HTTP(S) evidence links, the closed gtfs_schedule scope, a valid review date that is not in the future, non-empty attribution and reviewer, and an explicit identity review. Unknown keys or inferred evidence fail registry loading. Absence means no approved evidence record is on file; it is not a claim that the feed is unlicensed.

Unknown fields, malformed URLs or locations, duplicate ids, missing alias targets, and alias cycles fail registry loading. Run the same gates as CI before opening a pull request:

cd pipeline
uv run scorecard lint --strict
uv run pytest -q tests/test_agencies.py tests/test_submissions.py

The contributor walkthrough is in docs/add-your-agency.md.