Allergen Class Extension

Canonical	../StructureDefinition/nexus-allergen-class-extension
Status	draft · 1.26.0
Base	Extension (constraint)
Context	AllergyIntolerance (element)
Source	FSH · JSON

What kind of thing the recorded allergen is: a single drug, a drug class, a food, an environmental substance or a vaccine.

FSH

The authored source of truth: extensions/AllergenClassExtension.fsh (edit on GitHub). One FSH file may define several related artifacts.

// AllergenClassExtension.fsh
// WHAT KIND of thing a recorded allergen is -- as an extension, because `code.coding` is not a
// place a second FACT may go.
//
// WHY THIS EXISTS SEPARATELY FROM THE CODE SYSTEM. The vocabulary was never the problem. The
// concept it carries is well argued and `AllergyIntolerance.category` genuinely cannot express it:
// a reaction recorded against one drug and a reaction recorded against a whole drug class are both
// `medication`, and an interaction check against a new prescription has to know which of the two it
// is looking at. What was wrong was the CARRIER.
//
// R4 DEFINES `CodeableConcept.coding` AS TRANSLATIONS OF ONE CONCEPT -- several codings that all
// say the same thing in different vocabularies, which is why a consumer may pick whichever coding
// it understands and get the same answer. An allergen's CLASS is not a translation of the allergen;
// it is a coarser, orthogonal fact about it. Carried in `code.coding` it puts two concepts at two
// levels into an array a reader is entitled to treat as synonyms, distinguishable only by system --
// so a consumer that picks "whichever coding it recognises" can come away holding `drug class`
// where it believed it held the substance.
//
// AN EXTENSION IS THE ELEMENT FOR AN ADDITIONAL FACT, and that is the whole of the fix. Two pieces
// of published precedent, both checked in `hl7.fhir.uv.extensions.r4` rather than recalled:
//
//   * THE NEIGHBOURING FACETS OF THIS RESOURCE are all extensions --
//     `allergyintolerance-certainty`, `-assertedDate`, `-abatement` and `-reasonRefuted`. Each is a
//     true statement about an allergy record that no element models, which is this case exactly.
//   * CLASSIFYING A SUBSTANCE IS ITSELF DONE ON AN EXTENSION. `medication-classification` carries a
//     medication's anatomical, therapeutic, pharmacologic or chemical class on an extension over
//     `Medication`, with its own code system for the KIND of classification. It answers a different
//     question from this one -- it classifies a product rather than saying whether a recorded
//     allergen is one substance or a family -- but it settles the shape: HL7 does not put a
//     classification of a substance into the `coding` array that names the substance.
//
// NO PUBLISHED EXTENSION CARRIES THIS CONCEPT, which is why one is minted here. Searched the HL7
// extensions pack, PS-CA, CA Baseline and US Core; the nearest is the medication classification
// above, and it is not the same fact.
//
// WHY NOT SNOMED SUBSUMPTION, which is the obvious objection. SNOMED does distinguish a substance
// from a class, and a terminology server can answer "is this concept a drug class" by subsumption
// against the recorded code. That answer is correct and is not available where it is needed: the
// check runs at prescribing time, inside the EMR, against a record that may carry a local or an
// inbound coding rather than SNOMED at all. Stating the class on the record makes the answer
// readable without a terminology round-trip and without assuming which vocabulary the substance
// arrived in.
//
// CONTEXTED ON THE RESOURCE, not on `code`. The class qualifies the allergy that was recorded
// rather than any one coding of the substance, and a record whose substance is coded twice must
// not be able to carry two different classes.

Extension: NexusAllergenClass
Id: nexus-allergen-class-extension
Title: "Allergen Class Extension"
Description: """
What kind of thing the recorded allergen is: a single drug, a drug class, a food, an environmental
substance or a vaccine.

**It determines `category`, and says the thing `category` cannot.** Every value here maps onto
exactly one of R4's four `AllergyIntolerance.category` values, and two of them -- `drug` and
`class` -- map onto the same one. That collision is the point: a reaction recorded against one
medicinal substance and a reaction recorded against a whole family of them are both `medication`,
and a cross-sensitivity check against a new prescription needs to know which it is reading.

**It is a fact about the record, not a translation of the substance.**
[`AllergyIntolerance.code`](StructureDefinition-nexus-emr-core-allergyintolerance.md) carries WHAT
the patient reacted to, and every coding in it says that same thing in a different vocabulary. This
says WHAT KIND, which is a different and coarser statement, so it rides an element of its own.

**At most one per record.** A record whose substance carries several codings still describes one
allergen and therefore one class.

**MIGRATION.** Write this extension. Records written before it exists carry the class as an
additional coding inside `AllergyIntolerance.code.coding`, under the same code system; that
carriage is not part of this specification and is not produced going forward. A reader of older
records has to read it from where it was written, and must not mistake it for a translation of the
substance while doing so. Moving the existing data is outstanding work and is not described here.
"""
* ^url = "../StructureDefinition/nexus-allergen-class-extension"
* ^status = #draft
* ^experimental = false
* ^context[0].type = #element
* ^context[0].expression = "AllergyIntolerance"

* value[x] only Coding
* value[x] 1..1
* value[x] from ../ValueSet/nexus-allergen-class (required)
* value[x] ^short = "What kind of thing the allergen is"
* value[x] ^definition = "The allergen's kind, from the allergen class vocabulary. A required binding: the set is closed and complete -- it is the five kinds this estate's allergen picker assigns -- so a value outside it is not an extension of the concept but a different one, and belongs in a different element."