STU 3 Ballot

This page is part of the FHIR Specification (v1.6.0: STU 3 Ballot 4). 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.2 Resource Provenance - Content

Security Work GroupMaturity Level: 1Compartments: 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.2.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.2.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.

The relationship between a resource and it's provenance is established by a reference from the provenance resource to it's 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.

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

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. 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 of the resources, entities, and agents involved in the activity. These References need not be resolvable. The references must provide a unique and ambiguous 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

This resource is referenced by DeviceUseRequest and DiagnosticRequest

6.2.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Provenance ΣDomainResourceWho, What, When for a set of resources
... target Σ1..*Reference(Any)Target Reference(s) (usually version specific)
... period Σ0..1PeriodWhen the activity occurred
... recorded Σ1..1instantWhen the activity was recorded / updated
... reason Σ0..*CodingReason the activity is occurring
PurposeOfUse (Extensible)
... activity Σ0..1CodingActivity that occurred
ProvenanceEventCurrentState (Extensible)
... location Σ0..1Reference(Location)Where the activity occurred, if relevant
... policy Σ0..*uriPolicy or plan the activity was defined by
... agent Σ1..*BackboneElementActor involved
.... role Σ1..1CodingWhat the agents involvement was
ProvenanceParticipantRole (Extensible)
.... actor Σ0..1Reference(Practitioner | RelatedPerson | Patient | Device | Organization)Individual, device or organization playing role
.... userId Σ0..1IdentifierAuthorization-system identifier for the agent
.... relatedAgent Σ0..*BackboneElementTrack delegation between agents
..... type Σ1..1CodeableConceptType of relationship between agents
v3 Code System RoleLinkType (Example)
..... target Σ1..1uriReference to other agent in this resource by identifier
... entity Σ0..*BackboneElementAn entity used in this activity
.... role Σ1..1codederivation | revision | quotation | source | removal
ProvenanceEntityRole (Required)
.... type Σ1..1CodingThe type of resource in this entity
ResourceType (Extensible)
.... reference Σ1..1uriIdentity of entity
.... display Σ0..1stringHuman description of entity
.... agent Σ0..*see agentEntity is attributed to this agent
... signature Σ0..*SignatureSignature on target

doco Documentation for this format

