Skip to content

Local Vocabulary, and When Not to Mint It

Every code system, naming system and extension in this guide should exist because what it carries had nowhere else to go. This page is the test a new one has to pass, and a record of the forms this guide has since replaced with published ones.

The test matters because the answer is usually already published. Base R4, a published HL7 extension or a national specification often carries the fact already, and a consumer that knows those will look for it there. Where an earlier release minted something a published artifact already covered, 1.26.0 moved to the published answer; the table below lists each one.

The test, in order

Ask these in sequence and stop at the first that answers.

  1. Does a base R4 ELEMENT carry this? Not a similar element — this fact. If an element exists, nothing else is conformant, because a consumer looks where the specification says to look.
  2. Does a PUBLISHED extension carry it? HL7's extensions pack ships hundreds, and this guide already depends on it. A published extension is resolvable, versioned and understood by consumers that have never read this guide.
  3. Does a national or provincial specification carry it? CA Baseline, PS-CA, the Ontario eReferral and eHealth Ontario profiles. A provincial answer is the one a provincial consumer will already have implemented.
  4. Does a published TERMINOLOGY carry the concept? SNOMED CT, LOINC, the HL7 v2 and v3 code systems. Check the binding on the element you are writing: an example or preferred binding still admits the published code, and a preferred binding is FHIR telling you which vocabulary to reach for first.
  5. Only then mint, and say in the artifact what you checked and what it did not answer.

Two rules about carriers that are easy to get wrong

CodeableConcept.coding holds TRANSLATIONS of one concept. Several codings that all say the same thing in different vocabularies — which is precisely why a consumer may take whichever coding it recognises and expect the same answer. A second, different fact placed there is not a translation, and a consumer exercising that entitlement comes away holding the wrong thing. An additional fact about a record goes in an extension.

An Identifier NAMES something and survives a move between servers. If the value is a digest, a computed key, a version marker or an opaque platform handle — anything a reader must not parse, join on or resolve — it is not an identifier, and a NamingSystem declaring an authority for it is a contract that contradicts itself. The prose saying "do not join on this" does not repair the datatype saying you may; a consumer reads the datatype.

Earlier forms, and what to write instead

Each row is deprecated or re-carried in 1.26.0. The old form stays published and representable because stored data carries it; no new writer should reach for it.

Instead of Write Because
diagnostic-report-category#point-of-care SNOMED CT 405262001 |Point of care testing| The concept is published, and DiagnosticReport.category binds example — the SNOMED coding is already conformant
schedule-code#routine ROUTINE from v2-0276 Slot.appointmentType binds that value set at preferred strength in base R4
schedule-code#clinic, #telehealth the appointment modality vocabulary This guide already publishes that axis; one package should not carry two answers
nexus-referral#pulmonary_rehab SNOMED CT 15081005 |Pulmonary rehabilitation| on the service requested Coding the service rather than the referral act dissolves the overlap instead of resolving it
hrm-content-checksum as an Identifier alternate-hash on the attachment, with algorithm = SHA-256 An active published HL7 R4 extension for exactly this; Attachment.hash cannot be used because R4 types it base64Binary and fixes it to sha-1
hrm-file-version as an Identifier an extension, following the hrm-accompanying-* shape The same release already chose extensions for verbatim HRM source fields with nowhere to go
nexus-generated-{schedule,slot} as an Identifier an extension marking the resource as generated Its own description says the value is "not a correlation key" — and as composed it has no UTC offset and no duration, so it could not be one
nexus-clinical-role-assignment as an Identifier an extension carrying the opaque handle Its own description says "do not parse it and do not join on it"
the five contact-by-* tag systems Practitioner.telecom.system + ContactPoint.rank Base R4 models the channel and the preference order; see below
an allergen class in AllergyIntolerance.code.coding the allergen class extension coding is translations of one concept; a class is a different and coarser fact

The contact-preference case, in full

It is the clearest example of the test paying off, because the answer is in base R4 and two independent specifications point at the same element.

Five code systems published one boolean each — contact-by-email, -fax, -hrm, -mail, -phone — on Practitioner.meta.tag. Five existed because the tag writer keeps one tag per system, which is a fact about the writer and not about FHIR. But the axis is modelled already:

  • ContactPoint.system is a required binding over phone | fax | email | pager | url | sms | other.
  • ContactPoint.rank is defined as "Specify preferred order of use (1 = highest)".
  • contactpoint-purpose, an active published extension, carries "the reasons considered appropriate to reach out via this particular mechanism" where a channel is for some correspondence and not all of it.

Two pieces of precedent say rank is the answer. HL7 retired its own iso21090-preferred boolean with the note "DEPRECATED: Use rank element or extension instead" — a boolean flag was tried internationally and withdrawn. And Ontario's own eReferral Practitioner profile constrains Practitioner.telecom.rank directly, so the provincial answer is the same element.

Two channels do not map cleanly, and saying so is part of the answer:

  • Mail is not a ContactPoint. A postal address is Practitioner.address, and R4 gives Address no rank; preference among addresses is use and period.
  • HRM has no code in contact-point-system. system = other carrying the routing value is the conformant carriage, and whether that is sufficient is the one part of this axis that still needs a local decision.

What a minted artifact owes the reader

When the test genuinely comes back empty, say so on the artifact: what you checked, and what it did not answer. The allergen class extension is the worked example — it names the four packages searched, the nearest published thing found, and why that thing answers a different question.

An artifact that does not say what it checked is indistinguishable from one where nobody looked.

Someone else's codes, with no URI of their own

A different case from minting vocabulary: the codes exist and belong to a publisher, but the publisher defines no FHIR URI for them. Health Canada's Drug Product Database and Licensed Natural Health Products Database tables are the standing example.

  • Use the publisher's URI when one exists. A publisher's own FHIR URI, or one HL7 Terminology registers for it, is the only choice; this guide does not mint beside it.
  • Mint under https://fhir.apps.health/ only when none exists, and never on the publisher's own domain: an address there claims to speak for the publisher.
  • A stand-in carries the publisher's codes verbatim. Codes and displays are the publisher's; the stand-in adds nothing to them and removes nothing. Its description says it is a stand-in.
  • A stand-in yields. If the publisher later publishes an official URI, this guide adopts and supports it, and says in the changelog how to move stored data from the stand-in.

The Drug Product Database company code system is one such stand-in; every Health Canada code system, value set and map on this guide's base is another.

Every stand-in is tagged, so one search finds them. Each carries a meta.tag coding in nexus-stand-in-uri, whose code names the publisher. _tag is a search parameter on every resource type, so on a server that keeps meta.tag and supports _tag, ?_tag=https://fhir.apps.health/CodeSystem/nexus-stand-in-uri| finds every stand-in, and adding a code finds one publisher's. The Nexus terminology service does neither for the terminology it serves, so do not search it this way; there, a stand-in is recognised by its canonical and its description.

A stand-in code system has a NamingSystem, holding the stand-in URI as its one unique id today. When a publisher mints an official URI, it is added there as a further unique id, and becomes the preferred one, so tooling treats the two as the same system and stored codings need not be rewritten.