Skip to content

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 as demographicext.city_mailing under oscar.
  • The value is exactly what the source held. valueString, leading and trailing spaces kept. A blank is valueCode empty, 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

  1. 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.
  2. 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.
  3. A client that saves a resource keeps the extension it read, unchanged.
  4. Values are shown in the narrative (narrative status extensions), except oscar/ values, which are gateway bookkeeping. A value placed in the narrative is XHTML-escaped: it is the source's text, never markup.
  5. 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:

  • target is every record the import wrote for that patient;
  • recorded is when;
  • agent names the importer, a Device, and the person who started the import, if any;
  • one entity with role source points at the import file, kept as a DocumentReference.

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.