6.4 Resource Provenance - Content

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

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; whereas AuditEvent covers "Usage" of "Entity" and all other "Activity" as defined in W3C Provenance.

The W3C Provenance Specification has the following fundamental model:

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.

6.4.3.1 Open Issues and Request for Comments

At this juncture, Provenance has several areas of concern for the Security WG. The first concern is whether the current HL7 ProvenanceEvent value set is sufficient for conveying the states to which a trigger event can cause an activity to transition the FHIR Resource target of the Provenance Resource from a previous state. The current value set was will be updated post DSTU2.

While the intended FHIR ProvenanceEvent value set has sub-value sets from multiple sources such as W3C and HL7, there are some duplicate and colliding definitions, the upside is that there are more provenance event related actions than in the HL7 ProvenanceEvent value set. The Security, Community Based Collaborative Care, and the EHR Work Groups are in the process of refining and de-duplicating this value set in hopes of replacing the current one in DSTU 2.1 if the Provenance Resource is permitted to be re-published. In any case, feedback from business and implementer communities would be very much appreciated.

Another area of concern is whether the Provenance.entity.role element is necessary at all if there is a sufficient activity value set, and if it is useful, whether W3C codes indicating that the entity is the target of provenance, e.g., derivation or revision, make sense where the entity is an input into a target resource which may be a revision or derivation of that entity.

Note that the binding of the ProvenanceEvent and Purpose of Use value sets are currently set to extensible rather than example. Concerns have been raised about constraining vocabulary choices during DSTU especially for other jurisdictions. For example, outside of the US, ISO 13606 Purpose of Use codes are more likely used. Security WG would also appreciate feedback on whether these bindings should be example or extensible.

• Structure
• UML
• XML
• JSON
• All

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 identifier
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

<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 identifier -->
  </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>

{
  "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 identifier
    }]
  }],
  "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 identifier
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 identifier -->
  </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 identifier
    }]
  }],
  "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
}