Source values¶
An incoming value this guide has no element for is kept on the record it belongs to. It goes in
one extension, nexus-source-value, with
one child per source field. The child's url is the field and its value is exactly what the source
held, so nothing a source sent is lost and nothing has to be invented to hold it.
It is the last stop after Carrying the raw code and Local vocabulary: those keep what a source said inside elements this guide defines; this keeps what had nowhere to go.
The shape¶
"extension": [ {
"url": "https://fhir.apps.health/StructureDefinition/nexus-source-value",
"extension": [
{ "url": "https://fhir.apps.health/source-field/cds-vendor-a/ClinicCampaign", "valueString": "Fall 2019 flu clinic" }
]
} ]
- The url is the field:
https://fhir.apps.health/source-field/<source>/<field>.<source>names the system (oscar, a migration vendor);<field>is the source's own name for the field, such asdemographicext.city_mailingunderoscar. - The value is exactly what the source held.
valueString, leading and trailing spaces kept. A blank isvalueCodeempty, because FHIR has no empty string, and no other code is allowed. A NULL gets no child. - At most one extension per resource, holding every source value on it. It is not a modifier.
Worked examples: a migrated immunization and an OSCAR gateway patient.
The rules¶
- A last resort, in this order: a mapped element; a coding, even with an unknown code; an existing HL7 extension; only then a source value. Never a note or free text.
- Nothing computes on source values. They are not searched, and no decision support or measure reads them. The CQL model can retrieve a Source Value Record, as it can any profile; the rule is that nothing computes on it.
- A client that saves a resource keeps the extension it read, unchanged.
- Values are shown in the narrative (narrative status
extensions), exceptoscar/values, which are gateway bookkeeping. A value placed in the narrative is XHTML-escaped: it is the source's text, never markup. - Where a value came from: the url's
<source>segment names the system. For an import, the import's Provenance names the file, the importer and the time.
OSCAR gateway values¶
The OSCAR gateway uses oscar/ values to give back exactly what OSCAR held when a FHIR element
cannot say it: a blank, or a value with spaces the element has trimmed. The
gateway patient example has
oscar/demographic.pref_name = empty and oscar/demographicext.city_mailing = " Marie ", with
the address city Marie.
On a write, the gateway maps each oscar/ value again. If the result equals the current element,
the original goes back to OSCAR (" Marie ", the blank). If it does not, the client has edited the
element, the edit wins, and the edit is what is written.
Values with no record to sit on¶
A whole source category this guide does not model, or a value about the patient that no resource
carries, goes on a NexusCoreSourceValueRecord:
a Basic with code
naming the category under https://fhir.apps.health/source-field/<source>, the patient as
subject,
created,
and the values in the extension. One per patient per source category; it declares the profile in
meta.profile, which is what tells it apart from an app-state Basic. See the
migrated category example.
A SMART scope names a resource type, not a profile, so an app granted basic scopes for app state
can read, write and delete source value records too. Limiting who may write them is a server
decision; the profile cannot express it.
Imports¶
An import is recorded with an ordinary
NexusEmrCoreProvenance, one per
import file or feed message and patient covered:
targetis every record the import wrote for that patient;recordedis when;agentnames the importer, aDevice, and the person who started the import, if any;- one
entitywith rolesourcepoints at the import file, kept as aDocumentReference.
See the import Provenance example.
A file covering several patients gets one DocumentReference and one Provenance per patient
covered, with the file sliced or referenced per patient. A single DocumentReference for the whole
file would sit in one patient's record and carry the others' data with it.
Validating¶
The child urls are not StructureDefinitions, and a validator rejects an extension url it cannot
resolve. Allow the domain: with the HL7 validator CLI, pass
-extension https://fhir.apps.health/source-field/. Leading or trailing spaces in a valueString
draw a warning; that is expected.