FHIR R6 API Incubator
0.1.0 - ci-build International flag

FHIR R6 API Incubator, published by HL7 International / FHIR Infrastructure. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/api-incubator-ig/ and changes regularly. See the Directory of published versions

Resource Profile: Graph Definition

Official URL: http://hl7.org/fhir/StructureDefinition/GraphDefinition Version: 0.1.0
Standards status: Trial-use Maturity Level: 1 Computable Name: GraphDefinition
Other Identifiers: OID:2.16.840.1.113883.4.642.5.1327

A formal computable definition of a graph of resources - that is, a coherent set of resources that form a graph by following references. The Graph Definition resource defines a set and makes rules about the set.

Scope and Usage

The GraphDefinition resource provides a formal computable definition of a graph of resources - that is, a coherent set of resources that form a graph by following references. The Graph Definition resource defines a set and makes rules about the set. The GraphDefinition resource can be used to:

  • Summarize a set of profiles on resources
  • Define a graph of resources to return in a query
  • Define a graph of resources to include in a document
  • Document rules about the relationship between a set of resources e.g. must all resources concern the same patient?

Boundaries and Relationships

There is a close relationship between Profiles and GraphDefinitions:

  • A StructureDefinition defines a profile, and profiles can make rules about the relationships between resources. A carefully defined set of profiles implies part of what is in a GraphDefinition
  • A GraphDefinition defines rules about the relationships between resources, and in so doing, implies some constraints that could or should be represented in their profiles, if they are defined
  • Like CompartmentDefinition, GraphDefinition allows defining a grouping of resources and may be used for security access permissions. However, GraphDefinitions do not define additional query capabilities and are much more limited in how membership in the collection is defined (all resources that are part of a Compartment must expose a search parameter of the same name).

Profiles and Graph Definitions can be used together, or separately. When used together, they should be consistent. Note, though, that a graph definition may contain a subset or a superset of the relationships explicitly described in the profiles it refers to.

It is possible that in some circumstances, a graph definition makes incompatible rules with the Profiles it refers to - in this case, no graph of resources will meet the constraints expressed. Applications should - but are not required to - detect when such incompatibilities arise.

Usages:

You can also check for usages in the FHIR IG Statistics

Formal Views of Profile Content

Description of Profiles, Differentials, Snapshots and how the different presentations work.

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. GraphDefinition C 0..* DomainResource Definition of a graph of resources

Elements defined in Ancestors:id, meta, implicitRules, language, text, contained, extension, modifierExtension
Interfaces Implemented: CanonicalResource
Constraints: cnl-0
... meta Σ 0..1 Meta Metadata about the resource
... implicitRules ?!Σ 0..1 uri A set of rules under which this content was created
... language 0..1 code Language of the resource content
Binding: AllLanguages (required): IETF language tag for a human language
Additional BindingsPurpose
CommonLanguages Starter
... text 0..1 Narrative Text summary of the resource, for human interpretation
This profile does not constrain the narrative in regard to content, language, or traceability to data elements
... contained 0..* Resource Contained, inline Resources
... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored
Slice: Unordered, Open by value:url
... url ΣC 0..1 uri Canonical identifier for this graph definition, represented as a URI (globally unique)
... identifier Σ 0..* Identifier Additional identifier for the GraphDefinition (business identifier)
... version Σ 0..1 string Business version of the graph definition
... versionAlgorithm[x] Σ 0..1 How to compare versions
Binding: VersionAlgorithm (extensible)
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 1..1 string Name for this graph definition (computer friendly)
... title Σ 0..1 string Name for this graph definition (human friendly)
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 0..1 dateTime Date last changed
... publisher Σ 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher
... description 0..1 markdown Natural language description of the graph definition
... useContext Σ 0..* UsageContext The context that the content is intended to support
... jurisdiction Σ 0..* CodeableConcept Jurisdiction of the authority that maintains the graph definition (if applicable)
Binding: Jurisdiction ValueSet (extensible): Countries and regions within which this artifact is targeted for use.
... purpose 0..1 markdown Why this graph definition is defined
... copyright 0..1 markdown Notice about intellectual property ownership, can include restrictions on use
... copyrightLabel 0..1 string Copyright holder and year(s)
... start 0..1 id Starting Node
... node 0..* BackboneElement Potential target for the link
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
.... nodeId 1..1 id Internal ID - target for link references
.... description 0..1 string Why this node is specified
.... type 1..1 code Type of resource this link refers to
Binding: VersionIndependentResourceTypesAll (required): A type of resource, or a Reference (from all versions)
Additional BindingsPurposeDocumentation
AllResourceTypes UI Binding
.... profile 0..1 canonical(StructureDefinition) Profile for the target resource
... link 0..* BackboneElement Links this graph makes rules about
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
.... description 0..1 string Why this link is specified
.... min 0..1 integer Minimum occurrences for this link
.... max 0..1 string Maximum occurrences for this link
.... sourceId 1..1 id Source Node for this link
.... path 0..1 string Path in the resource that contains the link
.... sliceName 0..1 string Which slice (if profiled)
.... targetId 1..1 id Target Node for this link
.... params 0..1 string Criteria for reverse lookup
.... compartment 0..* BackboneElement Compartment Consistency Rules
..... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
..... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
..... use 1..1 code where | requires
Binding: GraphCompartmentUse (required)
..... rule 1..1 code identical | matching | different | custom
Binding: GraphCompartmentRule (required)
..... code 1..1 code Patient | Encounter | RelatedPerson | Practitioner | Device | EpisodeOfCare
Binding: CompartmentType (required)
..... expression 0..1 string Custom rule, as a FHIRPath expression
..... description 0..1 string Documentation for FHIRPath expression

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
GraphDefinition.language Base required All Languages 📍6.0.0-ballot3 FHIR Std.
GraphDefinition.versionAlgorithm[x] Base extensible Version Algorithm 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.status Base required PublicationStatus 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.jurisdiction Base extensible Jurisdiction ValueSet 📦1.0.0 THO v7.2
GraphDefinition.node.​type Base required Version Independent Resource Types (All) 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.use Base required Graph Compartment Use 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.rule Base required Graph Compartment Rule 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.code Base required Compartment Type 📦6.0.0-ballot3 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
cnl-0 warning GraphDefinition Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
cnl-1 warning GraphDefinition.url URL should not contain | or # - these characters make processing canonical references problematic exists() implies matches('^[^|# ]+$')
dom-2 error GraphDefinition If the resource is contained in another resource, it SHALL NOT contain nested Resources contained.contained.empty()
dom-3 error GraphDefinition If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource contained.where((('#'+id.trace('id') in %resource.descendants().select(reference | as(uri))) or descendants().where(reference='#' | as(uri)='#').exists()).not()).trace('unmatched', id).empty()
dom-4 error GraphDefinition If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated contained.meta.versionId.empty() and contained.meta.lastUpdated.empty()
dom-5 error GraphDefinition If a resource is contained in another resource, it SHALL NOT have a security label contained.meta.security.empty()
dom-6 best practice GraphDefinition A resource should have narrative for robust management text.`div`.exists()
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())

