R4 Ballot #1 (Mixed Normative/Trial use) Current Build
This page was published as part of FHIR v3.3.0: R4 Ballot #1 : Mixed Normative/Trial use (First Normative ballot). It has been superceded by R4 . For a full list of available versions, see the Directory of published versions .

# 5.9 5.10 Resource GraphDefinition - Content

 FHIR Infrastructure Work Group Maturity Level : 0 1 Draft Trial Use Security Category : Anonymous Compartments : Not linked to any defined compartments

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

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 would need to be represented in their profiles

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 if resources will meet the constraints expressed. Applications should - but are not required - detect when such incompatibilities arise.

This resource is referenced by MessageDefinition .

This resource does not implement any patterns.

Structure

Name Flags Card. Type Description & Constraints
GraphDefinition D I TU DomainResource Definition of a graph of resources
+ Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation
Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension
url Σ 0..1 uri Canonical identifier for this graph definition, represented as a URI (globally unique)
version Σ 0..1 string Business version of the graph definition
name Σ I 1..1 string Name for this graph definition (computer friendly)
status ?! Σ 1..1 code draft | active | retired | unknown
PublicationStatus ( Required )
experimental ?! Σ 0..1 boolean For testing purposes, not real usage
date Σ 0..1 dateTime Date last changed
publisher Σ 0..1 string Name of the publisher (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 Intended jurisdiction for graph definition (if applicable)
Jurisdiction ValueSet ( Extensible )
purpose 0..1 markdown Why this graph definition is defined
start Σ 1..1 code Type of resource at which the graph starts
ResourceType ( Required )
profile 0..1 canonical ( StructureDefinition ) Profile on base resource
path 0..1 string Path in the resource that contains the link
sliceName 0..1 string Which slice (if profiled)
min 0..1 integer Minimum occurrences for this link
max 0..1 string Maximum occurrences for this link
description 0..1 string Why this link is specified
target 0..* BackboneElement Potential target for the link
type 1..1 code Type of resource this link refers to
ResourceType ( Required )
params 0..1 string Criteria for reverse lookup
profile 0..1 canonical ( StructureDefinition ) Profile for the target resource
compartment 0..* BackboneElement Compartment Consistency Rules
use 1..1 code condition | requirement
GraphCompartmentUse ( Required )
code 1..1 code Identifies the compartment Patient | Encounter | RelatedPerson | Practitioner | Device
CompartmentType ( Required )
rule 1..1 code identical | matching | different | custom
GraphCompartmentRule ( Required )
expression 0..1 string Custom rule, as a FHIRPath expression
description 0..1 string Documentation for FHIRPath expression

Documentation for this format

XML Template

<GraphDefinition xmlns="http://hl7.org/fhir">
<!-- from Resource: id, meta, implicitRules, and language -->
<!-- from DomainResource: text, contained, extension, and modifierExtension -->
<

<url value="[uri]"/><!-- 0..1 Canonical identifier for this graph definition, represented as a URI (globally unique) -->

<version value="[string]"/><!-- 0..1 Business version of the graph definition -->
<

<name value="[string]"/><!--  1..1 Name for this graph definition (computer friendly) -->

<status value="[code]"/><!-- 1..1 draft | active | retired | unknown -->
<

<experimental value="[boolean]"/><!-- 0..1 For testing purposes, not real usage -->

<date value="[dateTime]"/><!-- 0..1 Date last changed -->
<publisher value="[string]"/><!-- 0..1 Name of the publisher (organization or individual) -->
<contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>
<description value="[markdown]"/><!-- 0..1 Natural language description of the graph definition -->
<</useContext>

<useContext><!-- 0..* UsageContext The context that the content is intended to support --></useContext>

<jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction for graph definition (if applicable) --></jurisdiction>
<purpose value="[markdown]"/><!-- 0..1 Why this graph definition is defined -->
<start value="[code]"/><!-- 1..1 Type of resource at which the graph starts -->
<profile><!-- 0..1  Profile on base resource --></profile>
<path value="[string]"/><!-- 0..1 Path in the resource that contains the link -->
<sliceName value="[string]"/><!-- 0..1 Which slice (if profiled) -->
<min value="[integer]"/><!-- 0..1 Minimum occurrences for this link -->
<max value="[string]"/><!-- 0..1 Maximum occurrences for this link -->
<description value="[string]"/><!-- 0..1 Why this link is specified -->
<target>  <!-- 0..* Potential target for the link -->
<type value="[code]"/><!-- 1..1 Type of resource this link refers to -->
<params value="[string]"/><!-- 0..1 Criteria for reverse lookup -->
<profile><!-- 0..1  Profile for the target resource --></profile>
<compartment>  <!-- 0..* Compartment Consistency Rules -->
<use value="[code]"/><!-- 1..1 condition | requirement -->
<

<code value="[code]"/><!-- 1..1 Patient | Encounter | RelatedPerson | Practitioner | Device -->

<rule value="[code]"/><!-- 1..1 identical | matching | different | custom -->
<expression value="[string]"/><!-- 0..1 Custom rule, as a FHIRPath expression -->
<description value="[string]"/><!-- 0..1 Documentation for FHIRPath expression -->
</compartment>
</target>
</GraphDefinition>

JSON Template

{
"resourceType" : "GraphDefinition",
// from Resource: id, meta, implicitRules, and language
// from DomainResource: text, contained, extension, and modifierExtension
"

"url" : "<uri>", // Canonical identifier for this graph definition, represented as a URI (globally unique)

"version" : "<string>", // Business version of the graph definition
"

"name" : "<string>", // C? R!  Name for this graph definition (computer friendly)

"status" : "<code>", // R!  draft | active | retired | unknown
"

"experimental" : <boolean>, // For testing purposes, not real usage

"date" : "<dateTime>", // Date last changed
"publisher" : "<string>", // Name of the publisher (organization or individual)
"contact" : [{ ContactDetail }], // Contact details for the publisher
"description" : "<markdown>", // Natural language description of the graph definition
"

"useContext" : [{ UsageContext }], // The context that the content is intended to support

"jurisdiction" : [{ CodeableConcept }], // Intended jurisdiction for graph definition (if applicable)
"purpose" : "<markdown>", // Why this graph definition is defined
"start" : "<code>", // R!  Type of resource at which the graph starts
"

"profile" : {  }, // Profile on base resource

"path" : "<string>", // Path in the resource that contains the link
"sliceName" : "<string>", // Which slice (if profiled)
"min" : <integer>, // Minimum occurrences for this link
"max" : "<string>", // Maximum occurrences for this link
"description" : "<string>", // Why this link is specified
"target" : [{ // Potential target for the link
"type" : "<code>", // R!  Type of resource this link refers to
"params" : "<string>", // Criteria for reverse lookup
"

"profile" : {  }, // Profile for the target resource

"compartment" : [{ // Compartment Consistency Rules
"use" : "<code>", // R!  condition | requirement
"

"code" : "<code>", // R!  Patient | Encounter | RelatedPerson | Practitioner | Device

"rule" : "<code>", // R!  identical | matching | different | custom
"expression" : "<string>", // Custom rule, as a FHIRPath expression
"description" : "<string>" // Documentation for FHIRPath expression
}],
}]
}]
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .
[ a fhir:GraphDefinition;
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:

fhir:GraphDefinition.url [ uri ]; # 0..1 Canonical identifier for this graph definition, represented as a URI (globally unique)

fhir:GraphDefinition.version [ string ]; # 0..1 Business version of the graph definition
fhir:GraphDefinition.name [ string ]; # 1..1 Name for this graph definition (computer friendly)
fhir:GraphDefinition.status [ code ]; # 1..1 draft | active | retired | unknown
fhir:

fhir:GraphDefinition.experimental [ boolean ]; # 0..1 For testing purposes, not real usage

fhir:GraphDefinition.date [ dateTime ]; # 0..1 Date last changed
fhir:GraphDefinition.publisher [ string ]; # 0..1 Name of the publisher (organization or individual)
fhir:GraphDefinition.contact [ ContactDetail ], ... ; # 0..* Contact details for the publisher
fhir:GraphDefinition.description [ markdown ]; # 0..1 Natural language description of the graph definition
fhir:

fhir:GraphDefinition.useContext [ UsageContext ], ... ; # 0..* The context that the content is intended to support

fhir:GraphDefinition.jurisdiction [ CodeableConcept ], ... ; # 0..* Intended jurisdiction for graph definition (if applicable)
fhir:GraphDefinition.purpose [ markdown ]; # 0..1 Why this graph definition is defined
fhir:GraphDefinition.start [ code ]; # 1..1 Type of resource at which the graph starts
fhir:GraphDefinition.profile [ canonical(StructureDefinition) ]; # 0..1 Profile on base resource
fhir:GraphDefinition.link.path [ string ]; # 0..1 Path in the resource that contains the link
fhir:GraphDefinition.link.sliceName [ string ]; # 0..1 Which slice (if profiled)
fhir:GraphDefinition.link.target.type [ code ]; # 1..1 Type of resource this link refers to
fhir:GraphDefinition.link.target.params [ string ]; # 0..1 Criteria for reverse lookup
fhir:GraphDefinition.link.target.profile [ canonical(StructureDefinition) ]; # 0..1 Profile for the target resource
fhir:GraphDefinition.link.target.compartment [ # 0..* Compartment Consistency Rules
fhir:GraphDefinition.link.target.compartment.use [ code ]; # 1..1 condition | requirement
fhir:

fhir:GraphDefinition.link.target.compartment.code [ code ]; # 1..1 Patient | Encounter | RelatedPerson | Practitioner | Device

fhir:GraphDefinition.link.target.compartment.rule [ code ]; # 1..1 identical | matching | different | custom
fhir:GraphDefinition.link.target.compartment.expression [ string ]; # 0..1 Custom rule, as a FHIRPath expression
fhir:GraphDefinition.link.target.compartment.description [ string ]; # 0..1 Documentation for FHIRPath expression
], ...;
], ...;
], ...;
]

