Skip to content

Source Value Extension

Canonicalhttps://fhir.apps.health/StructureDefinition/nexus-source-value
Statusdraft · 1.33.0
BaseExtension (constraint)
ContextDomainResource (element)
SourceFSH · JSON

Incoming values this guide has no element for, kept on the record they belong to. Each child extension is one source field: its url is the field, https://fhir.apps.health/source-field/<source>/<field>, and its value is what the source held.

FSH

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

// SourceValueExtension.fsh
// Incoming values this guide has no element for, kept on the record they belong to. Each child
// extension is one source field: its `url` names the field, its value is what the source held.
//
// WHY THE CHILD URL IS THE FIELD. A source field is identified by where it came from and what the
// source called it, and nothing else. `https://fhir.apps.health/source-field/<source>/<field>` says
// both in one absolute URI, so a value carries its own origin and no second element can drift from
// it. The `<source>` segment names the system (`oscar`, a migration vendor); `<field>` is the
// source's own name for the field, as the source spells it.
//
// WHY THE DOMAIN MUST BE DECLARED. The child urls are not StructureDefinitions and never will be:
// a source can hold any number of fields, and this guide does not enumerate another system's schema.
// A validator rejects an undeclared relative child url outright, and rejects an absolute one it
// cannot resolve unless it is told the domain is allowed. The guide declares
// `https://fhir.apps.health/source-field/` as an extension domain (`extension-domain` in
// sushi-config.yaml), and a partner validating instances passes the same domain to its validator.
//
// VALUES ARE KEPT EXACTLY. `valueString` is the value as the source held it, leading and trailing
// spaces included; the validator warns about the spaces, and that warning is expected. FHIR has no
// empty string, so a blank is `valueCode` `empty`. A NULL has no child at all: absent is absent.
//
// NOT A MODIFIER. Nothing reads or computes on these values, so ignoring them is always safe.
//
// ONE PER RESOURCE. All of a record's source values sit under one extension, so a reader finds them
// in one place (the context invariant).

Invariant:   nexus-source-value-fields
Description: "Every source value names its field with an absolute url under https://fhir.apps.health/source-field/ (<source>/<field>)."
Severity:    #error
Expression:  "extension.all(url.startsWith('https://fhir.apps.health/source-field/'))"

Invariant:   nexus-source-value-blank
Description: "A coded source value is only ever the code `empty`, for a blank. Anything else the source held is a valueString."
Severity:    #error
Expression:  "extension.value.ofType(code).all($this = 'empty')"

Extension: NexusSourceValue
Id: nexus-source-value
Title: "Source Value Extension"
Description: """
Incoming values this guide has no element for, kept on the record they belong to. Each child
extension is one source field: its `url` is the field,
`https://fhir.apps.health/source-field/<source>/<field>`, and its value is what the source held.

**A last resort.** A value goes here only when no mapped element, no coding (even an unknown code)
and no existing HL7 extension can carry it. Never a note or free text.

**Kept exactly.** `valueString` is the value as the source held it, leading and trailing spaces
included. A blank is `valueCode` `empty`, because FHIR has no empty string. A NULL has no child.

**Nothing computes on it.** Source values are not searched, and no decision support or measure
reads them. A client that saves a resource keeps the extension it read.

**Validation.** The child urls are not StructureDefinitions. A validator must be told the
`https://fhir.apps.health/source-field/` domain is allowed (the validator CLI's
`-extension https://fhir.apps.health/source-field/`), or it rejects every child.

At most one on a resource.
"""
* ^url = "https://fhir.apps.health/StructureDefinition/nexus-source-value"
* ^status = #draft
* ^date = "2026-11-11"
* ^publisher = "WELLSTAR Technologies Corp."
* ^contact.name = "Nexus EMR FHIR Implementation Guide"
* ^contact.telecom.system = #url
* ^contact.telecom.value = "https://fhir.apps.health"
* ^jurisdiction = urn:iso:std:iso:3166#CA "Canada"
* ^context[0].type = #element
* ^context[0].expression = "DomainResource"
* ^contextInvariant[0] = "extension.where(url = 'https://fhir.apps.health/StructureDefinition/nexus-source-value').count() = 1"
* obeys nexus-source-value-fields
* obeys nexus-source-value-blank
* . ^short = "Source values with no element in this guide, one child per source field"
* . ^definition = "The values a source held that this guide has no element for, on the record they belong to. Each child extension is one field: `url` = `https://fhir.apps.health/source-field/<source>/<field>`, value = the value exactly as the source held it."
* value[x] 0..0
* extension 1..*
* extension ^short = "One source field: url = .../source-field/<source>/<field>"
* extension ^comment = "The url is the field and is absolute, under https://fhir.apps.health/source-field/ (invariant `nexus-source-value-fields`). `<source>` names the system the value came from; `<field>` is the source's own name for the field."
* extension.value[x] only string or code
* extension.value[x] ^short = "The value as the source held it, or the code `empty` for a blank"
* extension.value[x] ^comment = "`valueString` exactly as held, leading and trailing spaces kept (a validator warns about them; that is expected). `valueCode` `empty` for a blank, and no other code (invariant `nexus-source-value-blank`). A NULL has no child."