This structure is derived from DomainResource

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. GraphDefinition C 0..* DomainResource Definition of a graph of resources

Elements defined in Ancestors:id, meta, implicitRules, language, text, contained, extension, modifierExtension
Interfaces Implemented: CanonicalResource
Constraints: cnl-0
... url ΣC 0..1 uri Canonical identifier for this graph definition, represented as a URI (globally unique)
... identifier Σ 0..* Identifier Additional identifier for the GraphDefinition (business identifier)
... version Σ 0..1 string Business version of the graph definition
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 1..1 string Name for this graph definition (computer friendly)
... title Σ 0..1 string Name for this graph definition (human friendly)
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 0..1 dateTime Date last changed
... publisher Σ 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher
... description 0..1 markdown Natural language description of the graph definition
... useContext Σ 0..* UsageContext The context that the content is intended to support
... jurisdiction Σ 0..* CodeableConcept Jurisdiction of the authority that maintains the graph definition (if applicable)
Binding: Jurisdiction ValueSet (extensible): Countries and regions within which this artifact is targeted for use.
... purpose 0..1 markdown Why this graph definition is defined
... copyright 0..1 markdown Notice about intellectual property ownership, can include restrictions on use
... copyrightLabel 0..1 string Copyright holder and year(s)
... start 0..1 id Starting Node
... node 0..* BackboneElement Potential target for the link
.... nodeId 1..1 id Internal ID - target for link references
.... description 0..1 string Why this node is specified
.... type 1..1 code Type of resource this link refers to
Binding: VersionIndependentResourceTypesAll (required): A type of resource, or a Reference (from all versions)
Additional BindingsPurposeDocumentation
AllResourceTypes UI Binding
.... profile 0..1 canonical(StructureDefinition) Profile for the target resource
... link 0..* BackboneElement Links this graph makes rules about
.... description 0..1 string Why this link is specified
.... min 0..1 integer Minimum occurrences for this link
.... max 0..1 string Maximum occurrences for this link
.... sourceId 1..1 id Source Node for this link
.... path 0..1 string Path in the resource that contains the link
.... sliceName 0..1 string Which slice (if profiled)
.... targetId 1..1 id Target Node for this link
.... params 0..1 string Criteria for reverse lookup
.... compartment 0..* BackboneElement Compartment Consistency Rules
..... use 1..1 code where | requires
Binding: GraphCompartmentUse (required)
..... rule 1..1 code identical | matching | different | custom
Binding: GraphCompartmentRule (required)
..... code 1..1 code Patient | Encounter | RelatedPerson | Practitioner | Device | EpisodeOfCare
Binding: CompartmentType (required)
..... expression 0..1 string Custom rule, as a FHIRPath expression
..... description 0..1 string Documentation for FHIRPath expression