Changes since R3

See the Full Difference for further information

This analysis is available as XML or JSON .

See R3 <--> R4 Conversion Maps (status = 1 test that all execute ok. All tests pass round-trip testing and 1 r3 resources are invalid (0 errors). )

Structure

Name Flags Card. Type Description & Constraints
GraphDefinition D I TU DomainResource Definition of a graph of resources
+ Warning: Name should be usable as an identifier for the module by machine processing applications such as code generation
Elements defined in Ancestors: id , meta , implicitRules , language , text , contained , extension , modifierExtension
url Σ 0..1 uri Canonical identifier for this graph definition, represented as a URI (globally unique)
version Σ 0..1 string Business version of the graph definition
name Σ I 1..1 string Name for this graph definition (computer friendly)
status ?! Σ 1..1 code draft | active | retired | unknown
PublicationStatus ( Required )
experimental ?! Σ 0..1 boolean For testing purposes, not real usage
date Σ 0..1 dateTime Date last changed
publisher Σ 0..1 string Name of the publisher (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 Intended jurisdiction for graph definition (if applicable)
Jurisdiction ValueSet ( Extensible )
purpose 0..1 markdown Why this graph definition is defined
start Σ 1..1 code Type of resource at which the graph starts
ResourceType ( Required )
profile 0..1 canonical ( StructureDefinition ) Profile on base resource
path 0..1 string Path in the resource that contains the link
sliceName 0..1 string Which slice (if profiled)
min 0..1 integer Minimum occurrences for this link
max 0..1 string Maximum occurrences for this link
description 0..1 string Why this link is specified
target 0..* BackboneElement Potential target for the link
type 1..1 code Type of resource this link refers to
ResourceType ( Required )
params 0..1 string Criteria for reverse lookup
profile 0..1 canonical ( StructureDefinition ) Profile for the target resource
compartment 0..* BackboneElement Compartment Consistency Rules
use 1..1 code condition | requirement
GraphCompartmentUse ( Required )
code 1..1 code Identifies the compartment Patient | Encounter | RelatedPerson | Practitioner | Device
CompartmentType ( Required )
rule 1..1 code identical | matching | different | custom
GraphCompartmentRule ( Required )
expression 0..1 string Custom rule, as a FHIRPath expression
description 0..1 string Documentation for FHIRPath expression

Documentation for this format

XML Template

<GraphDefinition xmlns="http://hl7.org/fhir">
<!-- from Resource: id, meta, implicitRules, and language -->
<!-- from DomainResource: text, contained, extension, and modifierExtension -->
<

<url value="[uri]"/><!-- 0..1 Canonical identifier for this graph definition, represented as a URI (globally unique) -->

<version value="[string]"/><!-- 0..1 Business version of the graph definition -->
<

<name value="[string]"/><!--  1..1 Name for this graph definition (computer friendly) -->

<status value="[code]"/><!-- 1..1 draft | active | retired | unknown -->
<

<experimental value="[boolean]"/><!-- 0..1 For testing purposes, not real usage -->

<date value="[dateTime]"/><!-- 0..1 Date last changed -->
<publisher value="[string]"/><!-- 0..1 Name of the publisher (organization or individual) -->
<contact><!-- 0..* ContactDetail Contact details for the publisher --></contact>
<description value="[markdown]"/><!-- 0..1 Natural language description of the graph definition -->
<</useContext>

<useContext><!-- 0..* UsageContext The context that the content is intended to support --></useContext>

<jurisdiction><!-- 0..* CodeableConcept Intended jurisdiction for graph definition (if applicable) --></jurisdiction>
<purpose value="[markdown]"/><!-- 0..1 Why this graph definition is defined -->
<start value="[code]"/><!-- 1..1 Type of resource at which the graph starts -->
<profile><!-- 0..1  Profile on base resource --></profile>
<path value="[string]"/><!-- 0..1 Path in the resource that contains the link -->
<sliceName value="[string]"/><!-- 0..1 Which slice (if profiled) -->
<min value="[integer]"/><!-- 0..1 Minimum occurrences for this link -->
<max value="[string]"/><!-- 0..1 Maximum occurrences for this link -->
<description value="[string]"/><!-- 0..1 Why this link is specified -->
<target>  <!-- 0..* Potential target for the link -->
<type value="[code]"/><!-- 1..1 Type of resource this link refers to -->
<params value="[string]"/><!-- 0..1 Criteria for reverse lookup -->
<profile><!-- 0..1  Profile for the target resource --></profile>
<compartment>  <!-- 0..* Compartment Consistency Rules -->
<use value="[code]"/><!-- 1..1 condition | requirement -->
<

<code value="[code]"/><!-- 1..1 Patient | Encounter | RelatedPerson | Practitioner | Device -->

<rule value="[code]"/><!-- 1..1 identical | matching | different | custom -->
<expression value="[string]"/><!-- 0..1 Custom rule, as a FHIRPath expression -->
<description value="[string]"/><!-- 0..1 Documentation for FHIRPath expression -->
</compartment>
</target>
</GraphDefinition>

JSON Template

{
"resourceType" : "GraphDefinition",
// from Resource: id, meta, implicitRules, and language
// from DomainResource: text, contained, extension, and modifierExtension
"

"url" : "<uri>", // Canonical identifier for this graph definition, represented as a URI (globally unique)

"version" : "<string>", // Business version of the graph definition
"

"name" : "<string>", // C? R!  Name for this graph definition (computer friendly)

"status" : "<code>", // R!  draft | active | retired | unknown
"

"experimental" : <boolean>, // For testing purposes, not real usage

"date" : "<dateTime>", // Date last changed
"publisher" : "<string>", // Name of the publisher (organization or individual)
"contact" : [{ ContactDetail }], // Contact details for the publisher
"description" : "<markdown>", // Natural language description of the graph definition
"

"useContext" : [{ UsageContext }], // The context that the content is intended to support

"jurisdiction" : [{ CodeableConcept }], // Intended jurisdiction for graph definition (if applicable)
"purpose" : "<markdown>", // Why this graph definition is defined
"start" : "<code>", // R!  Type of resource at which the graph starts
"

"profile" : {  }, // Profile on base resource

"path" : "<string>", // Path in the resource that contains the link
"sliceName" : "<string>", // Which slice (if profiled)
"min" : <integer>, // Minimum occurrences for this link
"max" : "<string>", // Maximum occurrences for this link
"description" : "<string>", // Why this link is specified
"target" : [{ // Potential target for the link
"type" : "<code>", // R!  Type of resource this link refers to
"params" : "<string>", // Criteria for reverse lookup
"

"profile" : {  }, // Profile for the target resource

"compartment" : [{ // Compartment Consistency Rules
"use" : "<code>", // R!  condition | requirement
"

"code" : "<code>", // R!  Patient | Encounter | RelatedPerson | Practitioner | Device

"rule" : "<code>", // R!  identical | matching | different | custom
"expression" : "<string>", // Custom rule, as a FHIRPath expression
"description" : "<string>" // Documentation for FHIRPath expression
}],
}]
}]
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .
[ a fhir:GraphDefinition;
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:

fhir:GraphDefinition.url [ uri ]; # 0..1 Canonical identifier for this graph definition, represented as a URI (globally unique)

fhir:GraphDefinition.version [ string ]; # 0..1 Business version of the graph definition
fhir:GraphDefinition.name [ string ]; # 1..1 Name for this graph definition (computer friendly)
fhir:GraphDefinition.status [ code ]; # 1..1 draft | active | retired | unknown
fhir:

fhir:GraphDefinition.experimental [ boolean ]; # 0..1 For testing purposes, not real usage

fhir:GraphDefinition.date [ dateTime ]; # 0..1 Date last changed
fhir:GraphDefinition.publisher [ string ]; # 0..1 Name of the publisher (organization or individual)
fhir:GraphDefinition.contact [ ContactDetail ], ... ; # 0..* Contact details for the publisher
fhir:GraphDefinition.description [ markdown ]; # 0..1 Natural language description of the graph definition
fhir:

fhir:GraphDefinition.useContext [ UsageContext ], ... ; # 0..* The context that the content is intended to support

fhir:GraphDefinition.jurisdiction [ CodeableConcept ], ... ; # 0..* Intended jurisdiction for graph definition (if applicable)
fhir:GraphDefinition.purpose [ markdown ]; # 0..1 Why this graph definition is defined
fhir:GraphDefinition.start [ code ]; # 1..1 Type of resource at which the graph starts
fhir:GraphDefinition.profile [ canonical(StructureDefinition) ]; # 0..1 Profile on base resource
fhir:GraphDefinition.link.path [ string ]; # 0..1 Path in the resource that contains the link
fhir:GraphDefinition.link.sliceName [ string ]; # 0..1 Which slice (if profiled)
fhir:GraphDefinition.link.target.type [ code ]; # 1..1 Type of resource this link refers to
fhir:GraphDefinition.link.target.params [ string ]; # 0..1 Criteria for reverse lookup
fhir:GraphDefinition.link.target.profile [ canonical(StructureDefinition) ]; # 0..1 Profile for the target resource
fhir:GraphDefinition.link.target.compartment [ # 0..* Compartment Consistency Rules
fhir:GraphDefinition.link.target.compartment.use [ code ]; # 1..1 condition | requirement
fhir:

fhir:GraphDefinition.link.target.compartment.code [ code ]; # 1..1 Patient | Encounter | RelatedPerson | Practitioner | Device

fhir:GraphDefinition.link.target.compartment.rule [ code ]; # 1..1 identical | matching | different | custom
fhir:GraphDefinition.link.target.compartment.expression [ string ]; # 0..1 Custom rule, as a FHIRPath expression
fhir:GraphDefinition.link.target.compartment.description [ string ]; # 0..1 Documentation for FHIRPath expression
], ...;
], ...;
], ...;
]

