2nd DSTU Draft For Comment

This page is part of the FHIR Specification (v0.4.0: DSTU 2 Draft). 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 information that describes the activity that led to the creation of a set of resources. This information can be used to help determine their reliability or trace where the information in them came from. The focus of the provenance resource is record keeping, audit and traceability, and not explicit statements of clinical significance.

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 Security Event resource contains overlapping information, but is created as events occur, to track and audit the events. Security 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 thay 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. 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..*ElementPerson, organization, records, etc. involved in creating resource
.... role 1..1Codinge.g. author | overseer | enterer | attester | source | cc: +
ProvenanceAgentRole (Incomplete)
.... type 1..1Codinge.g. Resource | Person | Application | Record | Document +
ProvenanceAgentType (Incomplete)
.... reference 1..1uriIdentity of agent (urn or url)
.... display 0..1stringHuman description of participant
... entity 0..*ElementAn entity used in this activity
.... role 1..1codederivation | revision | quotation | source
ProvenanceEntityRole (Required)
.... type 1..1CodingResource Type, or something else
ProvenanceEntityType (Incomplete)
.... reference 1..1uriIdentity of participant (urn or url)
.... display 0..1stringHuman description of participant
.... agent 0..1see agentEntity is attributed to this agent
... integritySignature 0..1stringBase64 signature (DigSig) - integrity check

UML Diagram

Provenance (DomainResource)The Reference(s) that were generated 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 signature should match a Provenance.agent.reference in the provenance resource. The signature is only added to support checking cryptographic integrity of the resource, and not to represent workflow and clinical aspects of the signing process, or to support non-repudiationintegritySignature : string 0..1AgentThe role that the participant playedrole : Coding 1..1 « The role that a provenance agent playedProvenanceAgentRole+ »The type of the participanttype : Coding 1..1 « The type of a provenance agentProvenanceAgentType+ »Identity of participant. May be a logical or physical uri and maybe absolute or relativereference : uri 1..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 participant. 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, a piece of software, an inanimate object, an organization, 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..* Person, organization, records, etc. involved in creating resource -->
  <role><!-- 1..1 Coding e.g. author | overseer | enterer | attester | source | cc: + --></role>
  <type><!-- 1..1 Coding e.g. Resource | Person | Application | Record | Document + --></type>
  <reference value="[uri]"/><!-- 1..1 Identity of agent (urn or url) -->
  <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 Resource Type, or something else --></type>
  <reference value="[uri]"/><!-- 1..1 Identity of participant (urn or url) -->
  <display value="[string]"/><!-- 0..1 Human description of participant -->
  <agent><!-- 0..1 Content as for Provenance.agent Entity is attributed to this agent --></agent>
 </entity>
 <integritySignature value="[string]"/><!-- 0..1 Base64 signature (DigSig) - integrity check -->
</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" : [{ // Person, organization, records, etc. involved in creating resource
    "role" : { Coding }, // R! e.g. author | overseer | enterer | attester | source | cc: +
    "type" : { Coding }, // R! e.g. Resource | Person | Application | Record | Document +
    "reference" : "<uri>", // R! Identity of agent (urn or url)
    "display" : "<string>" // Human description of participant
  }],
  "entity" : [{ // An entity used in this activity
    "role" : "<code>", // R! derivation | revision | quotation | source
    "type" : { Coding }, // R! Resource Type, or something else
    "reference" : "<uri>", // R! Identity of participant (urn or url)
    "display" : "<string>", // Human description of participant
    "agent" : { Content as for Provenance.agent } // Entity is attributed to this agent
  }],
  "integritySignature" : "<string>" // Base64 signature (DigSig) - integrity check
}

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..*ElementPerson, organization, records, etc. involved in creating resource
.... role 1..1Codinge.g. author | overseer | enterer | attester | source | cc: +
ProvenanceAgentRole (Incomplete)
.... type 1..1Codinge.g. Resource | Person | Application | Record | Document +
ProvenanceAgentType (Incomplete)
.... reference 1..1uriIdentity of agent (urn or url)
.... display 0..1stringHuman description of participant
... entity 0..*ElementAn entity used in this activity
.... role 1..1codederivation | revision | quotation | source
ProvenanceEntityRole (Required)
.... type 1..1CodingResource Type, or something else
ProvenanceEntityType (Incomplete)
.... reference 1..1uriIdentity of participant (urn or url)
.... display 0..1stringHuman description of participant
.... agent 0..1see agentEntity is attributed to this agent
... integritySignature 0..1stringBase64 signature (DigSig) - integrity check

