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.
- 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.
- 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.
- 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.
- 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
exampleorpreferredbinding still admits the published code, and apreferredbinding is FHIR telling you which vocabulary to reach for first. - 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.systemis a required binding overphone | fax | email | pager | url | sms | other.ContactPoint.rankis 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 givesAddressnorank; preference among addresses isuseandperiod. - HRM has no code in
contact-point-system.system = othercarrying 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.