Changes since DSTU2 Release 3

See the Full Difference for further information

This analysis is available as XML or JSON .

See R3 <--> R4 Conversion Maps (status = 1 test that all execute ok. All tests pass round-trip testing and 1 r3 resources are invalid (0 errors). )

Alternate See the Profiles & Extensions and the alternate definitions: Master Definition XML + JSON , XML Schema / Schematron + JSON Schema , ShEx (for Turtle ) + see the extensions , the spreadsheet version & the dependency analysis a

Path Definition Type Reference
GraphDefinition.status The lifecycle status of an artifact. Required PublicationStatus
GraphDefinition.jurisdiction Countries and regions within which this artifact is targeted for use use. Extensible Jurisdiction ValueSet
GraphDefinition.start
One of the resource types defined as part of this version of FHIR. Required Resource Types
GraphDefinition.link.target.compartment.use Defines how a compartment rule is used used. Required GraphCompartmentUse
GraphDefinition.link.target.compartment.code Identifies a compartment compartment. Required CompartmentType

 id Level Location Description Expression gdf-0 Warning (base) Name should be usable as an identifier for the module by machine processing applications such as code generation name.matches('[A-Z]([A-Za-z0-9_]){0,254}')

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?

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)

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 as part of with the search: 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.

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 .

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:

 Code Meaning identical The compartment must be identical (the same literal reference) matching The compartment must be the same - the record must be about the same patient, but the reference may be different different The compartment must be different custom The compartment rule is defined in the accompanying FHIRPath expression

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

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:

<!--
starting from a Composition...
-->
<!--
follow and Composition.section.entry that refers to a list
-->
<path value="Composition.section.entry"/>
<target>
<type value="List"/>
<!-- and inside this list, follow any items -->
<path value="List.entry.item"/>
<target>
<type value="Resource"/>
</target>
</target>

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:

<path value="Composition.section.entry"/>
<target>
<type value="List"/>
<compartment>
<use value="requirement"/>
<code value="Patient"/>
<rule value="identical"/>
</compartment>
</target>
<path value="List.entry.item"/>
<description value="Include any list entries"/>
<target>
<type value="Resource"/>
<compartment>
<use value="requirement"/>
<code value="Patient"/>
<rule value="identical"/>
</compartment>
</target>
</target>

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

<!--
-->
<path value="*"/>
<target>
<type value="List"/>
<!-- and inside this list, follow any references -->
<path value="*"/>
<target>
<type value="Resource"/>
</target>
</target>

<!--
-->
<path value="*"/>
<target>
<type value="Resource"/>
<path value="*"/>
<target>
<type value="Resource"/>
</target>
</target>

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:

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

For convenience, a graph definition may be represented using a text short hand form, loosely based on the graphQL language . A graph definition is introduced by the name of the Resource ( GraphDefinition.start , followed by an optional profile in parentheses ( GraphDefinition.profile , then a group of links, surrounded by { and } :

Patient(http://hl7.org/fhir/us/core/Patient) {
}

Between the brackets are one or more links ( GraphDefinition.link ), separated by commas. Links statements can either be path-based look ups, or a search to perform a reverse lookup:

Patient {
managingOrganization : Organization,
generalPractitioner : Practitioner,
search Observation?patient={ref}
}

The format for a path-based look up is:

[path] cardinality [min]..[max] '[description]' : [ResoureType rules]

where:

• cardinality [min]..[max] is optional, and min = GraphDefinition.link.min and max = GraphDefinition.link.max
• description is optional, and = GraphDefinition.link.description

The resource type rules statement consists of one or more of the following, separated by ; characters:

[ResourceType] (profile)

where:

• profile is optional, and = GraphDefinition.link.target.profile
• description is optional, and = GraphDefinition.link.description

In addition, the resource type rule may be followed by a links section, surrounded by {} , with the content as described above.

Search statements for reverse look ups have a slightly different format:

Patient{
search [ResourceType]?[params] cardinality [min]..[max] '[description]'
}

where:

• cardinality [min]..[max] is optional, and min = GraphDefinition.link.min and max = GraphDefinition.link.max
• description is optional, and = GraphDefinition.link.description

In this format, the amount of whitespace, and its form, is irrelevant. For the purposes of clarity, the examples here are laid out on different lines, but this is not required. When a GraphDefinition is used as a parameter in a url, no whitespace is used.

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

Patient(http://hl7.org/fhir/us/core/Patient) {
managingOrganization cardinality 0..1 'description of item' :
Organization(http://hl7.org/fhir/us/core/Organization) {
endpoint : Endpoint
};
Basic;
Group {
item : Patient
},
generalPractitioner : Organization,
search Observation?patient={ref} cardinality 0..10 'Observations for the patient' {
performer : Practitioner,
related.where(type='has-member').target : Observation require matching Patient,
related.where(type='derived-from').target : Observation where identical Patient,
related.where(type='sequel-to').target : Observation where different Patient,
related.where(type='qualified-by').target : Observation where custom Patient = path
}
}

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

 Name Type Description Expression In Common context token A use context assigned to the graph definition (GraphDefinition.useContext.value as CodeableConcept) context-quantity quantity A quantity- or range-valued use context assigned to the graph definition (GraphDefinition.useContext.value as Quantity) | (GraphDefinition.useContext.value as Range) context-type token A type of use context assigned to the graph definition GraphDefinition.useContext.code context-type-quantity composite A use context type and quantity- or range-based value assigned to the graph definition On GraphDefinition.useContext:   context-type: code   context-quantity: value.as(Quantity) | value.as(Range) context-type-value composite A use context type and value assigned to the graph definition On GraphDefinition.useContext:   context-type: code   context: value.as(CodeableConcept) date date The graph definition publication date GraphDefinition.date description string The description of the graph definition GraphDefinition.description jurisdiction token Intended jurisdiction for the graph definition GraphDefinition.jurisdiction name string Computationally friendly name of the graph definition GraphDefinition.name publisher string Name of the publisher of the graph definition GraphDefinition.publisher start token Type of resource at which the graph starts GraphDefinition.start status token The current status of the graph definition GraphDefinition.status url uri The uri that identifies the graph definition GraphDefinition.url version token The business version of the graph definition GraphDefinition.version