doco Documentation for this format

Terminology Bindings (Differential)

Path Status Usage ValueSet Version Source
GraphDefinition.versionAlgorithm[x] Base extensible Version Algorithm 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.status Base required PublicationStatus 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.jurisdiction Base extensible Jurisdiction ValueSet 📦1.0.0 THO v7.2
GraphDefinition.node.​type Base required Version Independent Resource Types (All) 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.use Base required Graph Compartment Use 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.rule Base required Graph Compartment Rule 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.code Base required Compartment Type 📦6.0.0-ballot3 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
cnl-0 warning GraphDefinition Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. GraphDefinition C 0..* DomainResource Definition of a graph of resources

Elements defined in Ancestors:id, meta, implicitRules, language, text, contained, extension, modifierExtension
Interfaces Implemented: CanonicalResource
Constraints: cnl-0
... meta Σ 0..1 Meta Metadata about the resource
... implicitRules ?!Σ 0..1 uri A set of rules under which this content was created
... language 0..1 code Language of the resource content
Binding: AllLanguages (required): IETF language tag for a human language
Additional BindingsPurpose
CommonLanguages Starter
... text 0..1 Narrative Text summary of the resource, for human interpretation
This profile does not constrain the narrative in regard to content, language, or traceability to data elements
... contained 0..* Resource Contained, inline Resources
... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored
Slice: Unordered, Open by value:url
... url ΣC 0..1 uri Canonical identifier for this graph definition, represented as a URI (globally unique)
... identifier Σ 0..* Identifier Additional identifier for the GraphDefinition (business identifier)
... version Σ 0..1 string Business version of the graph definition
... versionAlgorithm[x] Σ 0..1 How to compare versions
Binding: VersionAlgorithm (extensible)
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 1..1 string Name for this graph definition (computer friendly)
... title Σ 0..1 string Name for this graph definition (human friendly)
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 0..1 dateTime Date last changed
... publisher Σ 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher
... description 0..1 markdown Natural language description of the graph definition
... useContext Σ 0..* UsageContext The context that the content is intended to support
... jurisdiction Σ 0..* CodeableConcept Jurisdiction of the authority that maintains the graph definition (if applicable)
Binding: Jurisdiction ValueSet (extensible): Countries and regions within which this artifact is targeted for use.
... purpose 0..1 markdown Why this graph definition is defined
... copyright 0..1 markdown Notice about intellectual property ownership, can include restrictions on use
... copyrightLabel 0..1 string Copyright holder and year(s)
... start 0..1 id Starting Node
... node 0..* BackboneElement Potential target for the link
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
.... nodeId 1..1 id Internal ID - target for link references
.... description 0..1 string Why this node is specified
.... type 1..1 code Type of resource this link refers to
Binding: VersionIndependentResourceTypesAll (required): A type of resource, or a Reference (from all versions)
Additional BindingsPurposeDocumentation
AllResourceTypes UI Binding
.... profile 0..1 canonical(StructureDefinition) Profile for the target resource
... link 0..* BackboneElement Links this graph makes rules about
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
.... description 0..1 string Why this link is specified
.... min 0..1 integer Minimum occurrences for this link
.... max 0..1 string Maximum occurrences for this link
.... sourceId 1..1 id Source Node for this link
.... path 0..1 string Path in the resource that contains the link
.... sliceName 0..1 string Which slice (if profiled)
.... targetId 1..1 id Target Node for this link
.... params 0..1 string Criteria for reverse lookup
.... compartment 0..* BackboneElement Compartment Consistency Rules
..... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
..... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
..... use 1..1 code where | requires
Binding: GraphCompartmentUse (required)
..... rule 1..1 code identical | matching | different | custom
Binding: GraphCompartmentRule (required)
..... code 1..1 code Patient | Encounter | RelatedPerson | Practitioner | Device | EpisodeOfCare
Binding: CompartmentType (required)
..... expression 0..1 string Custom rule, as a FHIRPath expression
..... description 0..1 string Documentation for FHIRPath expression

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
GraphDefinition.language Base required All Languages 📍6.0.0-ballot3 FHIR Std.
GraphDefinition.versionAlgorithm[x] Base extensible Version Algorithm 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.status Base required PublicationStatus 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.jurisdiction Base extensible Jurisdiction ValueSet 📦1.0.0 THO v7.2
GraphDefinition.node.​type Base required Version Independent Resource Types (All) 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.use Base required Graph Compartment Use 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.rule Base required Graph Compartment Rule 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.code Base required Compartment Type 📦6.0.0-ballot3 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
cnl-0 warning GraphDefinition Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
cnl-1 warning GraphDefinition.url URL should not contain | or # - these characters make processing canonical references problematic exists() implies matches('^[^|# ]+$')
dom-2 error GraphDefinition If the resource is contained in another resource, it SHALL NOT contain nested Resources contained.contained.empty()
dom-3 error GraphDefinition If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource contained.where((('#'+id.trace('id') in %resource.descendants().select(reference | as(uri))) or descendants().where(reference='#' | as(uri)='#').exists()).not()).trace('unmatched', id).empty()
dom-4 error GraphDefinition If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated contained.meta.versionId.empty() and contained.meta.lastUpdated.empty()
dom-5 error GraphDefinition If a resource is contained in another resource, it SHALL NOT have a security label contained.meta.security.empty()
dom-6 best practice GraphDefinition A resource should have narrative for robust management text.`div`.exists()
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())

