The world reports water in a hundred incompatible ways. A registry that simply collects them inherits every incompatibility. The Protocol takes the other route: it does not tell anyone what to measure, it tells every dataset how to say what it is, where it came from, and who stands behind the number. That is the whole contract. Everything below is what it takes to keep that promise machine-checkable.
A dataset is verified when a machine, not a reader, can confirm five things about it.
Every dataset carries the same wrapper around its content. For a plain data file the envelope keys sit at the top level; for a map layer they sit beside the features; for a database row they map to columns. The content inside can be anything the dataset's own contract defines. The envelope is what makes ten thousand different datasets one registry.
{
"nvdm": "1.0",
"dataset": "data-root/ward-profiles",
"scope": { "kind": "city", "id": "madurai" },
"provenance": {
"sources": [
{
"id": "wris-gw-levels",
"title": "India-WRIS Ground Water Level dataset",
"publisher": "CGWB via India-WRIS",
"url": "https://indiawris.gov.in/wris/",
"license": "GoI open publication, cited with attribution",
"as_of": "2026-06",
"retrieved": "2026-07-25"
}
],
"method": "api",
"produced_at": "2026-07-26",
"produced_by": "scripts/fetch-wris-gw.py",
"note": "free-text caveats",
"conventions": {
"sign": "depth positive-down; per-station overrides in station records",
"units": "depths metres below ground level"
}
},
"ext": { }
}
Three timestamps and only three, all ISO 8601: as_of, the period the evidence describes; retrieved, when it was acquired; produced_at, when this dataset was generated. Seven competing spellings of "when" in the wild were the reason.
A dataset that is an administrative view of evidence owned by another scope, a city page showing its basin's data for instance, declares itself a projection of that scope and names the method, instead of becoming a divergent copy. One canonical record, many projections.
Download the envelope as a JSON Schema (draft 2020-12).
| Shape | What it is | Example |
|---|---|---|
| Record envelope | An object: the envelope plus named collections of records | Allocations, commitments, facts |
| Feature collection | A GeoJSON layer with the envelope as foreign members | Water bodies, rivers, wards |
| Indexed collection | A map keyed by an external identifier | Catchments keyed by OSM id |
| Series | An observation timeseries: entity id, ISO dates, unit-suffixed values, declared conventions | Groundwater levels, reservoir storage |
Each logical dataset declares one shape and a core: the keys every instance must provide, with types and units. A core only grows by optional additions; removing or retyping a key for one place is exactly the drift the contract exists to stop. Anything a place needs beyond the core goes in a namespaced extension, and an extension used by two or more places is promoted into the core: the standard grows from practice.
| Quantity | Canonical unit | Note |
|---|---|---|
| Reservoir storage | tmc | Publisher units may sit alongside, never silently converted |
| Supply and demand flow | mld | Entitlements also in native units |
| Depth to water | m below ground | Sign convention must be declared |
| Area | ha for water bodies, sqkm for catchments | Never mixed within a dataset |
| Rainfall | mm | |
| Percentages | pct, 0 to 100 | Not fractions |
Names carry the romanised form, with local-language names in language-suffixed keys. External identifiers are named by their system (osm_id, lgd_code, census_code) and never collapsed into one another; crosswalks are explicit records. Geometry is WGS84 GeoJSON with stable feature identities so editions can be compared. Absent evidence is an absent key plus a note, hedged as "no known public X as of a date".
The ladder is cumulative: a valid envelope on an unaccounted dataset stays at L1. New datasets entering the registry are required to reach L2; L3 requires the dataset's contract to be published.
The contract is versioned semantically. Additive changes, such as new optional envelope fields or new dataset contracts, are minor versions; anything that would invalidate a conforming dataset is a major version, and version 1 datasets remain readable by version 2 consumers. Registries of scopes, datasets, and sources are append-only: renames are new entries with crosswalks. Changes ship with the validator's report attached, so the difference in conformance is the review artefact.
It governs data records, not presentation, and not policy. It does not prescribe what to measure or set targets. It is not a methodology for water credits, indices, or financial instruments; those sit outside the contract, and data conforming to it is not thereby an input to any of them. Conformance says how a dataset is described and verified; access to a dataset is governed by the licence each source states.