View raw Markdown
type: resourceresource: Provenance

Provenance

Introduction

Scope and Usage

The Provenance resource tracks information about the activity that created, revised, deleted, or signed a version of a resource, describing the entities and agents involved. This information can be used to form assessments about its quality, reliability, trustworthiness, or to provide pointers for where to go to further investigate the origins of the resource and the information in it.

Provenance resources are a record-keeping assertion that gathers information about the context in which the information in a resource was obtained. Provenance resources are prepared by the application that initiates the create/update etc. of the resource. An AuditEvent resource contains overlapping information, but is created as events occur, to track and audit the events. AuditEvent resources are often (though not exclusively) created by the application responding to the read/query/create/update/etc. event.

Boundaries and Relationships

Many other FHIR resources contain some elements that represent information about how the resource was obtained, and therefore they overlap with the functionality of the Provenance resource. These properties in other resources SHOULD always be used in preference to the Provenance resource, and the Provenance resource SHOULD be used where additional information is required, or explicit record or provenance is desired. Details on this overlap can be found on the FiveWs, including a mapping at the Resource Element level.

The relationship between a resource and its provenance is established by a reference from the provenance resource to its target. In this way, provenance MAY be provided about any resource or version, including past versions. There MAY be multiple provenance records for a given resource or version of a resource.

Background and Context

The Provenance resource is based on the W3C Provenance specification, and mappings are provided. The Provenance resource is tailored to fit the FHIR use-cases for provenance more directly. In terms of W3C Provenance the FHIR Provenance resource covers "Generation" of "Entity" with respect to FHIR defined resources for creation or updating; whereas AuditEvent covers "Usage" of "Entity" and all other "Activity" as defined in W3C Provenance.

The W3C Provenance Specification has the following fundamental model:

Key concepts

Where:

The Provenance resource corresponds to a single activity that identifies a set of resources (target) generated by the activity. The activity also references other entities (entity) that were used and the agents (agent) that were associated with the activity. To record multiple activities that resulted in one (target), record each (activity) in independent Provenance records all pointing at that (target).

The Provenance resource depends upon having References to all the resources, entities, and agents involved in the activity. These References need not be resolvable. The references must provide a unique and unambiguous identification. If a resource, entity, or agent can have different versions that must be identified, then the Reference must have versioning information included.

Versioning and unique identification are not mandated for all systems that provide Resources, entities, and agents. But, inclusion of Provenance requirements MAY introduce requirements for versioning and unique identification on those systems

The Provenance resource is based on leveraging the W3C Provenance specification to represent HL7 support of provenance throughout its standards and explicitly modeled as functional capabilities in ISO/HL7 10781 EHR System Functional Model Release 2 and ISO 21089 Trusted End-to-End Information Flows. Mappings are provided. The Provenance resource is tailored to fit the FHIR use-cases for provenance more directly. In terms of W3C Provenance the FHIR Provenance resources covers "Generation" of "Entity" with respect to FHIR defined resources for creation or updating; whereas AuditEvent covers "Usage" of "Entity" and all other "Activity" as defined in W3C Provenance.

Notes

Using the Provenance Resource

The Provenance resource identifies information about another resource (the target element). The Provenance resource MAY be used in several different ways:

The resources found in a Bundle are often the latest version and don't have a version identified, yet Provenance resources in the Bundle MAY have references (e.g. .target) to version specific resources. When de-referencing resource references that MAY have a version identified one SHOULD look for the non-version resource found in the Bundle.

On a RESTful system, the target resource reference SHOULD be version specific, but this requires special care: For new resources that need to have a corresponding Provenance resource, the version-specific reference is often not knowable until after the target resource has been updated. This can create an integrity problem for the system - what if the Provenance resource cannot be created after the target resource has been updated? To avoid any such integrity problems, the target resource and the Provenance resources SHOULD be submitted as a pair using a transaction (see the Transaction Example). Alternatively, the Provenance http header MAY be used if supported.

Element Level Provenance

The Provenance.target MAY point at a specific element within the targeted resource using the target element extension or target path extension. For example when updating a Patient resource with a new official name, such as shown in example 1, where the Provenance is indicating that the official name was provided by the Patient themselves.

HTTP Header

