ValueSet Secondary Coding Extension

Canonical	../StructureDefinition/valueset-secondary-coding
Status	draft · 1.26.0
Base	Extension (constraint)
Context	ValueSet.expansion.contains (element)
Source	FSH · JSON

A second coding for one member of a pre-expanded ValueSet, carried on that member beside its own system and code. Repeats: a member with two secondary codings carries two.

Overview

SUPERSEDED BY A PUBLISHED EXTENSION. Write http://hl7.org/fhir/5.0/StructureDefinition/extension-ValueSet.expansion.contains.property instead. R4's ValueSet.expansion.contains has no element for a per-member property, which is why this extension was minted. R5 adds expansion.contains.property -- and HL7 publishes that element back to R4 as an extension, ACTIVE, fhirVersion 4.0.1, contexted on ValueSet.expansion.contains, in hl7.fhir.uv.xver-r5.r4. It was already available when this one was written.

It is a strict superset, and the difference is the part that matters. The published extension carries a code child naming WHAT THE PROPERTY IS, beside a value child that admits code, Coding, string, integer or boolean -- and a subProperty for nested pairs. This extension has only a value, so what the value MEANS has to be inferred from valueCoding.system.

That inference fails on a case this guide already has. The allergen picker's list annotates each member with an allergen class, and the problem picker's list annotates each member with a classification edition. Both are axes over expansion members; the moment two axes are drawn from ONE vocabulary, system no longer tells them apart and there is nowhere to say which is which. The published extension names the axis explicitly and does not have that failure mode.

ADOPTING IT NEEDS A DEPENDENCY. hl7.fhir.uv.xver-r5.r4 is not currently pinned by this guide, and it must be declared before a validator can resolve the canonical. That declaration belongs with the change that moves the writer, not ahead of it -- the package carries over 1,400 StructureDefinitions and pinning it for an extension nothing yet writes would add weight for no reader.

What it buys. These lists ship pre-expanded and are filtered in the client, so the second code travels with the member the user picks. The picker can then emit a complete CodeableConcept -- the member's own coding, followed by each secondary coding -- rather than resolving a map after the fact. The allergen class rides this way on the allergen picker's list, so an entry knows what kind of allergen it is at the moment it is recorded; the problem picker carries a classification coding the same way, the edition named by that coding's own system.

Read it by the value's system -- and this is the limitation that supersedes it. The extension URL says only that a second code is present; what the code IS comes from valueCoding.system. Repeats are in no guaranteed order and a member may carry more than one, so infer nothing from position either. Two axes drawn from one vocabulary are indistinguishable under this rule, which is exactly what the published extension's code child exists to state.

It annotates a member; it does not decide membership. A concept is in the set because compose includes it. This adds a code to a member and never adds or removes one.

MIGRATION. Nexus EMR writes this extension today at https://fhir.nexus.health/StructureDefinition/valueset-secondary-coding (FHIR-374): it is live in seeded expansions and in code, and is under migration to the canonical declared here. That address shares the final segment valueset-secondary-coding with the canonical, so matching that segment reads both -- but it does NOT read the second address below.

A SECOND PRE-MIGRATION ADDRESS, which no suffix rule reaches. The earliest form of this extension was spelled for one classification and is written at https://fhir.nexus.health/StructureDefinition/valueset-secondary-icd10 (FHIR-374). It is the same extension under a narrower name -- the same value, the same reading rule, and the classification it carries is named by valueCoding.system rather than by the URL -- so this guide declares one canonical for both rather than a second artifact for the special case. It is the address the seeded problem picker's classification codings are filed under today. It has no segment in common with the canonical and must be matched exactly; a reader built on the suffix alone misses every member filed under it. Write the canonical, and neither of these.