# Verified Changes protocol, v0.1 A small, open convention for publishing dated, sourced changes to facts, so that any AI assistant can ask one question of any site: what changed since my knowledge ends? Identifier: `verified-changes/0.1`. Reference implementation: Data Butler (https://databutler.dev), whose own changelog is served this way. Markdown version: `/protocol?format=md`. ## Purpose Every language model has a training cutoff, and the facts it learned keep moving afterwards: a tax threshold rises at a Budget, an exam board moves a topic to another paper, a recall dataset gains a month of records. An assistant has no uniform way to find out what moved, so it answers from memory or re-reads whole source pages. The protocol gives this one shape. A site that tracks facts publishes a list of **entries**, each saying what a fact was, what it is now, from when, where that was checked, and when. An assistant finds the list at a well-known URL, calls it once with its cutoff date, and receives the entries that postdate it, newest first. Nothing here is specific to Data Butler's subject matter. Design rules: plain JSON, no authentication, no registration, no new transport. Everything reuses HTTP, JSON Schema, RSS, Atom and MCP as they exist. ## Entry schema An entry records one fact that moved. Fields, all required unless marked: - `area` (string) — the dataset area the fact belongs to, a lowercase slug such as `uk-rates`. Areas are declared in the discovery document. - `key` (string) — the stable identifier of the fact within its area, slash-separated: `income-tax/personal-allowance`, `8463/paper-1/topics`, `fr-recalls/count`. The pair `area/key` is the fact's namespace. The same fact keeps the same key forever; a renamed label is not a new key. - `label` (string) — the human-readable name of the fact. - `from` (any JSON value) — the previous value. `null` means the fact is new to the publisher (first coverage, or a figure the source introduced). - `to` (any JSON value) — the new value. `null` means the source withdrew the fact. - `effectiveFrom` (date or `null`) — the day the new value applies from, as the source states it: 6 April for a UK tax-year figure, the snapshot date for a dataset refresh. `null` when the source does not date the change (a specification page edited without a stated start date). - `source` (URL) — the official page the change was verified against. Not a news report, not the publisher's own page. - `verifiedDate` (date) — the day the publisher fetched `source` and confirmed `to`. This is the publication date of the entry and the date feeds and sorting use. - `note` (string, may be empty) — the one line a script cannot know: "Autumn Budget 2026", "AQA spec update for first teaching 2027", or the counts behind a dataset's first derivation. Empty when no context is needed. - `unit` (string or `null`, optional) — the unit of `from` and `to` when they are numbers: `GBP/year`, `%`, `pence/litre`. Dates are `YYYY-MM-DD`. `effectiveFrom` and `verifiedDate` answer different questions: when the world changed, and when the publisher checked. A Budget announced in November for the following April has `verifiedDate` in November and `effectiveFrom` the next 6 April; a consumer asking "since 2026-12-01" still receives it, because either date after the cutoff qualifies. Publishers may add context fields (Data Butler adds `taxYear` and `band` to rates entries; `board`, `level`, `subject`, `specCode` to exam entries). Consumers ignore fields they do not know. Names are camelCase. **Identity and immutability.** An entry is identified by `area` + `key` + `verifiedDate`. Entries are never edited or deleted once published; a mistaken entry is corrected by a new entry with the right `to`, a later `verifiedDate` and a `note` saying what it corrects. Every entry a consumer has seen is therefore final. Worked example — Data Butler's entry recording first coverage of the French RappelConso recall dataset: ```json { "area": "vehicles", "key": "fr-recalls/dataset", "label": "RappelConso automobile recalls dataset", "from": null, "to": "covered", "effectiveFrom": "2026-10-02", "source": "https://rappel.conso.gouv.fr/", "verifiedDate": "2026-10-02", "note": "First derivation of data/vehicles/fr-recalls.json: 1,663 automobile fiches (2018-01-19 → 2026-08-07), the full RappelConso V2 open-data export for sub-category \"automobiles, motos, scooters\" (DGCCRF, Licence Ouverte 2.0) as committed in the controle-technique repo on 2026-10-02; 568 fiches matched to 94 curated models by that site's reviewed alias table. Records reshaped, never edited." } ``` The JSON Schema for an entry and for the document that carries entries is published at https://databutler.dev/schema/changes.v0.json (draft 2020-12; the entry is `$defs/entry`). ## Discovery A publisher announces that it speaks the protocol at `/.well-known/changes.json`. An assistant that knows the convention needs no documentation: fetch the file, read the areas and endpoints, call the JSON endpoint. Fields: - `protocol` — `"verified-changes/0.1"`. - `publisher` — `{ "name", "url" }`. - `areas[]` — one object per area: `name` (the slug entries carry), `description` (what facts it covers), `cadence` (how often the sources are re-checked, in words). - `endpoints` — `json` (required; takes `?since=` and `?area=`), and optionally `html`, `rss`, `atom`, and `mcp` as `{ "url", "tool" }`. - `schema` — the URL of the JSON Schema the changes document validates against. - `licence` — the terms the entries may be reused under. - `contact` — an `https:` or `mailto:` URL for reporting a wrong entry. - Optional: `updated` (when this file last changed), `coverageStart` (changes before this day are not itemised), `specification` (where this protocol version is written down). The discovery document's own schema is https://databutler.dev/schema/well-known-changes.v0.json. A publisher that also serves an `llms.txt` adds one line there pointing at the discovery document, for example: ``` - `GET https://databutler.dev/.well-known/changes.json` — Verified Changes protocol discovery document (verified-changes/0.1): areas tracked, cadence, endpoints. ``` Data Butler's discovery document: ```json { "protocol": "verified-changes/0.1", "publisher": { "name": "Data Butler", "url": "https://databutler.dev/" }, "updated": "2026-10-04", "coverageStart": "2026-08-31", "areas": [ { "name": "uk-rates", "description": "UK tax-year rates and thresholds verified against gov.uk: income tax, National Insurance, minimum wage, student loans, VAT, ISA, pensions, stamp duty, capital gains, dividends, savings and marriage allowances, State Pension and State Pension age, statutory sick/maternity/paternity pay, Child Benefit.", "cadence": "Every 6 April (new tax year) and after each Budget or Autumn Statement; minimum wage on 1 April; every source page re-fetched weekly." }, { "name": "uk-exams", "description": "UK exam-board specifications verified against the boards' own pages: which topic sits on which paper, durations, marks, weightings. AQA GCSE sciences and maths so far.", "cadence": "Each September and on any published specification update; every source page re-fetched weekly." }, { "name": "vehicles", "description": "Official vehicle recall datasets: DVSA (UK), RappelConso (France) and MLIT (Japan) recalls and complaints; EU Safety Gate is a stub.", "cadence": "Monthly." }, { "name": "software-eol", "description": "Support and end-of-life dates for 14 runtimes and operating systems (endoflife.date snapshot): dataset additions, new cycles, moved or reached end-of-life dates", "cadence": "monthly" }, { "name": "policy-rates", "description": "Central-bank policy rates verified against the banks' own pages: Bank of England Bank Rate, US Federal Reserve federal funds target range, ECB key interest rates (deposit facility, main refinancing, marginal lending).", "cadence": "After each scheduled decision (eight a year per bank); re-verified within 45 days of verifiedDate; every source page re-fetched weekly." }, { "name": "us-rates", "description": "US federal rates and thresholds read from the IRS revenue procedures and notices and SSA's Federal Register notice: income-tax rate schedules and standard deduction, Social Security wage base and rates, Medicare, retirement-plan and IRA limits, HSA limits, estate and gift exclusions.", "cadence": "Annual: after the IRS tax-year inflation adjustments (October), the retirement-plan limits (November) and the SSA Federal Register notice (October/November); every source page re-fetched weekly." }, { "name": "de-rates", "description": "German tax and social-insurance figures read from the consolidated statutes, the Bundesgesetzblatt and the BMG/DRV/BMAS pages: Grundfreibetrag and § 32a tariff, Solidaritätszuschlag, Beitragsbemessungsgrenzen and Beitragssätze, Zusatzbeitrag, Mindestlohn, Geringfügigkeitsgrenze, Kindergeld, Kinderfreibetrag, Pauschbeträge, Entfernungspauschale.", "cadence": "Annual: after the Sozialversicherungsrechengrößen-Verordnung and the Zusatzbeitrag announcement (November), and any Steuergesetz changing § 32a EStG for the next Veranlagungszeitraum; every source page re-fetched weekly." }, { "name": "uk-vehicle-rules", "description": "UK vehicle tax (VED) and MOT rules verified against gov.uk: first-year rates by CO2 band, the standard rate, the expensive car supplement, 2001–2017 bands, pre-2001 engine-size rates, electric-vehicle rules since April 2025, historic-vehicle exemptions, MOT due dates, maximum fees, early renewal, retests, exemptions and penalties.", "cadence": "Every 1 April (VED rates and the historic-vehicle exemption date move with the Finance Act) and after each Budget; MOT fees and rules when DVSA changes them; every source page re-fetched weekly." }, { "name": "uk-exam-dates", "description": "UK exam calendar facts verified against JCQ and the boards' own documents: GCSE and A-level results days, the summer exam timetable (JCQ window, contingency day, dates of the most-asked papers at AQA, Pearson Edexcel, Cambridge OCR, WJEC/Eduqas), entry deadlines and late-fee dates, Scotland's results day, and announced specification changes with first-teaching and first-exam years.", "cadence": "Annual, calendar-driven: when JCQ and the boards publish the following summer's final timetables (early in the calendar year) and the results days; the weekly watcher hashes the JCQ and board timetable pages" }, { "name": "calendar", "description": "Public holidays (UK, US federal, German Länder, France), tax-year starts/ends (nine countries) and daylight-saving switch dates for 2026–2028: new years published, holidays added or moved, rule changes", "cadence": "monthly" }, { "name": "uk-gov-process", "description": "UK government service facts verified against gov.uk: passport fees (UK and overseas), driving licence renewal and provisional licences, change of address, vehicle tax and SORN, voter registration, birth and death registration, Blue Badge, Self Assessment deadlines and Making Tax Digital, National Insurance numbers, Universal Credit, EU Settlement Scheme, eVisa and ETA — fees, processing times, eligibility, start URLs and dated changes.", "cadence": "Re-verified against the gov.uk pages every 30 days and on fee-change days (Home Office fees usually move in April); every source page re-fetched weekly through the gov.uk content API." } ], "endpoints": { "json": "https://databutler.dev/api/changes", "html": "https://databutler.dev/changes", "rss": "https://databutler.dev/changes.rss", "atom": "https://databutler.dev/changes.atom", "mcp": { "url": "https://databutler.dev/api/mcp", "tool": "what_changed_since" } }, "schema": "https://databutler.dev/schema/changes.v0.json", "specification": "https://databutler.dev/protocol", "licence": "Free to reuse with attribution to databutler.dev. Each entry's underlying fact belongs to the linked official source and stays under that source's terms (for gov.uk, the Open Government Licence v3.0).", "contact": "https://github.com/physics-star-cat/databutler/issues" } ``` ## Transports The same entries are served in four ways. Only JSON is required; the rest are conveniences for humans, feed readers and MCP clients. **JSON.** `GET ?since=YYYY-MM-DD&area=` returns a changes document: `protocol`, `schema`, `publisher`, `generated` (the day it was produced), `entries[]`, plus the filters applied. Semantics: - `since` is a day. An entry qualifies when `verifiedDate > since` or `effectiveFrom > since` — strictly after, so an assistant passes its cutoff date and receives changes verified or taking effect after it. A `since` before the publisher's `coverageStart` is answered, with a note that earlier changes are not itemised. - `area` narrows to one declared area; omit it or pass `all` for every area. An unknown area is an error naming the known areas. - Ordering is newest `verifiedDate` first. - Pagination: a document carries at most a few hundred entries (Data Butler caps at 100). A consumer wanting more walks forward by area, or reads the feeds, which carry the full history. This version defines no cursor. - A publisher with no server may serve a static document at `endpoints.json` that ignores `since`; the consumer filters client-side. Data Butler's response to `GET /api/changes?since=2026-10-01&area=vehicles`, one entry shown. The fields outside the document (`attribution`, `freshness`, `cite`) are its response envelope, allowed by the schema as additional properties: ```json { "attribution": "databutler.dev", "docs": "https://databutler.dev/api", "note": "Entries newest first: from/to, effectiveFrom, the official source, and a maintainer note where recorded.", "protocol": "verified-changes/0.1", "schema": "https://databutler.dev/schema/changes.v0.json", "publisher": { "name": "Data Butler", "url": "https://databutler.dev/" }, "generated": "2026-10-03", "since": "2026-10-01", "area": "vehicles", "coverageStart": "2026-08-31", "areasCovered": ["uk-rates", "uk-exams", "vehicles"], "count": 3, "entries": [ { "area": "vehicles", "key": "jp-recalls/dataset", "label": "MLIT recall filings and owner complaints dataset", "from": null, "to": "covered", "effectiveFrom": "2026-08-30", "source": "https://renrakuda.mlit.go.jp/", "verifiedDate": "2026-10-03", "note": "First derivation of data/vehicles/jp-recalls.json from the shaken-data MLIT snapshot of 2026-08-30: 919 unique recall filings (1,377 model links, 1994-03-24 → 2026-07-30) and 19,659 owner complaints across 75 models. ..." } ], "freshness": { "verifiedDate": "2026-10-03", "nextScheduledRefresh": null, "staleness": "live" }, "cite": { "url": "https://databutler.dev/r/changes?since=2026-10-01&area=vehicles", "text": "databutler.dev, computed live 2026-10-03 against https://renrakuda.mlit.go.jp/" } } ``` **HTML.** `endpoints.html` is an indexable page of the same entries, newest first, each showing every field, with a fragment anchor per entry so each has a permalink. It takes the same `?area=` and `?since=` filters and carries `rel="alternate"` links to the feeds and the JSON. **RSS and Atom.** One item per entry, same order: - `guid` (RSS) and `id` (Atom) are the entry's permalink on the HTML page: `#--`. Because entries are immutable, a guid never changes and never recurs. - `link` is the entry's `source` — the official page — so a reader lands on the evidence. - `pubDate` / `published` / `updated` are the `verifiedDate` at midnight UTC. - `category` is the `area`. - Rendering is pure: the same entries always produce the same bytes, so caches stay quiet until the data changes. Data Butler's RSS item for the EU Safety Gate stub entry: ```xml vehicles: EU Safety Gate vehicle alerts — none → stub https://ec.europa.eu/safety-gate-alerts/screen/webReport https://databutler.dev/changes#vehicles-eu-safety-gate-dataset-2026-10-03 Sat, 03 Oct 2026 00:00:00 GMT vehicles EU Safety Gate vehicle alerts: none → stub. Effective from 2026-10-03; verified 2026-10-03. Official source: https://ec.europa.eu/safety-gate-alerts/screen/webReport Note: Stub only — ... ``` **MCP.** A publisher with an MCP server exposes a tool named `what_changed_since` (the name is the convention, so a client can look for it). Input: `{ "since": "YYYY-MM-DD" (required), "area": a declared area or "all" (optional) }`. Output: the changes document above, as the result's text content. The tool is read-only and declares so in its annotations. Data Butler's call: ```json { "method": "tools/call", "params": { "name": "what_changed_since", "arguments": { "since": "2026-06-01", "area": "vehicles" } } } ``` ## Freshness envelope Changes are only useful next to the facts, so a conforming publisher stamps every answer it gives — not only the changes document — with two blocks: - `freshness` — `{ "verifiedDate", "nextScheduledRefresh", "staleness" }`. `verifiedDate` is when the dataset behind the answer was last checked against its source. `nextScheduledRefresh` is when the publisher has committed to checking again, or `null` for computed-on-request answers. `staleness` is one of four words: `fresh` (before the scheduled refresh), `due` (the refresh date has passed, within a short grace window — Data Butler uses 14 days), `overdue` (past the grace window; treat the answer with suspicion and say so), `live` (computed or fetched at request time). - `cite` — `{ "url", "text" }`. `url` is a permalink a person can open to see the same answer beside its official source and verification date; `text` is a one-line citation an assistant can quote. Data Butler's envelope on a UK income-tax lookup: ```json { "freshness": { "verifiedDate": "2026-08-31", "nextScheduledRefresh": "2027-04-06", "staleness": "fresh" }, "cite": { "url": "https://databutler.dev/r/uk/rates?category=income-tax", "text": "databutler.dev, verified 2026-08-31 against https://www.gov.uk/income-tax-rates" } } ``` An assistant that sees `overdue` should prefer to tell the user the figure may be stale rather than present it as current. ## Verification rule The protocol carries no cryptographic proof; its trust comes from a publishing discipline every conforming publisher follows and states: 1. **Fetch before publish.** An entry is written only after `source` was fetched on `verifiedDate` and `to` was read from that page — never from memory, a news story or a summary. Entries are generated by a script from two committed versions of the data, so `from` and `to` are both recorded values; a person adds only the `note`. 2. **Re-check on a cadence.** Each area's `cadence` is a commitment. The publisher re-fetches every `source` at least that often and, for scheduled datasets, publishes `nextScheduledRefresh`. 3. **Watch the sources.** Between refreshes, a watcher re-fetches every `source` URL (Data Butler: weekly, Mondays 06:00 UTC) and raises an issue when a page changes, so a surprise change is noticed within a week. The watcher never writes data; a person does, against the live page. 4. **Never edit, always append.** A wrong entry is followed by a correcting entry; the wrong one stays, so what an assistant was told on a given day remains reconstructible. 5. **Say what is not covered.** `coverageStart` and the `areas` list bound the claim. A question outside them gets an explicit "not covered", not a guess. ## Conformance A publisher conforms to `verified-changes/0.1` when every item below holds; each is checkable from outside with a fetch and the published schemas. 1. `GET /.well-known/changes.json` returns JSON that validates against https://databutler.dev/schema/well-known-changes.v0.json, with `protocol` equal to `verified-changes/0.1`. 2. Every `endpoints.*` URL in it responds (JSON endpoint with 200 and `application/json`; HTML with 200 and `text/html`; feeds with their media types; MCP with a `tools/list` that includes the named tool). 3. `GET ?since=` validates against https://databutler.dev/schema/changes.v0.json, and every entry's `area` appears in `areas[].name`. 4. Entries are ordered newest `verifiedDate` first, and `?since=` applies the strict either-date rule above. 5. Every entry's `source` is an `https:` URL on the authority's own domain, and fetching it succeeds. 6. No entry is ever modified or removed: the set of `area|key|verifiedDate` identities only grows between fetches. 7. Feed guids are permalinks that resolve to an anchor on the HTML page, and two fetches of a feed with unchanged data are byte-identical. 8. Every data answer the publisher serves carries `freshness` (with `staleness` from the four-word vocabulary) and `cite.url`. 9. `llms.txt`, if present, names the discovery document. 10. The publisher states its verification rule and cadence publicly (a page like this one or a curation document) and files corrections as new entries. Data Butler checks items 1, 3, 4, 6, 7 and 8 in its own test suite on every commit; items 2, 5 and 9 are checked by its weekly watcher and deploy checks. **For an assistant.** At the start of a session that touches a publisher's subject matter, fetch `/.well-known/changes.json` once, then call `endpoints.json` (or the MCP tool) once with `since` set to your training cutoff and no area filter. Treat each entry as superseding what you learned: quote `to`, say it applies from `effectiveFrom`, cite `source` or `cite.url`. An empty document means the facts you know for those areas were still current on their `verifiedDate`s; say that rather than hedging. Do not re-poll within a session; the cadence says how often anything can change. ## Versioning The identifier is `verified-changes/.`. Within a major version publishers may add fields and consumers must ignore unknown ones; required fields, their types and the `since` semantics do not change. A minor bump adds optional fields or transports; a major bump may change required fields and ships a new schema URL (`changes.v1.json`). The discovery document names the version the publisher speaks. v0.x is a draft: the shape has served Data Butler since 2026-08-31, but v1.0 may tighten wording after other sites implement it. Comments and corrections: https://github.com/physics-star-cat/databutler/issues.