This page is part of the FHIR Specification (v1.0.0: DSTU 2 Ballot 3). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

6.4 Resource Provenance - Content

Security

Work Group

Maturity Level: 1

Compartments: Device, Patient, Practitioner, RelatedPerson

Provenance of a resource is a record that describes entities and processes involved in producing and delivering or otherwise influencing that resource. Provenance provides a critical foundation for assessing authenticity, enabling trust, and allowing reproducibility. Provenance assertions are a form of contextual metadata and can themselves become important records with their own provenance. Provenance statement indicates clinical significance in terms of confidence in authenticity, reliability, and trustworthiness, integrity, and stage in lifecycle (e.g., Document Completion - has the artifact been legally authenticated), all of which may impact Security, Privacy, and Trust policies.

6.4.1 Scope and Usage

The provenance resource tracks information about the activity that created a version of a resource, including the entities, and agents involved in producing a resource. This information can be used to form assessments about its quality, reliability or 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. A Audit Event resource contains overlapping information, but is created as events occur, to track and audit the events. Audit Event resources are often (though not exclusively) created by the application responding to the read/query/create/update etc. event.

6.4.2 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, though overlap can occur.

6.4.3 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 resources covers "Generation" of "Entity" with respect to FHIR defined Resources for creation or updating; where as Audit Event 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:

Target - An Entity that is a FHIR Resource instance that is Created, Updated, or Deleted.
Entity - An entity is a physical, digital, conceptual, or other kind of thing with some fixed aspects; entities may be real or imaginary.
Agent - An agent is something that bears some form of responsibility for an activity taking place, for the existence of an entity, or for another agent's activity.
Activity - 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.

The Provenance resource actually 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.

Structure

Name	Flags	Card.	Type	Description & Constraints
Provenance	Σ		DomainResource	Who, What, When for a set of resources
target	Σ	1..*	Reference(Any)	Target Reference(s) (usually version specific)
period	Σ	0..1	Period	When the activity occurred
recorded	Σ	1..1	instant	When the activity was recorded / updated
reason	Σ	0..*	CodeableConcept	Reason the activity is occurring PurposeOfUse (Extensible)
activity	Σ	0..1	CodeableConcept	Activity that occurred ProvenanceEventCurrentState (Extensible)
location	Σ	0..1	Reference(Location)	Where the activity occurred, if relevant
policy	Σ	0..*	uri	Policy or plan the activity was defined by
agent	Σ	0..*	BackboneElement	Agents involved in creating resource
role	Σ	1..1	Coding	What the agents involvement was ProvenanceParticipantRole (Extensible)
actor	Σ	0..1	Reference(Practitioner \| RelatedPerson \| Patient \| Device \| Organization)	Individual, device or organization playing role
userId	Σ	0..1	Identifier	Authorization-system identifier for the agent
relatedAgent	Σ	0..*	BackboneElement	Track delegation between agents
type	Σ	1..1	CodeableConcept	Type of relationship between agents v3 Code System RoleLinkType (Example)
target	Σ	1..1	uri	Reference to other agent in this resource by id
entity	Σ	0..*	BackboneElement	An entity used in this activity
role	Σ	1..1	code	derivation \| revision \| quotation \| source ProvenanceEntityRole (Required)
type	Σ	1..1	Coding	The type of resource in this entity ResourceType (Extensible)
reference	Σ	1..1	uri	Identity of entity
display	Σ	0..1	string	Human description of entity
agent	Σ	0..1	see agent	Entity is attributed to this agent
signature	Σ	0..*	Signature	Signature on target
Documentation for this format

UML Diagram

XML Template

