DSTU2 Ballot Source

This page is part of the FHIR Specification (v0.5.0: DSTU 2 Ballot 2). 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.5 Resource Provenance - Content

This resource maintained by the FHIR Management Group Work Group

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.5.1 Scope and Usage

The provenance resource tracks information about 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.5.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.5.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

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.

6.5.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Provenance DomainResourceWho, What, When for a set of resources
... target 1..*AnyTarget Reference(s) (usually version specific)
... period 0..1PeriodWhen the activity occurred
... recorded 1..1instantWhen the activity was recorded / updated
... reason 0..1CodeableConceptReason the activity is occurring
... location 0..1LocationWhere the activity occurred, if relevant
... policy 0..*uriPolicy or plan the activity was defined by
... agent 0..*ElementAgents involved in creating resource
.... role 1..1CodingAgents Role
ProvenanceAgentRole (Extensible)
.... type 1..1CodingAgent Type
ProvenanceAgentType (Required)
.... reference[x] Identity of agent
..... referenceUri0..1uri
..... referenceReference0..1Practitioner | RelatedPerson | Patient | Device
.... display 0..1stringHuman description of participant
... entity 0..*ElementAn entity used in this activity
.... role 1..1codederivation | revision | quotation | source
ProvenanceEntityRole (Required)
.... type 1..1CodingEntity Type
ProvenanceEntityType (Required)
.... reference 1..1uriIdentity of entity
.... display 0..1stringHuman description of entity
.... agent 0..1see agentEntity is attributed to this agent
... signature 0..*SignatureSignature on target

UML Diagram

Provenance (DomainResource)The Reference(s) that were generated or updated by the activity described in this resource. A provenance can point to more than one target if multiple resources were created/updated by the same activitytarget : Reference(Any) 1..*The period during which the activity occurredperiod : Period 0..1The instant of time at which the activity was recordedrecorded : instant 1..1The reason that the activity was taking placereason : CodeableConcept 0..1Where the activity occurred, if relevantlocation : Reference(Location) 0..1Policy or plan the activity was defined by. Typically, a single activity may have multiple applicable policy documents, such as patient consent, guarantor funding, etcpolicy : uri 0..*A digital signature on the target Reference(s). The signer should match a Provenance.agent. The purpose of the signature is indicatedsignature : Signature 0..*AgentThe function of the agent with respect to the activityrole : Coding 1..1 « The role that a provenance agent played with respect to the activityProvenanceAgentRole+ »The type of participation of the agenttype : Coding 1..1 « The type of a provenance agentProvenanceAgentType »Identity of participant as a Resource or urireference[x] : uri|Reference(Practitioner|RelatedPerson| Patient|Device) 0..1Human-readable description of the participantdisplay : string 0..1EntityHow the entity was used during the activityrole : code 1..1 « How an entity was used in an activityProvenanceEntityRole »The type of the entity. If the entity is a resource, then this is a resource typetype : Coding 1..1 « The type of an entity used in an activityProvenanceEntityType »Identity of the Entity used. May be a logical or physical uri and maybe absolute or relativereference : uri 1..1Human-readable description of the entitydisplay : string 0..1An agent takes a role in an activity such that the agent can be assigned some degree of responsibility for the activity taking place. An agent can be a person, an organization, software, or other entities that may be ascribed responsibilityagent0..*The entity is attributed to an agent to express the agent's responsibility for that entity, possibly along with other agents. This description can be understood as shorthand for saying that the agent was responsible for the activity which generated the entityagent0..1An entity used in this activityentity0..*

XML Template

<Provenance xmlns="http://hl7.org/fhir"> doco
 <!-- 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..1 CodeableConcept Reason the activity is occurring --></reason>
 <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 Agents Role --></role>
  <type><!-- 1..1 Coding Agent Type --></type>
  <reference[x]><!-- 0..1 uri|Reference(Practitioner|RelatedPerson|Patient|Device) 
      Identity of agent --></reference[x]>
  <display value="[string]"/><!-- 0..1 Human description of participant -->
 </agent>
 <entity>  <!-- 0..* An entity used in this activity -->
  <role value="[code]"/><!-- 1..1 derivation | revision | quotation | source -->
  <type><!-- 1..1 Coding Entity Type --></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