The custom header X-Provenance to provide a provenance resource when performing PUT or POST operations using the RESTful interface:

POST [base]/Observation Content-Type: application/fhir+? X-Provenance: { "resourceType": "Provenance", "location": { "reference": "Location/1" }," agent" ... }

[body]

The intent is that the server picks up the provenance, fills out the target, and then stores the provenance information as it normally would. Notes:

Signatures

The Provenance resource includes a signature element (digital signature) which can be used for standards based integrity verification and non-repudiation purposes. The Signature datatype provides details on use of the signature element. The Signature.type coded value of "Source" SHOULD be used when the signature is for simply proving that the resource content is the same as it was when the resource was updated or created.

Provenance of Removal

A Provenance record can be recorded to indicate who deleted a Resource. If versioning is supported, the version that was deleted is referenced in Provenance.target; if versioning is not supported then Provenance.target contains the non-version reference. Provenance.entity is not used unless there is a business requirement to do so.

Use of Provenance to record Import and Transform

Provenance can be used to record activities of an automaton that transforms input. Such as middleware that extracts information from a HL7 V2 message and creates FHIR resources, or middleware that extracts information from an HL7 CDA document and creates FHIR resources, etc. The Provenance in these cases is recording the activity of the middleware.

The middleware in this case would, in addition to creating the target resources, create a Provenance resource that indicates all the target resources (using Provenance.target). The middleware is identified as one of the Provenance.agent elements, with the Provenance.agent.type of assembler.

The middleware MAY record the source as another Provenance.agent element.

The original content is optionally saved. This might be as a DocumentReference, or Binary. The Provenance.entity would then point at this original content.

The original source might include some form of 'provenance' to cover the history of the original content prior to the import transformation. This original source 'provenance' SHOULD be converted into FHIR Provenance records as appropriate.

Examples of this activity with Provenance profile can be found in the IHE Implementation Guides for

Multiple Patients Affected

Where a provenance activity impacts more than one Patient/Subject; multiple Provenance resources SHOULD be recorded, one for each Patient/Subject. This best enables segmentation of the Provenance details so as to limit the Privacy impact. The use of multiple Provenance is a best-practice and SHOULD be driven by a Policy. There will be cases where the use of multiple Provenance resources is not necessary, such as public health reporting.

Relevant History Provenance

Some Event pattern or Request pattern resources will have a relevantHistory element. These elements would point to a subset of all Provenance about that resource that are considered relevant. For further guidance on relevantHistory see Event history pattern or Request history pattern.

StructureDefinition

Elements (Simplified)

Mappings

Implementation Guide

implementationguide-Provenance-core.xml

<?xml version="1.0" encoding="UTF-8"?>

<ImplementationGuide xmlns="http://hl7.org/fhir">
  <id value="Provenance-core"/>
  <extension url="http://hl7.org/fhir/build/StructureDefinition/introduction">
    <valueString value="provenance-relevant-history-introduction.xml"/>
  </extension>
  <extension url="http://hl7.org/fhir/build/StructureDefinition/notes">
    <valueString value="provenance-relevant-history-notes.xml"/>
  </extension>
  <version value="2025-11-01"/>
  <name value="ProvenanceRelevantHistory"/>
  <title value="Provenance  Relevant  History"/>
  <status value="active"/>
  <date value="2025-11-01"/>
  <publisher value="Health Level Seven International"/>
  <description value="Guidance on using Provenance for related history elements"/>
  <definition>
    <resource>
      <reference>
        <reference value="StructureDefinition/provenance-relevant-history"/>
      </reference>
    </resource>
  </definition>
</ImplementationGuide>

Resource Packs

list-Provenance-packs.xml

<?xml version="1.0" encoding="UTF-8"?>

<List xmlns="http://hl7.org/fhir">
  <id value="Provenance-packs"/>
  <status value="current"/>
  <mode value="working"/>
  <entry>
    <item>
      <reference value="ImplementationGuide/Provenance-core"/>
    </item>
  </entry>
</List>

Search Parameters

Full Search Parameters

Examples

Full Examples

Mapping Exceptions

provenance-event-mapping-exceptions.xml

Divergent Elements

Unmapped Elements

provenance-fivews-mapping-exceptions.xml

Divergent Elements

Unmapped Elements