This structure is derived from DomainResource

Summary

Mandatory: 0 element(9 nested mandatory elements)

Maturity: 1

Key Elements View

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. GraphDefinition C 0..* DomainResource Definition of a graph of resources

Elements defined in Ancestors:id, meta, implicitRules, language, text, contained, extension, modifierExtension
Interfaces Implemented: CanonicalResource
Constraints: cnl-0
... meta Σ 0..1 Meta Metadata about the resource
... implicitRules ?!Σ 0..1 uri A set of rules under which this content was created
... language 0..1 code Language of the resource content
Binding: AllLanguages (required): IETF language tag for a human language
Additional BindingsPurpose
CommonLanguages Starter
... text 0..1 Narrative Text summary of the resource, for human interpretation
This profile does not constrain the narrative in regard to content, language, or traceability to data elements
... contained 0..* Resource Contained, inline Resources
... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored
Slice: Unordered, Open by value:url
... url ΣC 0..1 uri Canonical identifier for this graph definition, represented as a URI (globally unique)
... identifier Σ 0..* Identifier Additional identifier for the GraphDefinition (business identifier)
... version Σ 0..1 string Business version of the graph definition
... versionAlgorithm[x] Σ 0..1 How to compare versions
Binding: VersionAlgorithm (extensible)
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 1..1 string Name for this graph definition (computer friendly)
... title Σ 0..1 string Name for this graph definition (human friendly)
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 0..1 dateTime Date last changed
... publisher Σ 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher
... description 0..1 markdown Natural language description of the graph definition
... useContext Σ 0..* UsageContext The context that the content is intended to support
... jurisdiction Σ 0..* CodeableConcept Jurisdiction of the authority that maintains the graph definition (if applicable)
Binding: Jurisdiction ValueSet (extensible): Countries and regions within which this artifact is targeted for use.
... purpose 0..1 markdown Why this graph definition is defined
... copyright 0..1 markdown Notice about intellectual property ownership, can include restrictions on use
... copyrightLabel 0..1 string Copyright holder and year(s)
... start 0..1 id Starting Node
... node 0..* BackboneElement Potential target for the link
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
.... nodeId 1..1 id Internal ID - target for link references
.... description 0..1 string Why this node is specified
.... type 1..1 code Type of resource this link refers to
Binding: VersionIndependentResourceTypesAll (required): A type of resource, or a Reference (from all versions)
Additional BindingsPurposeDocumentation
AllResourceTypes UI Binding
.... profile 0..1 canonical(StructureDefinition) Profile for the target resource
... link 0..* BackboneElement Links this graph makes rules about
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
.... description 0..1 string Why this link is specified
.... min 0..1 integer Minimum occurrences for this link
.... max 0..1 string Maximum occurrences for this link
.... sourceId 1..1 id Source Node for this link
.... path 0..1 string Path in the resource that contains the link
.... sliceName 0..1 string Which slice (if profiled)
.... targetId 1..1 id Target Node for this link
.... params 0..1 string Criteria for reverse lookup
.... compartment 0..* BackboneElement Compartment Consistency Rules
..... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
..... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
..... use 1..1 code where | requires
Binding: GraphCompartmentUse (required)
..... rule 1..1 code identical | matching | different | custom
Binding: GraphCompartmentRule (required)
..... code 1..1 code Patient | Encounter | RelatedPerson | Practitioner | Device | EpisodeOfCare
Binding: CompartmentType (required)
..... expression 0..1 string Custom rule, as a FHIRPath expression
..... description 0..1 string Documentation for FHIRPath expression

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
GraphDefinition.language Base required All Languages 📍6.0.0-ballot3 FHIR Std.
GraphDefinition.versionAlgorithm[x] Base extensible Version Algorithm 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.status Base required PublicationStatus 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.jurisdiction Base extensible Jurisdiction ValueSet 📦1.0.0 THO v7.2
GraphDefinition.node.​type Base required Version Independent Resource Types (All) 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.use Base required Graph Compartment Use 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.rule Base required Graph Compartment Rule 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.code Base required Compartment Type 📦6.0.0-ballot3 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
cnl-0 warning GraphDefinition Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
cnl-1 warning GraphDefinition.url URL should not contain | or # - these characters make processing canonical references problematic exists() implies matches('^[^|# ]+$')
dom-2 error GraphDefinition If the resource is contained in another resource, it SHALL NOT contain nested Resources contained.contained.empty()
dom-3 error GraphDefinition If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource contained.where((('#'+id.trace('id') in %resource.descendants().select(reference | as(uri))) or descendants().where(reference='#' | as(uri)='#').exists()).not()).trace('unmatched', id).empty()
dom-4 error GraphDefinition If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated contained.meta.versionId.empty() and contained.meta.lastUpdated.empty()
dom-5 error GraphDefinition If a resource is contained in another resource, it SHALL NOT have a security label contained.meta.security.empty()
dom-6 best practice GraphDefinition A resource should have narrative for robust management text.`div`.exists()
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())

