Glossary

The A to Z as data. The record shape, how Term resolves an entry, how to propose one, and where the machine-readable copy lives.

The rule

One vocabulary, one file, many surfaces. The plain-English vocabulary is authored once in tokens/glossary.json and consumed everywhere: by Term in a running product, by the filterable A to Z on Plain-English A to Z, by the generated glossary reference, by search, and by the machine-readable output at /r that an agent reads.

This page is about the vocabulary as data. Plain-English A to Z is canonical for the rule. That page says how a replacement word is chosen and why. The two do not restate each other, and assert-ia.mts checks that they do not.

Why it is data and not prose

Three reasons, and the third is the one that decided it.

Consistency is mechanical. A writer cannot remember whether the product says "usual range" or "typical range". A lookup can.
It is checkable. A term used in a component's copy that is not in the file is a build-time question, not a review-time argument.
Agents need it. An agent generating a health screen will otherwise invent plain-English wording, and the wording it invents will be plausible, fluent and subtly clinical. Publishing the vocabulary as JSON turns that from a generation problem into a lookup.

The record shape

Each entry is one clinical term. The fields:

Field	Required	What it is
`term`	yes	The clinical term, as the reader will meet it on a document. Its natural case, so "HbA1c", not "hba1c".
`plain`	yes	The replacement phrase. Two or three words. Used verbatim in copy.
`definition`	yes	One original sentence, written for a lay reader. Never copied from a clinical source.
`seenOn`	no	Where the reader is likely to meet the clinical term, such as a prescription, a results letter, a monitor.
`aliases`	no	Search synonyms and common misspellings.
`category`	no	The health category the term belongs to, from the category axis.

Two rules about the fields. plain is a phrase the product will actually print, so it must read correctly mid-sentence. That means lower case unless it is a proper noun, and no trailing full stop. definition is one sentence, not a paragraph, because it is rendered inside a popover next to a word.

Approved / Rejected

plain: "high blood pressure" with definition: "Blood pressure that stays higher than the usual range over time, rather than on a single reading."

Don’t

plain: "hypertension" with definition: "A chronic medical condition characterised by persistently elevated arterial blood pressure."

The rejected record does both of the things this file exists to prevent: the replacement is the clinical term unchanged, and the definition is written in the register the vocabulary is supposed to translate out of. It also uses "chronic" in the definition of a term whose own entry would replace "chronic".

plain: "average blood sugar" with seenOn: "your results letter and your GP's records"

Don’t

plain: "sugar level" with no seenOn, and the term written in lower case

The second rejection is subtler. "Sugar level" is plainer and it is wrong: it describes a different measurement from the one the term names, and without seenOn the reader has no way to connect the phrase in the app to the code on the letter in their hand.

A complete record, as it appears in the file:

{
  "term": "HbA1c",
  "plain": "average blood sugar",
  "definition": "A blood test that shows the average amount of sugar in your blood over the past two to three months.",
  "seenOn": "your results letter and your GP's records",
  "aliases": ["a1c", "glycated haemoglobin", "haemoglobin a1c"],
  "category": "metabolic"
}

Patterns

Adding an entry. The definition is the hard part. Write it in this order and the register usually takes care of itself:

Say what it is, in one clause

Start with "a", "the" or a verb. Never with the clinical term repeated.

Say what it means for the reader

The clause that answers "so what?". This is the clause that clinical sources omit and lay readers need.

Stop

One sentence. If you need a second, the extra material belongs on a page, and the entry should link to it rather than grow.

Proposing an entry you cannot write. If you know a term needs an entry but cannot write the definition, open it as a proposal rather than adding a weak one; a bad definition is worse than a missing one, because Term will render it confidently. See Proposing a component.

Challenging an entry. Entries are versioned with everything else, and a change to plain is a change to strings a product is printing. Treat it as a breaking change to copy and record it in the changelog.

The rendered list

The full filterable list is rendered on Plain-English A to Z, which is the page to send a writer to. The generated, machine-readable form is at the glossary reference.

This table has not been generated. It is produced by scripts/build-tokens.mts. Run pnpm run generate and reload.

Nothing on this site types a measured number by hand, so an ungenerated table shows this rather than an example.

Banned words

Banned in definition text specifically. These are the words that leak the clinical register back into the file that exists to remove it.

Banned in a definition	Why	Use instead
characterised by, is defined as	Dictionary register; nobody speaks like this.	start with what it is
chronic	The word being defined, or one just like it.	long-term
elevated, decreased, deranged	Clinical comparatives.	higher, lower
patient	The reader is not a patient inside their own app.	you, or people
may be indicative of	Hedged clinical inference.	can be a sign of
pathology, aetiology, presentation	Register with no lay equivalent in context.	rewrite the sentence
refer to your physician	Not the reader's word, and usually not their country.	contact your GP, or whatever your product's route is

Term is the only consumer that resolves a record at runtime. It renders the clinical word with plain and definition available; a term with no record renders as plain text rather than inventing an explanation.
Glossary is the filterable list component.
CareCard and ConsentSheet are the two surfaces most likely to introduce a term the reader has never met, and therefore the two most dependent on this file being complete.

Glossary

On this page