Systems and records
Silent schema semantic change: same 92 field names, 23 new rules
By SourceX Editorial · Updated
10 sections
Short answer
A silent schema semantic change keeps a field's name, and usually its type, but changes what its values may be or mean, so name and type checks pass. In the GTFS transit reference, all 92 fields defined in March 2016 still exist in September 2026, yet 23 changed their allowed codes or presence rule. Compare each field's codes, labels, presence and definition across versions before accepting a re-delivery.
Retrieval
Silent schema semantic
Key takeaways
- Name checks are blind to this change: all 92 GTFS field names from March 2016 survived to September 2026, so a column comparison flags none of them.
- Comparing allowed codes and presence rules flagged 23 of the 92: three fields gained seven codes and 20 changed their presence label.
- Old labels can be wrong too: by our reading, 7 of the 20 presence changes only brought the label into line with what the 2016 text already allowed.
- A document's revision date is a weak version signal: it moved in the same commit for 3 of 34 structural or rule changes, and an August 2026 change still sits under April 27, 2026.
- Pin each delivery to a commit or content hash, ship a field fingerprint manifest, and block acceptance on new codes, presence rule changes and renamed categories until a person has read them.
What is a silent schema semantic change in a dataset?
It is a change in what a field's values may be or mean while the field keeps its name, and usually its type. Parsers, schema registries and column comparisons pass it, because they check names and types. The damage shows up later: a join that quietly drops rows, a label map with a class it has never seen, or a trend that bends on the day a new release arrived.
Three forms recur. The allowed values grow or shrink, so a coded field gains a value your mapping does not know. A code keeps its number while its category is renamed or redefined. Or the presence rule moves: a field that was always filled may now be empty for some rows, or must be empty for others. Business systems produce all three whenever an administrator adds a picklist value or splits a status, and the export header looks exactly as it did before.
Apache Avro's specification shows why ordinary tooling lets this through. During schema resolution, record fields are matched by name, a schema's doc fields are ignored, and when the writer uses an enum symbol the reader does not know and the reader declares a default, the default is used. A reader can therefore load new data under old assumptions without raising a single error.
Ten years of one public data dictionary: every field name survived
To measure how often meaning moves under a stable name, we compared the General Transit Feed Specification (GTFS) Schedule reference, the data dictionary transit agencies follow when they publish timetables, at two pinned commits in its public GitHub repository: the first master version after the reference was converted to Markdown tables (commit 3fc0138, 16 March 2016, UTC) and the latest (commit 3c9e7b9, 16 September 2026, UTC).
The dictionary grew from 92 fields in 13 files to 228 fields in 32 files. All 92 original fields, keyed by file and field name, are still present. A header or column comparison against the 2016 dictionary therefore reports nothing missing and nothing renamed.
The per-field comparison tells a different story. Three fields gained allowed codes, 7 codes in all, and 20 fields changed their presence label, so 23 of the 92 fields, exactly a quarter, moved on at least one of those two rules. A further 20 codes in 9 fields kept their number but changed label wording, and after normalization the definition text of 91 of the 92 fields differs.
GTFS is a careful case, not a sloppy one. Its governance page lists backwards compatibility as a guiding principle, so that existing feeds stay valid and existing parsers can keep reading the older parts of newer feeds. Valid for the producer is not the same as unchanged for the consumer: the changes below kept old feeds valid and still altered what a reader built on the 2016 dictionary would assume.
Which check catches which change? The same-name test matrix
Run the checks as a stack, because each one is blind to something the next one sees. Use the matrix below as the acceptance test for any delivery that claims an unchanged schema; it shows each check's result on the GTFS pair and the decision it should trigger:
| Check | What it compares | GTFS result, 2016 to 2026 | What it misses | Decision when it fires |
|---|---|---|---|---|
| Field-name check | File and field names, as a header diff would | 0 of 92 flagged; every name survived | Every change described on this page | Block only on missing or renamed fields |
| Allowed-code check | The set of codes each coded field enumerates | 3 fields gained 7 codes (location_type 2 to 4, route_type 11 and 12, transfer_type 4 and 5) | Codes whose number stays while their category changes | Hold the delivery until every new code is mapped, merged or excluded |
| Code-label check | Label text for each code number present in both versions | 20 codes in 9 fields reworded; on reading, 5 codes in 3 fields renamed or re-described | Changes to the field's definition outside its code list | Send each changed label to a person; remap labels and aggregates |
| Presence check | Required, optional, conditional or recommended label | 20 fields changed: 10 rule changes, 7 labels catching up with old text, 3 guidance only | Conditions written only in prose | Rebuild null rules and join logic for the version received |
| Type check | Declared data type of each field | Not measurable: the 2016 reference had no type column | Meaning that moves inside an unchanged type | Compare types wherever both versions declare them |
| Definition-text hash | Normalized description of each field | 91 of 92 changed, mostly rewording | Nothing, yet it cannot rank what matters | Treat as a trigger to read, never as pass or fail |
Presence rules are null semantics, and the old label can be wrong too
A presence change tells you which rows may now leave a field empty, which makes it a null-semantics change even when every value still parses. The clearest case in this sample is stop_times.stop_id: required in 2016, conditionally required since the GTFS-Flex change merged on 19 March 2024, and now forbidden when a row uses a location group or a GeoJSON location instead. A pipeline that inner-joins stop times to stops on stop_id, or enforces a not-null rule written from the 2016 dictionary, silently drops or rejects those rows.
Reading all 20 presence changes against both texts sorts them into three kinds. Ten are rule changes that arrived with new capabilities: station pathways in 2019 (stop_name, stop_lat, stop_lon and parent_station), continuous stops in 2020 (shape_id), trip-to-trip transfers in 2022 (from_stop_id and to_stop_id) and flexible services in 2024 (stop_id, pickup_type and drop_off_type). Three are guidance only: feed_start_date, feed_end_date and feed_version moved from optional to recommended in 2023 and may still be empty.
The other seven are the warning. The 2016 table labelled arrival_time Required while its own description told producers to leave it empty at stops that are not time points, and labelled route_short_name Required while telling them to use an empty string when a route has no short name. A manifest generated from the 2016 presence column would have rejected rows that the 2016 text allowed. Derive null rules from the definition, not from the label alone, and record which of the two you used.
New codes and renamed categories: the number stays, the meaning moves
A new code is the easiest silent change to detect and the easiest to mishandle. Route_type gained 11 (trolleybus) and 12 (monorail) on 5 February 2020; location_type gained 2 (entrance or exit) on 28 November 2016, then 3 and 4 (generic node and boarding area) on 27 March 2019; transfer_type gained 4 and 5, for in-seat transfers, on 26 July 2022. A model or report built on the 2016 code list errors, drops these rows or, under a default rule like Avro's, files them under a category that is simply wrong.
Renamed categories are harder, because the code set does not change at all. Route_type 5 was "Cable car" in 2016 and has been "Cable tram" since 26 December 2019, defined as street-level rail cars pulled by a cable beneath them; route_type 6 went from "Gondola, Suspended cable car" to "Aerial lift, suspended cable car", with gondola lifts and aerial tramways as examples. Exact_times 1 was described in 2016 as frequency-based trips that are exactly scheduled, and since February 2019 as schedule-based trips with the exact same headway throughout the day. Any report that carries the old names forward now labels categories the specification defines differently.
The other 15 relabelled codes are wording: phrases such as "indicates that" were dropped and "passenger" became "riders". GTFS's own amendment rules draw the same line, allowing only editorial changes once a proposal is under vote, with wording free to change as long as it does not change the meaning. An acceptance review needs that distinction recorded per code, by a named person, with the reason.
Is a version label enough to pin what you received?
No. Pin the commit or a content hash, because a version label maintained by hand can lag the content it describes. The GTFS reference opens with a "Revised" date. Across the 127 consecutive pairs of versions on master's first-parent history that we compared, 34 versions changed a field's presence label or allowed codes, or added or removed a field. Only 3 of those 34 updated the Revised line in the same commit.
For 30 more, the line caught up later, between 4 and 765 days after the change, and the median lag across the 33 changes where it eventually moved was 112 days. The change of 17 August 2026 that made min_transfer_time conditionally required still sits under "Revised April 27, 2026" in the latest version. A buyer who recorded only the revision date would treat two different dictionaries as one.
Business exports behave the same way. A file named after its export date, a schema version string bumped by hand or a release note written after the fact tells you less than a hash of the field fingerprints shipped with the data itself.
The versioned delivery manifest: one semantic fingerprint per field
Ship a fingerprint line for every field with each delivery, and diff it against the last accepted delivery before any record is loaded. The entries below are the minimum, and each one feeds a check in the matrix above:
| Manifest entry | What it records | GTFS example | Check it enables |
|---|---|---|---|
| Field key and dictionary version | File, field and the commit or content hash of the dictionary used | stop_times.txt stop_id at commit 3c9e7b9 | Every comparison starts from a pinned pair |
| Presence rule | The label plus the condition text that governs empty values | Conditionally required; forbidden when a location group is used | Null-rule and join review |
| Allowed codes with labels | Each code and its label as published | route_type 5, Cable tram | Code-set and code-label checks |
| Label hash per code | A hash of each normalized label | Changes when Cable car became Cable tram | Cheap detection of renamed categories |
| Definition hash | A hash of the normalized definition text | Changed for 91 of 92 GTFS fields | A trigger for human reading |
| Change note | What changed, why, the effective date and the reviewer's decision | Rule changed with GTFS-Flex, 19 March 2024 | An audit trail for retraining and evaluation |
A file that loads and a checksum that matches: is that not enough?
It proves the bytes arrived intact and that a parser can read them, and nothing more. A checksum is computed over whatever the producer wrote, so a re-delivery with a renamed category carries a perfectly valid checksum of the new meaning. A loader that matches columns by name, as Avro's resolution rules do, reads 2026 values into 2016 assumptions without complaint.
The strongest objection runs the other way: semantic diffs are noisy. The definition hash flagged 91 of 92 GTFS fields, and 15 of the 20 relabelled codes were rewording. That is why the matrix treats hashes and labels as triggers for reading and blocks only on new codes, presence rule changes and renamed categories. In this sample the blocking list is 14 of the 92 fields by our reading: the 3 with new codes, the 10 with rule changes, and exact_times, whose categories were re-described (the renamed route_type and location_type codes sit in fields already counted). That is short enough for a reviewer to work through field by field.
The limits matter too. The scripts read a Markdown dictionary, not delivered rows, so they show where meaning moved in the specification, not how many feeds used the new codes. A dictionary that is wrong about its own data, like the 2016 presence labels, also needs a row-level profile of null rates and distinct values.
Acceptance checklist, and how to write it into a data request
Ask for the fingerprint, not just the file. A data request can name the fields a task depends on, the code lists and presence rules it assumes and the diff it will run on each delivery, which turns "same schema" from a promise into a test both sides can run.
SourceX sources datasets on request rather than holding them in stock: buyers set out scope, volume, language, format, timing and licensing on its request form, and SourceX follows up about potential sources. Attaching a field fingerprint and the matrix above gives that conversation a concrete acceptance test, and SourceX's illustrative sample manifest shows the kind of field guide a fingerprint can extend.
Before accepting any delivery that claims the same schema as the last one, work through this list; it applies to a CRM export as much as to a public specification:
Checklist · 9 items
- Record the commit, export job version or content hash of the data dictionary for both the accepted delivery and the new one.
- Diff field names first, then stop treating a clean name diff as a pass.
- Compare the code set of every coded field, and hold the delivery until each new code is mapped, merged or excluded in writing.
- Compare each code's label, and have a named reviewer record "renamed category" or "rewording", with a reason, for every change.
- Compare presence labels and the condition text behind them, then regenerate not-null rules and join logic from the text.
- Hash each field's normalized definition, and read every changed field that a model, label or metric depends on.
- Re-run the acceptance queries that touch changed fields on both deliveries, and compare row counts and label shares.
- Write a dated change note per field and keep it with the dataset version that training and evaluation runs cite.
- If the producer cannot supply the dictionary for an earlier delivery, mark that delivery's semantics as unverified instead of assuming they match.
0 of 9 ticked. Tick each item as you go.
Methods note: how the GTFS comparison was run
Data: the file gtfs/spec/en/reference.md in github.com/google/transit, read with git from a clone on 28 October 2026. Baseline: commit 3fc0138, the merge that put the Markdown-table reference on master on 16 March 2016 (its file is identical to commit 0cade33). Final: commit 3c9e7b9 of 16 September 2026. History: the 129 versions of the file on master's first-parent history, of which versions 2 to 129 were compared; version 1, the initial conversion, uses a different layout. Dates are committer dates in UTC, and merge commits on the first-parent line are included because they mark when a change reached master.
Parsing, by our own scripts (no repository code was run): a field is a row of a table whose header row contains "Field Name", under a level-three heading ending in .txt or .geojson inside the Field Definitions part; a row whose first cell is empty, ignoring line-break tags, continues the previous field, and any non-table line ends the table, so example tables are not read. Fields are keyed by file and field name, lower-cased with Markdown removed. Presence is the Required or Presence column. A code is an integer that starts an enumeration item (at the start of a cell or after a line break or bullet), written plain, bold or in code style, optionally followed by an "or empty" or "or blank" qualifier with or without parentheses or bold, then a hyphen, en dash, em dash or colon followed by a space; items of the form "1 or more" are ranges and are not counted; the 2016 form "A value of N indicates" is also read; a code listed twice in one field counts once. A code's label is the text after the separator at its first occurrence, up to the first full stop or line break, with emphasis removed and lower-cased; for a 2016 "A value of N indicates that ..." item, the label starts after "that" (starting it after "indicates" would give 23 relabelled codes in 10 fields instead of 20 in 9).
Counting: added or removed codes are counted only where a field enumerates codes in both versions; calendar.txt tuesday to sunday enumerate codes in 2016 but in 2026 refer to monday, so they are listed and not counted. Changed text means the definitions differ after removing link targets, emphasis, code marks and line breaks, collapsing spaces and lower-casing. Each dated change is the committer date of the first first-parent version whose parsed dictionary shows it. The split of presence changes into rule changes, labels catching up and guidance only, and of relabels into renamed categories and rewording, is our reading of both texts, recorded field by field. For the revision check, a version changed structure or rules when any field's presence label or code set changed or a field was added or removed; the Revised string is compared as written; lags are calendar days between commit dates (0 where the line moved in the same commit); the median of 33 lags is the middle value.
Not measured: whether any published feed used the new codes, row-level null rates, and type changes before 2019, when the reference added a type column. The comparison covers one dictionary; it illustrates the mechanism and is not a rate of change for business data.
Frequently asked questions
How is a silent semantic change different from schema drift?
Schema drift usually means structural change: columns added, removed, renamed or retyped. A silent semantic change keeps the structure and alters allowed values, category meaning or presence rules, so structural drift detectors pass it. Track both, with separate checks and separate owners.
Can a schema registry catch a semantic change?
Only partly. Registries apply structural rules such as Avro's, which match fields by name and ignore documentation, so a renamed category or a new condition written in prose goes through. Pair the registry with a fingerprint diff of codes, labels and presence for every field a task uses.
How do you spot a semantic change when the producer sends no data dictionary?
Profile the delivered values instead: distinct values per coded field, null rates per field and segment, and label shares, each compared with the last accepted delivery. A new value or a jump in empty values is the prompt to ask the producer what changed. Until they answer, record that delivery's semantics as unverified.
Should a renamed category trigger relabeling of training data?
It depends on whether membership changed. If only the name changed, update label text and documentation; if the grouping changed, as when route_type 6 widened from gondolas to aerial lifts, remap historical records or keep a version boundary in training and evaluation sets.
Is a transit specification a fair stand-in for business data?
It is a public, versioned dictionary with ten years of history, which business systems rarely publish, so it shows the mechanism clearly. Business exports usually change faster and with less notice, because a picklist value can be added in minutes. Treat the GTFS counts as an illustration, not as a rate for your data.
Sources
- The GTFS Schedule reference at commit 3c9e7b9 (16 September 2026) defines 228 fields in 32 files, makes stop_times.stop_id conditionally required and forbidden when a location group or location is used, names route_type 5 Cable tram and 6 Aerial lift, and still opens with Revised April 27, 2026. Source
- The GTFS reference at commit 3fc0138 (16 March 2016) defines 92 fields in 13 files, labels arrival_time and route_short_name Required while its text allows empty values, and names route_type 5 Cable car. Source
- GTFS governance lists backwards compatibility as a guiding principle and allows only editorial changes during a vote, with wording free to change as long as it does not change the meaning. Source
- The GTFS-Flex change merged on 19 March 2024 made stop_times.stop_id conditionally required and pickup_type and drop_off_type conditionally forbidden. Source
- Route types 11 (trolleybus) and 12 (monorail) were merged into the reference on 5 February 2020. Source
- Trip-to-trip transfers with transfer_type 4 and 5 were merged on 26 July 2022, making from_stop_id and to_stop_id conditionally required. Source
- A commit of 26 December 2019 redefined route_type 5 as cable tram and route_type 6 as aerial lift. Source
- A commit of 17 August 2026 made min_transfer_time conditionally required for timed transfers without changing the reference's Revised date. Source
- Avro schema resolution matches record fields by name, ignores doc fields, and substitutes the reader's enum default for an unknown writer symbol. Source
- SourceX's request form asks buyers for scope, volume, language, format, timing and licensing, and says datasets are sourced on request, not held in stock. Source
- SourceX publishes an illustrative sample package summary and field guide for a fictional company. Source
Tell us what data you need
Share scope, volume, format, timing and licensing needs. Datasets are sourced on request.