Differential View

This structure is derived from DomainResource

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. GraphDefinition C 0..* DomainResource Definition of a graph of resources

Elements defined in Ancestors:id, meta, implicitRules, language, text, contained, extension, modifierExtension
Interfaces Implemented: CanonicalResource
Constraints: cnl-0
... url ΣC 0..1 uri Canonical identifier for this graph definition, represented as a URI (globally unique)
... identifier Σ 0..* Identifier Additional identifier for the GraphDefinition (business identifier)
... version Σ 0..1 string Business version of the graph definition
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 1..1 string Name for this graph definition (computer friendly)
... title Σ 0..1 string Name for this graph definition (human friendly)
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 0..1 dateTime Date last changed
... publisher Σ 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher
... description 0..1 markdown Natural language description of the graph definition
... useContext Σ 0..* UsageContext The context that the content is intended to support
... jurisdiction Σ 0..* CodeableConcept Jurisdiction of the authority that maintains the graph definition (if applicable)
Binding: Jurisdiction ValueSet (extensible): Countries and regions within which this artifact is targeted for use.
... purpose 0..1 markdown Why this graph definition is defined
... copyright 0..1 markdown Notice about intellectual property ownership, can include restrictions on use
... copyrightLabel 0..1 string Copyright holder and year(s)
... start 0..1 id Starting Node
... node 0..* BackboneElement Potential target for the link
.... nodeId 1..1 id Internal ID - target for link references
.... description 0..1 string Why this node is specified
.... type 1..1 code Type of resource this link refers to
Binding: VersionIndependentResourceTypesAll (required): A type of resource, or a Reference (from all versions)
Additional BindingsPurposeDocumentation
AllResourceTypes UI Binding
.... profile 0..1 canonical(StructureDefinition) Profile for the target resource
... link 0..* BackboneElement Links this graph makes rules about
.... description 0..1 string Why this link is specified
.... min 0..1 integer Minimum occurrences for this link
.... max 0..1 string Maximum occurrences for this link
.... sourceId 1..1 id Source Node for this link
.... path 0..1 string Path in the resource that contains the link
.... sliceName 0..1 string Which slice (if profiled)
.... targetId 1..1 id Target Node for this link
.... params 0..1 string Criteria for reverse lookup
.... compartment 0..* BackboneElement Compartment Consistency Rules
..... use 1..1 code where | requires
Binding: GraphCompartmentUse (required)
..... rule 1..1 code identical | matching | different | custom
Binding: GraphCompartmentRule (required)
..... code 1..1 code Patient | Encounter | RelatedPerson | Practitioner | Device | EpisodeOfCare
Binding: CompartmentType (required)
..... expression 0..1 string Custom rule, as a FHIRPath expression
..... description 0..1 string Documentation for FHIRPath expression

doco Documentation for this format

Terminology Bindings (Differential)

Path Status Usage ValueSet Version Source
GraphDefinition.versionAlgorithm[x] Base extensible Version Algorithm 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.status Base required PublicationStatus 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.jurisdiction Base extensible Jurisdiction ValueSet 📦1.0.0 THO v7.2
GraphDefinition.node.​type Base required Version Independent Resource Types (All) 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.use Base required Graph Compartment Use 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.rule Base required Graph Compartment Rule 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.code Base required Compartment Type 📦6.0.0-ballot3 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
cnl-0 warning GraphDefinition Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')

Snapshot View

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. GraphDefinition C 0..* DomainResource Definition of a graph of resources

