Skip to content

Extraction Evidence Extension

Canonicalhttps://fhir.apps.health/StructureDefinition/nexus-extraction-evidence
Statusdraft (experimental) · 1.33.0
BaseExtension (constraint)
ContextCondition (element), MedicationStatement (element), MedicationRequest (element), AllergyIntolerance (element), Patient (element)
SourceFSH · JSON

The source passage a single extracted field was read from.

FSH

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

// ExtractionEvidenceExtension.fsh
// Per-field evidence for a value lifted out of a document by extraction.
//
// WHY. When a value on a resource was not typed by a clinician but read out of a source
// document, the passage it came from is the only thing that makes it checkable. Provenance
// records that an extraction ran and what it read; it does not record which ELEMENT rests on
// which passage. This extension is the FHIR home for that finer grain, carried on the resource
// the value landed on rather than on the activity that produced it.
//
// THE WIRE SHAPE THIS MIRRORS, and it is already settled in the producer:
//   { field: "Condition.clinical_status", text: "<the passage the value was read from>" }
// one repeat per extracted field. The mapping is 1:1.
//
// RELATIONSHIP TO nexus-attributed-fact, which is the question an implementer will ask first.
// The two look alike and answer different questions:
//
//   nexus-attributed-fact   a generated STATEMENT and the quotes backing it, on Provenance.
//                           Prose that cites. The unit is a sentence in a summary.
//   this extension          a FIELD on a resource and the text it was extracted from, on the
//                           resource. A value that came from somewhere. The unit is an element.
//
// A summary sentence has no element to attach to; an extracted `Condition.onsetDateTime` has no
// sentence. Carrying both under one extension would make the context list the union of every
// resource type plus Provenance and leave a reader unable to tell which sense was meant.
//
// FIRST PASS. Declared ahead of a live write path so the address is governed before anything
// transmits it, and marked experimental accordingly. `field` is a free string today rather than
// a bound element path: the producer's vocabulary is its own model's field names, which do not
// all correspond to a FHIR element, and inventing a mapping here would be a guess. Narrow it
// when a real consumer needs to resolve the values rather than display them.

Alias: $NexusExtractionEvidence = https://fhir.apps.health/StructureDefinition/nexus-extraction-evidence

Invariant:   extraction-evidence-is-substantive
Description: "Both halves must contain something other than whitespace -- a blank field name or passage evidences nothing, leaving a field that claims a source it cannot show"
Severity:    #error
// `value.ofType(string)`, NOT `valueString`: Extension.value[x] is a CHOICE and the publisher
// rejects the shorthand, which would leave the invariant unevaluated and so unenforced.
//
// NON-BLANK, NOT NON-EMPTY. R4's `string` already forbids the empty string, so the rule that adds
// something is "not only whitespace": `matches('[^ \t\r\n]')`, a character that is not a space,
// tab, carriage return or newline, with `matches` unanchored as every other pattern in this guide
// assumes. Written without `\S` on purpose: `\t`, `\r` and `\n` mean the same character whether an
// engine decodes the FHIRPath string escape first or hands it to its regex engine as-is, and `\S`
// does not.
Expression:  "extension('field').value.ofType(string).matches('[^ \\t\\r\\n]') and extension('text').value.ofType(string).matches('[^ \\t\\r\\n]')"

Extension: NexusExtractionEvidence
Id: nexus-extraction-evidence
Title: "Extraction Evidence"
Description: """
The source passage a single extracted field was read from.

Repeats, once per field that was extracted onto this resource. Each repeat names the field and
carries the verbatim text the value was taken from, so a reader can check one value against the
document it came from without re-running the extraction.

`field` is the producer's own name for what was extracted, for example `Condition.clinical_status`.
It is opaque: it is not required to be a resolvable FHIR element path, and a consumer MUST NOT
parse it to navigate the resource. `text` is the passage itself, as it appeared in the source.

This grain is deliberately finer than `Provenance.entity`, which records which documents an
extraction read. A consumer that only needs "where did this resource come from" should read
Provenance and ignore this extension.
"""
* ^url = $NexusExtractionEvidence
* ^status = #draft
* ^experimental = true
* ^context[0].type = #element
* ^context[0].expression = "Condition"
* ^context[1].type = #element
* ^context[1].expression = "MedicationStatement"
* ^context[2].type = #element
* ^context[2].expression = "MedicationRequest"
* ^context[3].type = #element
* ^context[3].expression = "AllergyIntolerance"
* ^context[4].type = #element
* ^context[4].expression = "Patient"
* obeys extraction-evidence-is-substantive
* . ^short = "One extracted field and the source passage it was read from"

* extension contains
    field 1..1 MS and
    text 1..1 MS

* extension[field].value[x] only string
* extension[field] ^short = "The producer's name for the extracted field (opaque; not a navigable path)"
* extension[text].value[x] only string
* extension[text] ^short = "The source passage the value was read from, verbatim"