UML Diagram

Provenance (DomainResource)The Reference(s) that were generated 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 signature should match a Provenance.agent.reference in the provenance resource. The signature is only added to support checking cryptographic integrity of the resource, and not to represent workflow and clinical aspects of the signing process, or to support non-repudiationintegritySignature : string 0..1AgentThe role that the participant playedrole : Coding 1..1 « The role that a provenance agent playedProvenanceAgentRole+ »The type of the participanttype : Coding 1..1 « The type of a provenance agentProvenanceAgentType+ »Identity of participant. May be a logical or physical uri and maybe absolute or relativereference : uri 1..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 participant. 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, a piece of software, an inanimate object, an organization, 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..* Person, organization, records, etc. involved in creating resource -->
  <role><!-- 1..1 Coding e.g. author | overseer | enterer | attester | source | cc: + --></role>
  <type><!-- 1..1 Coding e.g. Resource | Person | Application | Record | Document + --></type>
  <reference value="[uri]"/><!-- 1..1 Identity of agent (urn or url) -->
  <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 Resource Type, or something else --></type>
  <reference value="[uri]"/><!-- 1..1 Identity of participant (urn or url) -->
  <display value="[string]"/><!-- 0..1 Human description of participant -->
  <agent><!-- 0..1 Content as for Provenance.agent Entity is attributed to this agent --></agent>
 </entity>
 <integritySignature value="[string]"/><!-- 0..1 Base64 signature (DigSig) - integrity check -->
</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" : [{ // Person, organization, records, etc. involved in creating resource
    "role" : { Coding }, // R! e.g. author | overseer | enterer | attester | source | cc: +
    "type" : { Coding }, // R! e.g. Resource | Person | Application | Record | Document +
    "reference" : "<uri>", // R! Identity of agent (urn or url)
    "display" : "<string>" // Human description of participant
  }],
  "entity" : [{ // An entity used in this activity
    "role" : "<code>", // R! derivation | revision | quotation | source
    "type" : { Coding }, // R! Resource Type, or something else
    "reference" : "<uri>", // R! Identity of participant (urn or url)
    "display" : "<string>", // Human description of participant
    "agent" : { Content as for Provenance.agent } // Entity is attributed to this agent
  }],
  "integritySignature" : "<string>" // Base64 signature (DigSig) - integrity check
}

 

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

6.5.4.1 Terminology Bindings

PathDefinitionTypeReference
Provenance.agent.role The role that a provenance agent playedIncompletehttp://hl7.org/fhir/vs/provenance-agent-role
Provenance.agent.type The type of a provenance agentIncompletehttp://hl7.org/fhir/vs/provenance-agent-type
Provenance.entity.role How an entity was used in an activityFixedhttp://hl7.org/fhir/provenance-entity-role
Provenance.entity.type The type of an entity used in an activityIncompletehttp://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 an integritySignature element which contains an XML digital signature.

The purpose of the signature is limited to checking cryptographic integrity of the target Reference(s); e.g. detecting whether changes have occurred between the original construction of the resource and the application processing it. In order to make proper use of the signature element, implementation profiles are required to further clarify the obligations around creating and checking the signature.

The following rules apply to digital signature:

  • The Certificate identifier SHOULD match the identity of an agent (Provenance.agent.reference)
  • If the signature has an IHE purposeOfSignature property, the value SHALL be "source", OID "1.2.840.10065.1.12", which means "the signature of an automated data source". If the signature does not have a purposeOfSignature property, the signature is still to used for this use
  • Whether the representation of the Provenance resource is xml or json, the signature is a base64 of the XML signature
  • The signature is always a signature of the target resource XML representation using a stated canonicalization
The signature is only added to support , and not to represent workflow and clinical aspects of the signing process, or to support non-repudiation.

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)
partytokenIdentity of agent (urn or url)Provenance.agent.reference
partytypetokene.g. Resource | Person | Application | Record | Document +Provenance.agent.type
patientreferenceA patient that the target resource(s) refer to
(Patient)
startdateStarting time with inclusive boundaryProvenance.period.start
targetreferenceTarget Reference(s) (usually version specific)Provenance.target
(Any)