Elements defined in Ancestors:id, meta, implicitRules, language, text, contained, extension, modifierExtension
Interfaces Implemented: CanonicalResource
Constraints: cnl-0
... meta Σ 0..1 Meta Metadata about the resource
... implicitRules ?!Σ 0..1 uri A set of rules under which this content was created
... language 0..1 code Language of the resource content
Binding: AllLanguages (required): IETF language tag for a human language
Additional BindingsPurpose
CommonLanguages Starter
... text 0..1 Narrative Text summary of the resource, for human interpretation
This profile does not constrain the narrative in regard to content, language, or traceability to data elements
... contained 0..* Resource Contained, inline Resources
... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored
Slice: Unordered, Open by value:url
... url ΣC 0..1 uri Canonical identifier for this graph definition, represented as a URI (globally unique)
... identifier Σ 0..* Identifier Additional identifier for the GraphDefinition (business identifier)
... version Σ 0..1 string Business version of the graph definition
... versionAlgorithm[x] Σ 0..1 How to compare versions
Binding: VersionAlgorithm (extensible)
.... versionAlgorithmString string
.... versionAlgorithmCoding Coding
... name ΣC 1..1 string Name for this graph definition (computer friendly)
... title Σ 0..1 string Name for this graph definition (human friendly)
... status ?!Σ 1..1 code draft | active | retired | unknown
Binding: PublicationStatus (required): The lifecycle status of an artifact.
... experimental Σ 0..1 boolean For testing only - never for real usage
... date Σ 0..1 dateTime Date last changed
... publisher Σ 0..1 string Name of the publisher/steward (organization or individual)
... contact Σ 0..* ContactDetail Contact details for the publisher
... description 0..1 markdown Natural language description of the graph definition
... useContext Σ 0..* UsageContext The context that the content is intended to support
... jurisdiction Σ 0..* CodeableConcept Jurisdiction of the authority that maintains the graph definition (if applicable)
Binding: Jurisdiction ValueSet (extensible): Countries and regions within which this artifact is targeted for use.
... purpose 0..1 markdown Why this graph definition is defined
... copyright 0..1 markdown Notice about intellectual property ownership, can include restrictions on use
... copyrightLabel 0..1 string Copyright holder and year(s)
... start 0..1 id Starting Node
... node 0..* BackboneElement Potential target for the link
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
.... nodeId 1..1 id Internal ID - target for link references
.... description 0..1 string Why this node is specified
.... type 1..1 code Type of resource this link refers to
Binding: VersionIndependentResourceTypesAll (required): A type of resource, or a Reference (from all versions)
Additional BindingsPurposeDocumentation
AllResourceTypes UI Binding
.... profile 0..1 canonical(StructureDefinition) Profile for the target resource
... link 0..* BackboneElement Links this graph makes rules about
.... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
.... description 0..1 string Why this link is specified
.... min 0..1 integer Minimum occurrences for this link
.... max 0..1 string Maximum occurrences for this link
.... sourceId 1..1 id Source Node for this link
.... path 0..1 string Path in the resource that contains the link
.... sliceName 0..1 string Which slice (if profiled)
.... targetId 1..1 id Target Node for this link
.... params 0..1 string Criteria for reverse lookup
.... compartment 0..* BackboneElement Compartment Consistency Rules
..... extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
..... modifierExtension ?!Σ 0..* Extension Extensions that cannot be ignored even if unrecognized
..... use 1..1 code where | requires
Binding: GraphCompartmentUse (required)
..... rule 1..1 code identical | matching | different | custom
Binding: GraphCompartmentRule (required)
..... code 1..1 code Patient | Encounter | RelatedPerson | Practitioner | Device | EpisodeOfCare
Binding: CompartmentType (required)
..... expression 0..1 string Custom rule, as a FHIRPath expression
..... description 0..1 string Documentation for FHIRPath expression

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
GraphDefinition.language Base required All Languages 📍6.0.0-ballot3 FHIR Std.
GraphDefinition.versionAlgorithm[x] Base extensible Version Algorithm 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.status Base required PublicationStatus 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.jurisdiction Base extensible Jurisdiction ValueSet 📦1.0.0 THO v7.2
GraphDefinition.node.​type Base required Version Independent Resource Types (All) 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.use Base required Graph Compartment Use 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.rule Base required Graph Compartment Rule 📦6.0.0-ballot3 FHIR Std.
GraphDefinition.link.​compartment.code Base required Compartment Type 📦6.0.0-ballot3 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
cnl-0 warning GraphDefinition Name should be usable as an identifier for the module by machine processing applications such as code generation name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')
cnl-1 warning GraphDefinition.url URL should not contain | or # - these characters make processing canonical references problematic exists() implies matches('^[^|# ]+$')
dom-2 error GraphDefinition If the resource is contained in another resource, it SHALL NOT contain nested Resources contained.contained.empty()
dom-3 error GraphDefinition If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource contained.where((('#'+id.trace('id') in %resource.descendants().select(reference | as(uri))) or descendants().where(reference='#' | as(uri)='#').exists()).not()).trace('unmatched', id).empty()
dom-4 error GraphDefinition If a resource is contained in another resource, it SHALL NOT have a meta.versionId or a meta.lastUpdated contained.meta.versionId.empty() and contained.meta.lastUpdated.empty()
dom-5 error GraphDefinition If a resource is contained in another resource, it SHALL NOT have a security label contained.meta.security.empty()
dom-6 best practice GraphDefinition A resource should have narrative for robust management text.`div`.exists()
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())

This structure is derived from DomainResource

Summary

Mandatory: 0 element(9 nested mandatory elements)

Maturity: 1

 

​Other representations of profile: CSV, Excel, Schematron

Notes:

Using GraphDefinitions

The GraphDefinition resource can be used to:

  • Summarize a set of profiles on resources
  • Define a graph of resources to return in a query
  • Define a graph of resources to include in a document
  • Document rules about the relationship between a set of resources e.g. must all resources concern the same patient?