{doco
  "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
  "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!  Agents Role
    "type" : { Coding }, // R!  Agent Type
    // reference[x]: Identity of agent. One of these 2:
    "referenceUri" : "<uri>",
    "referenceReference" : { Reference(Practitioner|RelatedPerson|Patient|Device) },
    "display" : "<string>" // Human description of participant
  }],
  "entity" : [{ // An entity used in this activity
    "role" : "<code>", // R!  derivation | revision | quotation | source
    "type" : { Coding }, // R!  Entity Type
    "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

NameFlagsCard.TypeDescription & Constraintsdoco
.. Provenance DomainResourceWho, What, When for a set of resources
... target 1..*AnyTarget Reference(s) (usually version specific)
... period 0..1PeriodWhen the activity occurred
... recorded 1..1instantWhen the activity was recorded / updated
... reason 0..1CodeableConceptReason the activity is occurring
... location 0..1LocationWhere the activity occurred, if relevant
... policy 0..*uriPolicy or plan the activity was defined by
... agent 0..*ElementAgents involved in creating resource
.... role 1..1CodingAgents Role
ProvenanceAgentRole (Extensible)
.... type 1..1CodingAgent Type
ProvenanceAgentType (Required)
.... reference[x] Identity of agent
..... referenceUri0..1uri
..... referenceReference0..1Practitioner | RelatedPerson | Patient | Device
.... display 0..1stringHuman description of participant
... entity 0..*ElementAn entity used in this activity
.... role 1..1codederivation | revision | quotation | source
ProvenanceEntityRole (Required)
.... type 1..1CodingEntity Type
ProvenanceEntityType (Required)
.... reference 1..1uriIdentity of entity
.... display 0..1stringHuman description of entity
.... agent 0..1see agentEntity is attributed to this agent
... signature 0..*SignatureSignature on target

UML Diagram

Provenance (DomainResource)The Reference(s) that were generated or updated by the activity described in this resource. A provenance can point to more than one target if multiple resources were created/updated by the same activitytarget : Reference(Any) 1..*The period during which the activity occurredperiod : Period 0..1The instant of time at which the activity was recordedrecorded : instant 1..1The reason that the activity was taking placereason : CodeableConcept 0..1Where the activity occurred, if relevantlocation : Reference(Location) 0..1Policy or plan the activity was defined by. Typically, a single activity may have multiple applicable policy documents, such as patient consent, guarantor funding, etcpolicy : uri 0..*A digital signature on the target Reference(s). The signer should match a Provenance.agent. The purpose of the signature is indicatedsignature : Signature 0..*AgentThe function of the agent with respect to the activityrole : Coding 1..1 « The role that a provenance agent played with respect to the activityProvenanceAgentRole+ »The type of participation of the agenttype : Coding 1..1 « The type of a provenance agentProvenanceAgentType »Identity of participant as a Resource or urireference[x] : uri|Reference(Practitioner|RelatedPerson| Patient|Device) 0..1Human-readable description of the participantdisplay : string 0..1EntityHow the entity was used during the activityrole : code 1..1 « How an entity was used in an activityProvenanceEntityRole »The type of the entity. If the entity is a resource, then this is a resource typetype : Coding 1..1 « The type of an entity used in an activityProvenanceEntityType »Identity of the Entity used. May be a logical or physical uri and maybe absolute or relativereference : uri 1..1Human-readable description of the entitydisplay : string 0..1An agent takes a role in an activity such that the agent can be assigned some degree of responsibility for the activity taking place. An agent can be a person, an organization, software, or other entities that may be ascribed responsibilityagent0..*The entity is attributed to an agent to express the agent's responsibility for that entity, possibly along with other agents. This description can be understood as shorthand for saying that the agent was responsible for the activity which generated the entityagent0..1An entity used in this activityentity0..*

XML Template

<Provenance xmlns="http://hl7.org/fhir"> doco
 <!-- 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..1 CodeableConcept Reason the activity is occurring --></reason>
 <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 Agents Role --></role>
  <type><!-- 1..1 Coding Agent Type --></type>
  <reference[x]><!-- 0..1 uri|Reference(Practitioner|RelatedPerson|Patient|Device) 
      Identity of agent --></reference[x]>
  <display value="[string]"/><!-- 0..1 Human description of participant -->
 </agent>
 <entity>  <!-- 0..* An entity used in this activity -->
  <role value="[code]"/><!-- 1..1 derivation | revision | quotation | source -->
  <type><!-- 1..1 Coding Entity Type --></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

{doco
  "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
  "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!  Agents Role
    "type" : { Coding }, // R!  Agent Type
    // reference[x]: Identity of agent. One of these 2:
    "referenceUri" : "<uri>",
    "referenceReference" : { Reference(Practitioner|RelatedPerson|Patient|Device) },
    "display" : "<string>" // Human description of participant
  }],
  "entity" : [{ // An entity used in this activity
    "role" : "<code>", // R!  derivation | revision | quotation | source
    "type" : { Coding }, // R!  Entity Type
    "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)

6.5.4.1 Terminology Bindings

PathDefinitionTypeReference
Provenance.agent.role The role that a provenance agent played with respect to the activityExtensiblehttp://hl7.org/fhir/vs/provenance-agent-role
Provenance.agent.type The type of a provenance agentRequiredhttp://hl7.org/fhir/vs/provenance-agent-type
Provenance.entity.role How an entity was used in an activityRequiredhttp://hl7.org/fhir/provenance-entity-role
Provenance.entity.type The type of an entity used in an activityRequiredhttp://hl7.org/fhir/vs/resource-types

6.5.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.5.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.5.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.5.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.

NameTypeDescriptionPaths
enddateEnd time with inclusive boundary, if not ongoingProvenance.period.end
locationreferenceWhere the activity occurred, if relevantProvenance.location
(Location)
partyreferenceIdentity of agentProvenance.agent.reference[x]
(Device, Patient, Practitioner, RelatedPerson)
partytypetokenAgent TypeProvenance.agent.type
patientreferenceA patient that the target resource(s) refer to
(Patient)
sigtypetokenIndication of the reason the entity signed the object(s)Provenance.signature.type
startdateStarting time with inclusive boundaryProvenance.period.start
targetreferenceTarget Reference(s) (usually version specific)Provenance.target
(Any)