Skip to content

Provenance Profile

Canonicalhttps://fhir.apps.health/StructureDefinition/nexus-emr-core-provenance
Statusdraft · 1.33.0
BaseProvenance (constraint)
SourceFSH · JSON

Attribution for AI-mediated writes, cross-boundary writes and record-lifecycle events such as linking an arriving result to a chart or entering a resource into the record: what was produced, when, by which agent (human or non-human), from what inputs, and -- for generated text -- which verbatim source passage each statement rests on. Used standalone against a produced resource, and contained in an AI-suggestion review Task against the suggestion contained alongside it.

TypedFhir API / Pydantic schema

The typed accessor surface Provenance exposes for Provenance — generated from this IG's compiled profile; each typed accessor has a validating raw-FHIR twin (xRaw) where marked. The three ports are parity-enforced.

The AI-facing shape: from typed_fhir.facade.generated.schemas import ProvenanceSchema — model_json_schema() is a structured-output / tool definition; instantiating validates an extraction. Generated source.

class ProvenanceSchema(BaseModel):
    """AI-facing shape of the Provenance profile: the facade's typed accessor
    surface (curated + salient fields) as a pydantic model. `model_json_schema()` is a
    structured-output / tool schema; instantiating validates an extraction."""

    model_config = ConfigDict(extra="forbid")

    target: Reference | None = Field(
        None,
        description=(
            "The resource(s) this provenance describes. The resources produced or changed by the "
            "activity. For an AI write-back this is the resource the AI produced -- the drafted "
            "DocumentReference, the suggested MedicationRequest, the Task. Multiple targets are "
            "permitted and are the normal case for a single AI action that writes a bundle: one "
            "Provenance covering the set is preferable to one per resource, because the action "
            "was one decision. Note: Per the Nexus EMR logical-reference model these MAY be "
            "identifier-only. A consumer resolving provenance MUST handle a reference with no "
            "literal `reference` -- this is the single most common cause of provenance appearing "
            "'missing' when it is present. Provenance.target — 1..*"
        ),
    )
    recorded: FuzzyDate | None = Field(
        None,
        description=(
            "When this provenance record was created. The instant of time at which the activity "
            "was recorded. Note: This can be a little different from the time stamp on the "
            "resource if there is a delay between recording the event and updating the provenance "
            "and target resource. Provenance.recorded — 1..1"
        ),
    )
    reason: Concept | None = Field(
        None,
        description=(
            "Reason the activity is occurring. The reason that the activity was taking place. "
            "Provenance.reason — 0..*"
        ),
    )
    activity: Concept | None = Field(
        None,
        description=(
            "What kind of activity produced the target. An activity is something that occurs over "
            "a period of time and acts upon or with entities; it may include consuming, "
            "processing, transforming, modifying, relocating, using, or generating entities. "
            "Note: Bound EXTENSIBLE by the base, to `provenance-activity-type`, and a profile "
            "cannot unbind it. That value set has no concept for AI-mediated authorship or for "
            "linking a record to a chart, so it is not asserted for either. For AI-mediated "
            "activity the examples carry `activity.text`. LINKING IS CODED: where a record is "
            "linked to its target -- an arriving result or document attached to a patient's chart "
            "-- `activity` carries the ISO 21089 record-lifecycle event `link` (or `unlink`) from "
            "http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle, which any reader can "
            "interpret, and the `nexus-link-method` extension on `activity` says how: "
            "`automatic`, `confirmed` or `manual`. A validator warns that the ISO code is not in "
            "the extensible value set; that warning is expected. The method is required wherever "
            "the event is present and cannot appear without it (`nexus-prov-link-method`, "
            "`nexus-prov-link-method-event`). For a link or unlink, `target` SHOULD be "
            "version-specific -- the version that carries the resulting subject -- so that "
            "correcting a misfiled record (an `unlink` from the wrong target, then a `link` to "
            "the right one, each with its own method) shows which chart the record left. What the "
            "match was made on and how confident the matcher was are not part of the method; "
            "carry them in `activity.text`. Provenance.activity — 0..1. codes (extensible): ADM | "
            "ALY | ANONY | APPEND | ATND | AUT | AUTHEN | BBY | …"
        ),
    )
    agent: dict | None = Field(
        None,
        description=(
            "Who took part in the action. Who or what was responsible for the activity. For an "
            "AI-mediated action there are normally TWO agents and both matter: • the **non-human "
            "agent** that generated the content -- a Device, identifying the harness and, where a "
            "consumer needs it, the model; • the **human** who reviewed, accepted or attested to "
            "it -- a Practitioner. Recording only the human makes AI-drafted content "
            "indistinguishable from human-authored content, which is the specific outcome this "
            "profile exists to prevent. Recording only the AI loses accountability. Note: "
            "Includes the AI agent and its human supervisor where content was AI-drafted. "
            "Provenance.agent — 1..*"
        ),
    )
    entity: dict | None = Field(
        None,
        description=(
            "The inputs the activity derived from -- for AI, the record context it was given. The "
            "resources the activity used as input. For an AI action this is the record context "
            "the model was given: the resources drawn from the patient compartment that informed "
            "the output. This is what makes an AI output auditable rather than merely "
            "attributable -- \"this draft was generated from these twelve resources\" is a "
            "reviewable claim, where \"this draft came from the harness\" is not. Note: Records "
            "WHICH RESOURCES the activity read, and stays at that grain deliberately: "
            "statement-level attribution -- which generated sentence rests on which passage -- "
            "rides the `attributedFact` extension instead, and a citation there MAY point back to "
            "the entity it was drawn from. For a chart-wide compartment load, listing every "
            "member may still be prohibitively large, and a summarizing convention (the "
            "compartment snapshot's own identifier rather than each member) is the expected "
            "direction for that case. TWO CASES USE IT. For AI-mediated work, each input the "
            "agent was given is an entity with role `source`. For an IMPORT, one Provenance per "
            "import file or feed message and patient covered: `target` is every record the import "
            "wrote for that patient, `agent` names the importer Device (and the person who "
            "started the import, if any), and one entity with role `source` points at the import "
            "file kept as a DocumentReference. A file covering several patients gets one "
            "DocumentReference and one Provenance per patient, with the file sliced or referenced "
            "per patient, so no patient's record carries another's data. Provenance.entity — 0..*"
        ),
    )
    date: FuzzyDate | None = Field(
        None,
        description=(
            "When the activity happened. The period during which the activity occurred. Note: "
            "Preferred over `recorded` as THE date. A provenance written asynchronously (a queued "
            "write-back) has a `recorded` well after the action; dating the action to the "
            "bookkeeping timestamp misplaces it in every timeline. Salient field — "
            "occurredDateTime | occurredPeriod.start | recorded"
        ),
    )