---
title: "ADR 0012. Example data is synthetic and explicitly unsourced"
description: "Every demo and preview uses obviously invented numbers and one shared literal in place of a source, because a plausible example range is a fabricated citation."
url: "https://opsinjs.pensievelabs.org/project/decisions/0012-synthetic-example-data"
source: "https://opsinjs.pensievelabs.org/project/decisions/0012-synthetic-example-data.md"
section: "Project"
kind: "project"
reviewed: "2026-09-20"
reviewer: "clinical"
aliases: ["example data", "synthetic data", "example source", "unsourced example"]
---
> Elements written as `` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> Nothing is missing from this page. The data simply does not live in
> the prose.
## Status [#status]
**Accepted.** 2026-09-03.
## Context [#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](./0009-default-export-is-a-demo.mdx).
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/.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 [#decision]
**One literal, used by every example in the system.**
```ts
export const EXAMPLE_SOURCE = "Example data rather than a reference range"
```
It is exported from the substrate module of
[ADR 0010](./0010-shared-code-ships-with-every-item.mdx), 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 [#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 [#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](../../health/reference-ranges.mdx). An
honestly-declared opinion beats a plausible reference every time; see
[Evidence and references](../../health/evidence-and-references.mdx).
**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 [#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.