Summarize a set of profiles on resources

FHIR resources are relatively granular. In many/most cases, many resources are needed to handle any particular task. A typical example of this is a complex diagnostic report: it will start with a DiagnosticReport, which will link to a set of panels (Observation resources), each of which link to a set of Observation resources for atomic data items.

One way to represent this is to profile each of the resources, creating hundreds of profiles, and then leave it to the user to infer the overall pattern of the report from the detailed profiles for each observation in the report. But it's not easy to see the forest for the trees. A GraphDefinition can summarize the overall picture and present a summary to the user.

Here's an example of the kind of summary this represents. (Todo: make this an actual graph definition, and clone into the main spec)

Fetching a graph of resources

As another example of using many resources, to completely represent a medication dispense, an application needs not only the MedicationDispense resource, but also resources to represent the patient, provider, organizations, and the associated prescription.

A client can retrieve a single resource: 

  GET [base]/MedicationDispense/example

Then, when it reads the returned resource, it can fetch the referenced resources: 

  GET [base]/Patient/example
  GET [base]/Practitioner/example
  GET [base]/MedicationRequest/example
  ... etc.

This is a very inefficient way to retrieve all the required resources. An alternative approach is to do a search, and _include the required resources: 

  GET [base]/MedicationDispense?_id=example
    &_include=MedicationDispense:authorizingPrescription
    &_include=MedicationDispense:subject

But scaling this approach to fetch a full package with its dependencies becomes increasingly difficult as the package gets deeper. A graph definition can be used instead to inform the server what to return with the resource using the $graph operation: 

  GET [base]/MedicationDispense/example/$graph?graph=med-package

This is a request to return a graph of resource, using the graph definition 'med-package'. In this case, the graph definition would look approximately like this: 

MedicationDispense
  .subject
  .context
  .performer.actor
  .authorizingPrescription
     .requester.agent 
  .substitution.responsibleParty

Systems may either provide a pre-defined list of graph definitions that clients may choose from, or allow clients to define their own GraphDefinition resources and then refer to them.

Server may also allow clients also pass in their own graph definition using a text representation: 

  GET [base]/MedicationDispense/example/$graph?definition=Patient{managingOrganization:Organization{endpoint:Endpoint}}

See below for further details.

Building a document

A very similar issue applies when building a document using the $document operation. A document must include all the resources linked directly from the composition, but whether to include additional linked resources is at the discretion of the document author. How does the user inform the $document operation which linked resources to include? One option is a boolean flag for including all linked data, but this may be extensive - up to an entire patient record - and may include resources that are not desired.

An operation can use a graph definition as a parameter to the $document operation: 

GET [base]/Composition/example/$document?graph=example

​ This tells the server to include the graph of resources defined in the example GraphDefinition - in this case, any resources referred to from lists, when the section content is a list. Alternatively, servers may allow a client to pass in a definition directly (as shown above) using the parameter definition.

Document Relationship rules

One important question about the use of resources is cross-resource consistency. For example, if an Observation refers to both a Patient and Encounter, does the Encounter have to refer to the same patient?

In general, the answer to this is that it usually should - the record needs to be consistent. However there are edge cases where the references may differ. For example, with regard to patient references, they may differ for:

  • Health Records concerning mother and baby
  • Organ Transplants
  • Counselling, particularly family counselling

Other reasons for the references to differ - mixing records about the same patient from different servers, or specific records about patients mixed with records about groups of patients (particularly common in veterinarian care).

The GraphDefinition resource allows for compartment consistency rules to be made regarding the links between resources. For each link in the graph, the graph definition can make a rule about the compartment consistency. The rule can specify one of the following consistencies:

CodeMeaning
identicalThe compartment must be identical (the same literal reference)
matchingThe compartment must be the same - the record must be about the same patient, but the reference may be different
differentThe compartment must be different
customThe compartment rule is defined in the accompanying FHIRPath expression

Todo: how would this be validated? - where is the graph referred to?

Simple Examples

GraphDefinition can walk a graph forward through the links, which is the natural order. As an example, consider a profile on composition that wants to specify that the graph follows the section entry into a list: 