<Provenance xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <target><!-- 1..* Reference(Any) Target Reference(s) (usually version specific) --></target>
 <period><!-- 0..1 Period When the activity occurred --></period>
 <recorded value="[instant]"/><!-- 1..1 When the activity was recorded / updated -->
 <reason><!-- 0..* CodeableConcept Reason the activity is occurring --></reason>
 <activity><!-- 0..1 CodeableConcept Activity that occurred --></activity>
 <location><!-- 0..1 Reference(Location) Where the activity occurred, if relevant --></location>
 <policy value="[uri]"/><!-- 0..* Policy or plan the activity was defined by -->
 <agent>  <!-- 0..* Agents involved in creating resource -->
  <role><!-- 1..1 Coding What the agents involvement was --></role>
  <actor><!-- 0..1 Reference(Practitioner|RelatedPerson|Patient|Device|
    Organization) Individual, device or organization playing role --></actor>
  <userId><!-- 0..1 Identifier Authorization-system identifier for the agent --></userId>
  <relatedAgent>  <!-- 0..* Track delegation between agents -->
   <type><!-- 1..1 CodeableConcept Type of relationship between agents --></type>
   <target value="[uri]"/><!-- 1..1 Reference to other agent in this resource by id -->
  </relatedAgent>
 </agent>
 <entity>  <!-- 0..* An entity used in this activity -->
  <role value="[code]"/><!-- 1..1 derivation | revision | quotation | source -->
  <type><!-- 1..1 Coding The type of resource in this entity --></type>
  <reference value="[uri]"/><!-- 1..1 Identity of entity -->
  <display value="[string]"/><!-- 0..1 Human description of entity -->
  <agent><!-- 0..1 Content as for Provenance.agent Entity is attributed to this agent --></agent>
 </entity>
 <signature><!-- 0..* Signature Signature on target --></signature>
</Provenance>

JSON Template

{
  "resourceType" : "Provenance",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "target" : [{ Reference(Any) }], // R!  Target Reference(s) (usually version specific)
  "period" : { Period }, // When the activity occurred
  "recorded" : "<instant>", // R!  When the activity was recorded / updated
  "reason" : [{ CodeableConcept }], // Reason the activity is occurring
  "activity" : { CodeableConcept }, // Activity that occurred
  "location" : { Reference(Location) }, // Where the activity occurred, if relevant
  "policy" : ["<uri>"], // Policy or plan the activity was defined by
  "agent" : [{ // Agents involved in creating resource
    "role" : { Coding }, // R!  What the agents involvement was
    "actor" : { Reference(Practitioner|RelatedPerson|Patient|Device|
    Organization) }, // Individual, device or organization playing role
    "userId" : { Identifier }, // Authorization-system identifier for the agent
    "relatedAgent" : [{ // Track delegation between agents
      "type" : { CodeableConcept }, // R!  Type of relationship between agents
      "target" : "<uri>" // R!  Reference to other agent in this resource by id
    }]
  }],
  "entity" : [{ // An entity used in this activity
    "role" : "<code>", // R!  derivation | revision | quotation | source
    "type" : { Coding }, // R!  The type of resource in this entity
    "reference" : "<uri>", // R!  Identity of entity
    "display" : "<string>", // Human description of entity
    "agent" : { Content as for Provenance.agent } // Entity is attributed to this agent
  }],
  "signature" : [{ Signature }] // Signature on target
}

Structure

Name	Flags	Card.	Type	Description & Constraints
Provenance	Σ		DomainResource	Who, What, When for a set of resources
target	Σ	1..*	Reference(Any)	Target Reference(s) (usually version specific)
period	Σ	0..1	Period	When the activity occurred
recorded	Σ	1..1	instant	When the activity was recorded / updated
reason	Σ	0..*	CodeableConcept	Reason the activity is occurring PurposeOfUse (Extensible)
activity	Σ	0..1	CodeableConcept	Activity that occurred ProvenanceEventCurrentState (Extensible)
location	Σ	0..1	Reference(Location)	Where the activity occurred, if relevant
policy	Σ	0..*	uri	Policy or plan the activity was defined by
agent	Σ	0..*	BackboneElement	Agents involved in creating resource
role	Σ	1..1	Coding	What the agents involvement was ProvenanceParticipantRole (Extensible)
actor	Σ	0..1	Reference(Practitioner \| RelatedPerson \| Patient \| Device \| Organization)	Individual, device or organization playing role
userId	Σ	0..1	Identifier	Authorization-system identifier for the agent
relatedAgent	Σ	0..*	BackboneElement	Track delegation between agents
type	Σ	1..1	CodeableConcept	Type of relationship between agents v3 Code System RoleLinkType (Example)
target	Σ	1..1	uri	Reference to other agent in this resource by id
entity	Σ	0..*	BackboneElement	An entity used in this activity
role	Σ	1..1	code	derivation \| revision \| quotation \| source ProvenanceEntityRole (Required)
type	Σ	1..1	Coding	The type of resource in this entity ResourceType (Extensible)
reference	Σ	1..1	uri	Identity of entity
display	Σ	0..1	string	Human description of entity
agent	Σ	0..1	see agent	Entity is attributed to this agent
signature	Σ	0..*	Signature	Signature on target
Documentation for this format

