ADR 0012. Example data is synthetic and explicitly unsourced

Status

Accepted. 2026-09-03.

Context

Four rules that are individually correct meet at one line of one file, and the obvious way to satisfy all four is a fabrication.

The rules are these. A reference range must name its owner: ReferenceRange.source is required, and the interface explains that "a band with no provenance is an assertion with no author". A range without one is a safety error, OPSIN-0004, whose message asks the caller to name "a laboratory, a device maker, or a clinician". opsinjs ships no reference ranges for any metric, for any population, because they belong to the product's laboratory and clinical team and not to a component library. And nobody in this project invents a citation, ever.

The line where they meet is the demo of ADR 0009. A RangeBar demo has to render a band or it demonstrates nothing, a band needs a source, and the implementer writing it has a deadline. The answer that arrives unbidden is source: "NHS". That is a fabricated citation attached to a fabricated range, in a file that ships verbatim into other people's repositories, rendered as a screenshot on a public documentation site, and served as text through /r/<name>.json to programs that read it as fact.

The screenshot is the part that makes this worse than an ordinary careless example. A picture showing a plausible number against a plausible band under a recognised organisation's name is indistinguishable from a picture of somebody's result, and it will outlive the page it came from.

Decision

One literal, used by every example in the system.

export const EXAMPLE_SOURCE = "Example data rather than a reference range"

It is exported from the substrate module of ADR 0010, so all sixty components use the same string and a single search finds every example range in the repository.

The rules that go with it, all of them hard:

• ReferenceRange.source in an example is always EXAMPLE_SOURCE. Never a laboratory, a guideline body, a device manufacturer, a study, a country's health service, or an abbreviation that resembles one.
• Numbers are not plausible readings wherever the specification permits it. Use round and obviously invented numbers in preference to anything a reader could mistake for their own result. A band of ten to twenty with a value of fourteen is the shape. Where the specification forces a realistic shape, such as a paired blood-pressure reading or a temperature, keep the shape and the unit and choose a value nobody would act on.
• Labels name a fictional measurement. "Example measurement", "Sample reading", "Test value". Never a real metric's name attached to a number.
• Never ship a threshold, a plausibility bound, a score band, a staleness default, an emergency number or default disclaimer wording, for any metric, in any population. An example is not an exception. An omitted one renders an explicit absence, never a substituted default.

Consequences

• Previews look deliberately unreal, and that is the point. A screenshot of this system must never be mistakable for a screenshot of somebody's result. The cost is that a preview demonstrates the geometry, the alignment of the numerals, the two colour axes and the layout under 200% text, and does not demonstrate what a real reading looks like. The specification pages carry that in prose, where it can be reviewed.
• OPSIN-0004 stays satisfied without being weakened. The example passes the check by naming a real non-source, not by exempting examples from the check. This matters more than it looks: the fastest way to make a demo compile is to add an exemption, and an exemption is permanent.
• The string is user-visible text in a file that ships. A consumer who installs a component and forgets to replace the demo's data ships "Example data rather than a reference range" to a reader. That is a visible, self-explaining failure rather than a plausible one, which is the whole design of the literal.
• One string means one search. EXAMPLE_SOURCE finds every example range in the source; the rendered string finds every screenshot of one, including in somebody else's slide deck.
• This does not replace the never-invent rule, it is what makes the rule survivable. An implementer with an empty source: field and a deadline now has an answer that is neither a fabrication nor a blocked build, which is the condition under which rules are actually followed.

Alternatives considered

Realistic example data with a real citation. Rejected twice over. It requires a real reference range, which opsinjs does not own and explicitly does not ship, and a real citation, which nobody here is in a position to verify for sixty components. See Reference ranges. An honestly-declared opinion beats a plausible reference every time; see Evidence and references.

Realistic example data with an obviously fake source. The most dangerous option on the list, and the one most likely to be proposed, because it survives review: the reviewer looks at the source field, sees that it is marked as an example, and approves. Rejected because the number is the part a reader acts on, and the number is what gets cropped into a slide, copied into a design file, or read by somebody who never looks at the source field.

Make source optional for examples, or exempt demo files from OPSIN-0004. Rejected on principle. Making an enforcer lenient in order to get past it is not something this project does; the check exists precisely because an unsourced range looks finished, and a demo file is exactly where the appearance of being finished is most convincing.

Render every demo in its empty state, with no example data at all. Genuinely tempting, since an absent value is a first-class state that every component must handle anyway, and it removes the whole problem. Rejected because the empty state is one state out of several, and a preview that can only ever show the absence of a value cannot demonstrate the layout, the numerals, the range geometry or the colour axes, which is most of what a preview is for. The empty state gets an example of its own instead.

Revisiting this

Revisit when a specification genuinely needs a realistic shape to be legible and the round-numbers rule makes the preview misleading rather than merely unreal. A paired blood-pressure reading is the obvious candidate. The answer there is a realistic shape with a value nobody would act on, which this record already permits; it is written down here because it is the boundary somebody will argue about, and the argument should start from the permission rather than from the prohibition.

Edit this page

Last read through against the system on 2026-09-20. Due for review every 6 months; expiry is reported by pnpm run check:freshness.