<!-- this graph starts with a composition. We don't care what the specific profile is
     (though the statement above 'this case doesn't cross patients' implies that we do care a little) -->
  <start value="composition1"/>
  
  <node>
    <nodeId value="composition1"/>
    <description value="The base composition"/>
    <type value="Composition"/>
    <profile value="http://hl7.org/fhir/StructureDefinition/clinicaldocument"/>
  </node>
  <node>
    <nodeId value="list1"/>
    <description value="A list resource that a section entry reference points to"/>
    <type value="List"/>
  </node>
  <node>
    <nodeId value="resN"/>
    <description value="Generic resource that's the target of a list reference"/>
    <type value="Resource"/>
  </node>

  <!-- define the section -> list link -->
  <link>
    <description value="Link from Composition.section to list"/>
    <sourceId value="composition1"/>
    <!-- any section entry. Todo: this recurses; are we profiling this at all levels? --> 
    <path value="Composition.section.entry"/>
    <!-- 
      one target. This graph is not making rules about the content of the section entries - that
      would be done in a profile. it's just saying, if you see a reference to a list in a section
      entry, these are the rules that describe the graph
    -->
    <targetId value="list1"/>
  </link>    

  <!-- and from the list, any references -->
  <link>
    <description value="Include any list entries"/>
    <sourceId value="list1"/>
    <path value="List.entry.item"/>
    <targetId value="resN"/>
  </link>

The pattern can be extended to require that the none of the resources in this little graph reference a different patient - that is, it is a requirement when traversing the links that the patient compartment remain identical: 

  <!-- define the section -> list link -->
  <link>
    <description value="Link from Composition.section to list"/>
    <sourceId value="composition1"/>
    <!-- any section entry. Todo: this recurses; are we profiling this at all levels? --> 
    <path value="Composition.section.entry"/>
    <!-- 
      one target. This graph is not making rules about the content of the section entries - that
      would be done in a profile. it's just saying, if you see a reference to a list in a section
      entry, these are the rules that describe the graph
    -->
    <targetId value="list1"/>
    <compartment>
      <use value="requirement"/>
      <code value="Patient"/>
      <rule value="identical"/>
    </compartment>
  </link>    

  <!-- and from the list, any references -->
  <link>
    <description value="Include any list entries"/>
    <sourceId value="list1"/>
    <path value="List.entry.item"/>
    <targetId value="resN"/>
    <compartment>
      <use value="requirement"/>
      <code value="Patient"/>
      <rule value="identical"/>
    </compartment>
  </link>

Another useful approach is to walk any link * (e.g. wildcard support): 

  <link>
    <sourceId value="comp1">
    <!-- 
      follow all links that refers to a list
    -->
    <path value="*"/>
    <targetId value="list1">
  </link>
  <!-- and inside this list, follow any references -->
  <link>
    <sourceId value="list1">
    <path value="*"/>
    <targetId value="resN"/>
  </link>

or you can follow any links in any resource: 

  <link>
    <!-- 
      follow all links 
    -->
    <path value="*"/>
    <targetid value="resN"/>
  </link>

It's also possible to build a graph by walking links in reverse. This technique is useful, for example, when including provenance resources in a document: 

  <link>
    <sourceId value="obs1"/>
    <!-- if the path is missing <path value=""/> -->
    <targetId value="prov"/>  <!-- any provenance -->
    <!--
      and specify the search parameters to include 
      all the provenances that refer to this resource
    -->
    <params value="target={ref}"/>      
  </link>

Text Representation

For convenience, a graph definition may be represented using a text short hand form. A graph definition is introduced by two or more node statements: 

node start comp1 'The base composition' = Composition (http://hl7.org/fhir/StructureDefinition/clinicaldocument);
node list1 'A list resource that a section entry reference points to' = List;
node resN 'Generic resource that's the target of a list reference' = Resource;

Each node declaration starts with the fixed word node followed by the nodeId, the node description, =, the node type, and then, if the node has a profile, the profile value in brackets. One of the nodes have the key word "start"

Once all the nodes are declared, then the links are declared: 

link 'Link from Composition.section to list' = comp1[Composition.section.entry] -> list1 requires identical patient;
link 'Include any list entries' = list1[List.entry.item] -> resN requires identical patient;

The format for a link is: 

link '{description}' {min}..{max} = sourceId[{path}:{sliceName}] {targetId}?{params} {resource-compartment-rules};

where:

  • description, min, max, path, sliceName, params and resource-type-rules are all optional
  • resource-compartment-rules is present if there's a compartent, and the syntax is {use} {rule} {code}. If the rule is 'custom' then the syntax is '=' '{fhirpath}' '{description}'

In this format, the amount of whitespace, and its form, is irrelevant. For the purposes of clarity, the statements here are laid out on different lines, but this is not required. When a GraphDefinition is used as a parameter in a url, no extra whitespace is used, just a single space, and the descriptions SHOULD be omitted.

Here is a full example that uses all the features of the syntax: 

node pat = Patient;
node org = Organization;
node org2 = Organization;
node ept = EndPoint;
node prac = Practitioner;
node grp = Group;

link 'patient managing org' 0..1 = pat[managingOrganization] -> org;
link = org[endpoint] -> ept
link 'groups patient is in' = pat -> grp?item={ref}
link 'registered GP' = pat[generalPractitioner] -> org;
link 'Observations for the patient' = pat -> org?patient={ref};
link = org[performer] -> prac;
link = org[related.where(type='has-member').target] -> org2 requires matching Patient;
link = org[related.where(type='derived-from').target] -> org2 requires identical Patient;
link = org[related.where(type='sequel-to').target] -> org2 requires different Organization;
link = org[related.where(type='qualified-by').target] -> org2 requires custom Patient = path;