Observed directly
The number came from a direct observation of the thing itself, with a source reference that can be re-checked.
Write-time enforcement
A number that will not say how it was made does not get written.
Whole industries ship modeled figures as if they were measured. The fix is not a footnote — it is a constraint. Here, a value cannot be inserted without a provenance class and a published method version, and every read carries the label back out with it.
Four classes, no fifth option
Every value belongs to exactly one class. There is no unlabelled state, and no read path that strips the label off on the way out.
Produced by a method
The number was produced by a published method rather than observed. It must carry an interval, or explicitly declare that no interval is available.
Computed from other values
The number is an arithmetic consequence of other labelled values. It inherits the weakest provenance of its inputs.
Taken from a third party
The number came from outside this system. The source is recorded, but the method behind it is not ours to vouch for.
Rules with teeth
These are not conventions the team agrees to follow. They are conditions the database refuses to violate.
- 01
No value without a label
Provenance and method version are NOT NULL at the schema level. There is no application path that can bypass them.
- 02
Modeled means an interval, or an admission
A modeled value carries both bounds, or it states plainly that no interval is available. Silence is rejected by a CHECK constraint.
- 03
Methods are insert-only
You cannot edit a published method. You publish a new version that points at the one it supersedes, and the history stays visible.
- 04
Class changes are audited
When a row moves from modeled to measured — or the other way — the move is recorded with its evidence and its actor.
- 05
Every read carries the label
There is no unlabelled read path, in the UI or the API. A consumer cannot accidentally strip the provenance off.
- 06
The census is counted, never written
The public numbers are computed from live rows. No one can type a friendlier figure into them.
The rejection is the product
A write that omits provenance, omits its method version, or claims to be modeled without an interval does not get a warning. It gets a 422 and a specific reason.
Count what the census admits →POST /api/public/values
{ "subject": "east-corridor",
"metric": "Throughput",
"amount": 7150 }
422 Unprocessable Entity
{ "error": "provenance_required",
"detail": "provenance and method_version
are mandatory on every value" }