UML Diagram (Legend)

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 [1..*] « Any »The period during which the activity occurredperiod : Period [0..1]The instant of time at which the activity was recordedrecorded : instant [1..1]The reason that the activity was taking placereason : Coding [0..*] « The reason the activity took place. (Strength=Extensible)PurposeOfUse+ »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 entitiesactivity : Coding [0..1] « The activity that took place. (Strength=Extensible)ProvenanceEventCurrentState+ »Where the activity occurred, if relevantlocation : Reference [0..1] « Location »Policy 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 activity. (Strength=Extensible)ProvenanceParticipantRole+ »The individual, device or organization that participated in the eventactor : Reference [0..1] « Practitioner|RelatedPerson|Patient|Device| Organization »The identity of the agent as known by the authorization systemuserId : Identifier [0..1]RelatedAgentThe type of relationship between agentstype : CodeableConcept [1..1] « Type of relationship between two provenance agents. (Strength=Example)v3 Code System RoleLinkType?? »An internal reference to another agent listed in this provenance by its identifiertarget : uri [1..1]EntityHow the entity was used during the activityrole : code [1..1] « How an entity was used in an activity. (Strength=Required)ProvenanceEntityRole! »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 activity. (Strength=Extensible)ResourceType+ »Identity of the Entity used. May be a logical or physical uri and maybe absolute or relativereference : uri [1..1]Human-readable description of the entitydisplay : string [0..1]A relationship between two the agents referenced in this resource. This is defined to allow for explicit description of the delegation between agents. For example, this human author used this device, or one person acted on another's behestrelatedAgent[0..*]An actor taking a role in an activity for which it can be assigned some degree of responsibility for the activity taking placeagent[1..*]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 entityagent[0..*]An entity used in this activityentity[0..*]

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..* Coding Reason the activity is occurring --></reason>
 <activity><!-- 0..1 Coding 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>  <!-- 1..* Actor involved -->
  <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 | removal -->
  <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..* 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" : [{ Coding }], // Reason the activity is occurring
  "activity" : { Coding }, // Activity that occurred
  "location" : { Reference(Location) }, // Where the activity occurred, if relevant
  "policy" : ["<uri>"], // Policy or plan the activity was defined by
  "agent" : [{ // R!  Actor involved
    "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 | removal
    "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
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:Provenance;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

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

Changes since DSTU2

Provenance
Provenance.reason Type changed from CodeableConcept to Coding
Provenance.activity Type changed from CodeableConcept to Coding
Provenance.agent Min Cardinality changed from 0 to 1
Provenance.entity.agent Max Cardinality changed from 1 to *

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Provenance ΣDomainResourceWho, What, When for a set of resources
... target Σ1..*Reference(Any)Target Reference(s) (usually version specific)
... period Σ0..1PeriodWhen the activity occurred
... recorded Σ1..1instantWhen the activity was recorded / updated
... reason Σ0..*CodingReason the activity is occurring
PurposeOfUse (Extensible)
... activity Σ0..1CodingActivity that occurred
ProvenanceEventCurrentState (Extensible)
... location Σ0..1Reference(Location)Where the activity occurred, if relevant
... policy Σ0..*uriPolicy or plan the activity was defined by
... agent Σ1..*BackboneElementActor involved
.... role Σ1..1CodingWhat the agents involvement was
ProvenanceParticipantRole (Extensible)
.... actor Σ0..1Reference(Practitioner | RelatedPerson | Patient | Device | Organization)Individual, device or organization playing role
.... userId Σ0..1IdentifierAuthorization-system identifier for the agent
.... relatedAgent Σ0..*BackboneElementTrack delegation between agents
..... type Σ1..1CodeableConceptType of relationship between agents
v3 Code System RoleLinkType (Example)
..... target Σ1..1uriReference to other agent in this resource by identifier
... entity Σ0..*BackboneElementAn entity used in this activity
.... role Σ1..1codederivation | revision | quotation | source | removal
ProvenanceEntityRole (Required)
.... type Σ1..1CodingThe type of resource in this entity
ResourceType (Extensible)
.... reference Σ1..1uriIdentity of entity
.... display Σ0..1stringHuman description of entity
.... agent Σ0..*see agentEntity is attributed to this agent
... signature Σ0..*SignatureSignature on target

doco Documentation for this format

UML Diagram (Legend)

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 [1..*] « Any »The period during which the activity occurredperiod : Period [0..1]The instant of time at which the activity was recordedrecorded : instant [1..1]The reason that the activity was taking placereason : Coding [0..*] « The reason the activity took place. (Strength=Extensible)PurposeOfUse+ »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 entitiesactivity : Coding [0..1] « The activity that took place. (Strength=Extensible)ProvenanceEventCurrentState+ »Where the activity occurred, if relevantlocation : Reference [0..1] « Location »Policy 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 activity. (Strength=Extensible)ProvenanceParticipantRole+ »The individual, device or organization that participated in the eventactor : Reference [0..1] « Practitioner|RelatedPerson|Patient|Device| Organization »The identity of the agent as known by the authorization systemuserId : Identifier [0..1]RelatedAgentThe type of relationship between agentstype : CodeableConcept [1..1] « Type of relationship between two provenance agents. (Strength=Example)v3 Code System RoleLinkType?? »An internal reference to another agent listed in this provenance by its identifiertarget : uri [1..1]EntityHow the entity was used during the activityrole : code [1..1] « How an entity was used in an activity. (Strength=Required)ProvenanceEntityRole! »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 activity. (Strength=Extensible)ResourceType+ »Identity of the Entity used. May be a logical or physical uri and maybe absolute or relativereference : uri [1..1]Human-readable description of the entitydisplay : string [0..1]A relationship between two the agents referenced in this resource. This is defined to allow for explicit description of the delegation between agents. For example, this human author used this device, or one person acted on another's behestrelatedAgent[0..*]An actor taking a role in an activity for which it can be assigned some degree of responsibility for the activity taking placeagent[1..*]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 entityagent[0..*]An entity used in this activityentity[0..*]

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..* Coding Reason the activity is occurring --></reason>
 <activity><!-- 0..1 Coding 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>  <!-- 1..* Actor involved -->
  <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 | removal -->
  <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..* 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" : [{ Coding }], // Reason the activity is occurring
  "activity" : { Coding }, // Activity that occurred
  "location" : { Reference(Location) }, // Where the activity occurred, if relevant
  "policy" : ["<uri>"], // Policy or plan the activity was defined by
  "agent" : [{ // R!  Actor involved
    "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 | removal
    "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
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .doco


[ a fhir:Provenance;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

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

Changes since DSTU2

Provenance
Provenance.reason Type changed from CodeableConcept to Coding
Provenance.activity Type changed from CodeableConcept to Coding
Provenance.agent Min Cardinality changed from 0 to 1
Provenance.entity.agent Max Cardinality changed from 1 to *

See the Full Difference for further information

 

Alternate definitions: Master Definition (XML, JSON), XML Schema/Schematron (for ) + JSON Schema, ShEx (for Turtle)

6.2.4.1 Terminology Bindings

PathDefinitionTypeReference
Provenance.reason The reason the activity took place.ExtensiblePurposeOfUse
Provenance.activity The activity that took place.ExtensibleProvenanceEventCurrentState
Provenance.agent.role The role that a provenance agent played with respect to the activity.ExtensibleProvenanceParticipantRole
Provenance.agent.relatedAgent.type Type of relationship between two provenance agents.Examplev3 Code System RoleLinkType
Provenance.entity.role How an entity was used in an activity.RequiredProvenanceEntityRole
Provenance.entity.type The type of an entity used in an activity.ExtensibleResourceType

6.2.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.2.4.3 Digital 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.

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

For Provenance.agent, the actor element is used to reference an existing resource. To reference an entity that is not a FHIR resource, the userId element is used.

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

  <agent>
    <actor>
      <reference value="Patient/34/_history/3"/>
    </actor>
  </agent>

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

  <agent>
    <userId>
      <value value="http://acme.com/users/34"/>
    </userId>  
  </agent>

For Provenance.entity, the code in the .type element is used to differentiate between the two cases: 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:

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

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 entity (a person) not represented by a FHIR resource:

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

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

6.2.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
agentreferenceIndividual, device or organization playing roleProvenance.agent.actor
(Practitioner, Organization, Device, Patient, RelatedPerson)
enddateEnd time with inclusive boundary, if not ongoingProvenance.period.end
entityuriIdentity of entityProvenance.entity.reference
entity-typetokenThe type of resource in this entityProvenance.entity.type
locationreferenceWhere the activity occurred, if relevantProvenance.location
(Location)
patientreferenceTarget Reference(s) (usually version specific)Provenance.target
(Patient)
sigtokenIndication 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)
useridtokenAuthorization-system identifier for the agentProvenance.agent.userId