UML Diagram

XML Template

<Provenance xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <target><!-- 1..* Reference(Any) Target Reference(s) (usually version specific) --></target>
 <period><!-- 0..1 Period When the activity occurred --></period>
 <recorded value="[instant]"/><!-- 1..1 When the activity was recorded / updated -->
 <reason><!-- 0..* CodeableConcept Reason the activity is occurring --></reason>
 <activity><!-- 0..1 CodeableConcept Activity that occurred --></activity>
 <location><!-- 0..1 Reference(Location) Where the activity occurred, if relevant --></location>
 <policy value="[uri]"/><!-- 0..* Policy or plan the activity was defined by -->
 <agent>  <!-- 0..* Agents involved in creating resource -->
  <role><!-- 1..1 Coding What the agents involvement was --></role>
  <actor><!-- 0..1 Reference(Practitioner|RelatedPerson|Patient|Device|
    Organization) Individual, device or organization playing role --></actor>
  <userId><!-- 0..1 Identifier Authorization-system identifier for the agent --></userId>
  <relatedAgent>  <!-- 0..* Track delegation between agents -->
   <type><!-- 1..1 CodeableConcept Type of relationship between agents --></type>
   <target value="[uri]"/><!-- 1..1 Reference to other agent in this resource by id -->
  </relatedAgent>
 </agent>
 <entity>  <!-- 0..* An entity used in this activity -->
  <role value="[code]"/><!-- 1..1 derivation | revision | quotation | source -->
  <type><!-- 1..1 Coding The type of resource in this entity --></type>
  <reference value="[uri]"/><!-- 1..1 Identity of entity -->
  <display value="[string]"/><!-- 0..1 Human description of entity -->
  <agent><!-- 0..1 Content as for Provenance.agent Entity is attributed to this agent --></agent>
 </entity>
 <signature><!-- 0..* Signature Signature on target --></signature>
</Provenance>

JSON Template

{
  "resourceType" : "Provenance",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "target" : [{ Reference(Any) }], // R!  Target Reference(s) (usually version specific)
  "period" : { Period }, // When the activity occurred
  "recorded" : "<instant>", // R!  When the activity was recorded / updated
  "reason" : [{ CodeableConcept }], // Reason the activity is occurring
  "activity" : { CodeableConcept }, // Activity that occurred
  "location" : { Reference(Location) }, // Where the activity occurred, if relevant
  "policy" : ["<uri>"], // Policy or plan the activity was defined by
  "agent" : [{ // Agents involved in creating resource
    "role" : { Coding }, // R!  What the agents involvement was
    "actor" : { Reference(Practitioner|RelatedPerson|Patient|Device|
    Organization) }, // Individual, device or organization playing role
    "userId" : { Identifier }, // Authorization-system identifier for the agent
    "relatedAgent" : [{ // Track delegation between agents
      "type" : { CodeableConcept }, // R!  Type of relationship between agents
      "target" : "<uri>" // R!  Reference to other agent in this resource by id
    }]
  }],
  "entity" : [{ // An entity used in this activity
    "role" : "<code>", // R!  derivation | revision | quotation | source
    "type" : { Coding }, // R!  The type of resource in this entity
    "reference" : "<uri>", // R!  Identity of entity
    "display" : "<string>", // Human description of entity
    "agent" : { Content as for Provenance.agent } // Entity is attributed to this agent
  }],
  "signature" : [{ Signature }] // Signature on target
}

Alternate definitions: Schema/Schematron, Resource Profile (XML, JSON), Questionnaire

6.4.4.1 Terminology Bindings

Path	Definition	Type	Reference
Provenance.reason	The reason the activity took place.	Extensible	PurposeOfUse
Provenance.activity	The activity took place.	Extensible	ProvenanceEventCurrentState
Provenance.agent.role	The role that a provenance agent played with respect to the activity	Extensible	ProvenanceParticipantRole
Provenance.agent.relatedAgent.type	Type of relationship between two provenance agents	Example	v3 Code System RoleLinkType
Provenance.entity.role	How an entity was used in an activity	Required	ProvenanceEntityRole
Provenance.entity.type	The type of an entity used in an activity	Extensible	ResourceType

Path

Definition

Type

Reference

Provenance.reason

The reason the activity took place.

Extensible

PurposeOfUse

Provenance.activity

The activity took place.

Extensible

ProvenanceEventCurrentState

Provenance.agent.role

The role that a provenance agent played with respect to the activity

Extensible

ProvenanceParticipantRole

Provenance.agent.relatedAgent.type

Type of relationship between two provenance agents

Example

v3 Code System RoleLinkType

Provenance.entity.role

How an entity was used in an activity

Required

ProvenanceEntityRole

Provenance.entity.type

The type of an entity used in an activity

Extensible

ResourceType

6.4.4.2 Using the Provenance Resource

The provenance resource identifies information about another resource (the reference element). The provenance resource may be used in several different ways:

As part of a document bundle where it identifies the provenance of part or all of the document
On a RESTful system where it keeps track of provenance information relating to resources

When used in a document bundle, the references are often not explicitly versioned, but they always implicitly pertain to the version of the resource found in the document. 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.

6.4.4.3 Digital Signatures

The provenance resource includes a Digital Signature element 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 purposeOfSignature 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.

6.4.4.4 Party References

Because the Provenance resource often refers to parties that are not represented as FHIR resources, Agent and Entity references are allowed to be either references to other resources, or they can refer to other entities that are not FHIR resources.

The code in the .type element is used to differentiate between the two: if the code is in the system "http://hl7.org/fhir/resource-types", then the reference is to a resource, and the element reference functions exactly the same as in a Resource Reference.

A version specific reference to a FHIR resource on the same server:

  <agent>
    <type>
      <system value="http://hl7.org/fhir/resource-types"/>
      <code value="Patient"/>
    </type>
    <reference value="Patient/34/_history/3"/>
  </agent>

In effect, this is the same pattern as a standard resource reference, but the type becomes extensible to allow referencing other kinds of resources.

A reference to a user (a person) not represented by a FHIR resource:

  <agent>
    <type>
      <system value="http://hl7.org/fhir/provenance-participant-type"/>  
      <code value="person"/>
    </type>  
    <reference value="http://acme.com/users/34"/>
  </agent>

One subtle issue with the use of the Provenance resource is to differentiate between whether the reference is to the Resource itself, or whether the the reference is to the real world thing that the resource represents, e.g. was it the person involved in the activity, or the record of the person. For Agents, it should be understood that the reference is to the real world thing that the resource represents.

6.4.5 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Paths
agent	reference	Individual, device or organization playing role	Provenance.agent.actor (Device, Organization, Patient, Practitioner, RelatedPerson)
end	date	End time with inclusive boundary, if not ongoing	Provenance.period.end
entity	uri	Identity of entity	Provenance.entity.reference
entitytype	token	The type of resource in this entity	Provenance.entity.type
location	reference	Where the activity occurred, if relevant	Provenance.location (Location)
patient	reference	Target Reference(s) (usually version specific)	Provenance.target (Patient)
sigtype	token	Indication of the reason the entity signed the object(s)	Provenance.signature.type
start	date	Starting time with inclusive boundary	Provenance.period.start
target	reference	Target Reference(s) (usually version specific)	Provenance.target (Any)
userid	token	Authorization-system identifier for the agent	Provenance.agent.userId