Current Build

5.11 Resource GraphDefinition - Content

FHIR Infrastructure Work GroupMaturity Level: 0 DraftCompartments: 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 GraphRelationship 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.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. GraphDefinition DomainResourceDefinition of an graph of resources
Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... url Σ0..1uriLogical URI to reference this graph definition (globally unique)
... version Σ0..1stringBusiness version of the graph definition
... name Σ1..1stringName for this graph definition (computer friendly)
... status ?!Σ1..1codedraft | active | retired | unknown
PublicationStatus (Required)
... experimental ?!Σ0..1booleanFor testing purposes, not real usage
... date Σ0..1dateTimeDate this was last changed
... publisher Σ0..1stringName of the publisher (organization or individual)
... contact Σ0..*ContactDetailContact details for the publisher
... description 0..1markdownNatural language description of the graph definition
... useContext Σ0..*UsageContextContext the content is intended to support
... jurisdiction Σ0..*CodeableConceptIntended jurisdiction for graph definition (if applicable)
Jurisdiction ValueSet (Extensible)
... purpose 0..1markdownWhy this graph definition is defined
... start 1..1codeType of resource at which the graph starts
ResourceType (Required)
... profile 0..1uriProfile on base resource
... link 0..*BackboneElementLinks this graph makes rules about
.... path 0..1stringPath in the resource that contains the link
.... sliceName 0..1stringWhich slice (if profiled)
.... min 0..1integerMinimum occurrences for this link
.... max 0..1stringMaximum occurrences for this link
.... description 0..1stringWhy this link is specified
.... target 0..*BackboneElementPotential target for the link
..... type 1..1codeType of resource this link refers to
ResourceType (Required)
..... params 0..1stringCriteria for reverse lookup
..... profile 0..1uriProfile for the target resource
..... compartment 0..*BackboneElementCompartment Consistency Rules
...... use 1..1codecondition | requirement
GraphCompartmentUse (Required)
...... code 1..1codeIdentifies the compartment
CompartmentType (Required)
...... rule 1..1codeidentical | matching | different | custom
GraphCompartmentRule (Required)
...... expression 0..1stringCustom rule, as a FHIRPath expression
...... description 0..1stringDocumentation for FHIRPath expression
..... link 0..*see linkAdditional links from target resource

doco Documentation for this format

UML Diagram (Legend)

GraphDefinition (DomainResource)An absolute URI that is used to identify this graph definition when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this graph definition is (or will be) published. The URL SHOULD include the major version of the graph definition. For more information see [Technical and Business Versions](resource.html#versions)url : uri [0..1]The identifier that is used to identify this version of the graph definition when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the graph definition author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequenceversion : string [0..1]A natural language name identifying the graph definition. This name should be usable as an identifier for the module by machine processing applications such as code generationname : string [1..1]The status of this graph definition. Enables tracking the life-cycle of the content (this element modifies the meaning of other elements)status : code [1..1] « The lifecycle status of a Value Set or Concept Map. (Strength=Required)PublicationStatus! »A boolean value to indicate that this graph definition is authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage (this element modifies the meaning of other elements)experimental : boolean [0..1]The date (and optionally time) when the graph definition was published. The date must change if and when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the graph definition changesdate : dateTime [0..1]The name of the individual or organization that published the graph definitionpublisher : string [0..1]Contact details to assist a user in finding and communicating with the publishercontact : ContactDetail [0..*]A free text natural language description of the graph definition from a consumer's perspectivedescription : markdown [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching for appropriate graph definition instancesuseContext : UsageContext [0..*]A legal or geographic region in which the graph definition is intended to be usedjurisdiction : CodeableConcept [0..*] « Countries and regions within which this artifact is targeted for use (Strength=Extensible)Jurisdiction ValueSet+ »Explaination of why this graph definition is needed and why it has been designed as it haspurpose : markdown [0..1]The type of FHIR resource at which instances of this graph startstart : code [1..1] « One of the resource types defined as part of FHIR. (Strength=Required)ResourceType! »The profile that describes the use of the base resourceprofile : uri [0..1]LinkA FHIR expression that identifies one of FHIR References to other resourcespath : string [0..1]Which slice (if profiled)sliceName : string [0..1]Minimum occurrences for this linkmin : integer [0..1]Maximum occurrences for this linkmax : string [0..1]Information about why this link is of interest in this graph definitiondescription : string [0..1]TargetType of resource this link refers totype : code [1..1] « One of the resource types defined as part of FHIR. (Strength=Required)ResourceType! »A set of parameters to look upparams : string [0..1]Profile for the target resourceprofile : uri [0..1]CompartmentDefines how the compartment rule is used - whether it it is used to test whether resources are subject to the rule, or whether it is a rule that must be followeduse : code [1..1] « Defines how a compartment rule is used (Strength=Required)GraphCompartmentUse! »Identifies the compartmentcode : code [1..1] « Identifies a compartment (Strength=Required)CompartmentType! »identical | matching | different | no-rule | customrule : code [1..1] « How a compartment must be linked (Strength=Required)GraphCompartmentRule! »Custom rule, as a FHIRPath expressionexpression : string [0..1]Documentation for FHIRPath expressiondescription : string [0..1]Compartment Consistency Rulescompartment[0..*]Additional links from target resourcelink[0..*]Potential target for the linktarget[0..*]Links this graph makes rules aboutlink[0..*]

XML Template

<GraphDefinition xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 0..1 Logical URI to reference this graph definition (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 this was 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><!-- 0..* UsageContext Context 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 value="[uri]"/><!-- 0..1 Profile on base resource -->
 <link>  <!-- 0..* Links this graph makes rules about -->
  <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 value="[uri]"/><!-- 0..1 Profile for the target resource -->
   <compartment>  <!-- 0..* Compartment Consistency Rules -->
    <use value="[code]"/><!-- 1..1 condition | requirement -->
    <code value="[code]"/><!-- 1..1 Identifies the compartment -->
    <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>
   <link><!-- 0..* Content as for GraphDefinition.link Additional links from target resource --></link>
  </target>
 </link>
</GraphDefinition>

JSON Template

{doco
  "resourceType" : "GraphDefinition",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // Logical URI to reference this graph definition (globally unique)
  "version" : "<string>", // Business version of the graph definition
  "name" : "<string>", // 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 this was 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 }], // Context 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" : "<uri>", // Profile on base resource
  "link" : [{ // Links this graph makes rules about
    "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" : "<uri>", // Profile for the target resource
      "compartment" : [{ // Compartment Consistency Rules
        "use" : "<code>", // R!  condition | requirement
        "code" : "<code>", // R!  Identifies the compartment
        "rule" : "<code>", // R!  identical | matching | different | custom
        "expression" : "<string>", // Custom rule, as a FHIRPath expression
        "description" : "<string>" // Documentation for FHIRPath expression
      }],
      "link" : [{ Content as for GraphDefinition.link }] // Additional links from target resource
    }]
  }]
}

Turtle Template

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


[ 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:GraphDefinition.url [ uri ]; # 0..1 Logical URI to reference this graph definition (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:GraphDefinition.experimental [ boolean ]; # 0..1 For testing purposes, not real usage
  fhir:GraphDefinition.date [ dateTime ]; # 0..1 Date this was 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:GraphDefinition.useContext [ UsageContext ], ... ; # 0..* Context 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 [ uri ]; # 0..1 Profile on base resource
  fhir:GraphDefinition.link [ # 0..* Links this graph makes rules about
    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.min [ integer ]; # 0..1 Minimum occurrences for this link
    fhir:GraphDefinition.link.max [ string ]; # 0..1 Maximum occurrences for this link
    fhir:GraphDefinition.link.description [ string ]; # 0..1 Why this link is specified
    fhir:GraphDefinition.link.target [ # 0..* Potential target for the link
      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 [ uri ]; # 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:GraphDefinition.link.target.compartment.code [ code ]; # 1..1 Identifies the compartment
        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
      ], ...;
      fhir:GraphDefinition.link.target.link [ See GraphDefinition.link ], ... ; # 0..* Additional links from target resource
    ], ...;
  ], ...;
]

Changes since DSTU2

This resource did not exist in Release 2

This analysis is available as XML or JSON.

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. GraphDefinition DomainResourceDefinition of an graph of resources
Elements defined in Ancestors: id, meta, implicitRules, language, text, contained, extension, modifierExtension
... url Σ0..1uriLogical URI to reference this graph definition (globally unique)
... version Σ0..1stringBusiness version of the graph definition
... name Σ1..1stringName for this graph definition (computer friendly)
... status ?!Σ1..1codedraft | active | retired | unknown
PublicationStatus (Required)
... experimental ?!Σ0..1booleanFor testing purposes, not real usage
... date Σ0..1dateTimeDate this was last changed
... publisher Σ0..1stringName of the publisher (organization or individual)
... contact Σ0..*ContactDetailContact details for the publisher
... description 0..1markdownNatural language description of the graph definition
... useContext Σ0..*UsageContextContext the content is intended to support
... jurisdiction Σ0..*CodeableConceptIntended jurisdiction for graph definition (if applicable)
Jurisdiction ValueSet (Extensible)
... purpose 0..1markdownWhy this graph definition is defined
... start 1..1codeType of resource at which the graph starts
ResourceType (Required)
... profile 0..1uriProfile on base resource
... link 0..*BackboneElementLinks this graph makes rules about
.... path 0..1stringPath in the resource that contains the link
.... sliceName 0..1stringWhich slice (if profiled)
.... min 0..1integerMinimum occurrences for this link
.... max 0..1stringMaximum occurrences for this link
.... description 0..1stringWhy this link is specified
.... target 0..*BackboneElementPotential target for the link
..... type 1..1codeType of resource this link refers to
ResourceType (Required)
..... params 0..1stringCriteria for reverse lookup
..... profile 0..1uriProfile for the target resource
..... compartment 0..*BackboneElementCompartment Consistency Rules
...... use 1..1codecondition | requirement
GraphCompartmentUse (Required)
...... code 1..1codeIdentifies the compartment
CompartmentType (Required)
...... rule 1..1codeidentical | matching | different | custom
GraphCompartmentRule (Required)
...... expression 0..1stringCustom rule, as a FHIRPath expression
...... description 0..1stringDocumentation for FHIRPath expression
..... link 0..*see linkAdditional links from target resource

doco Documentation for this format

UML Diagram (Legend)

GraphDefinition (DomainResource)An absolute URI that is used to identify this graph definition when it is referenced in a specification, model, design or an instance. This SHALL be a URL, SHOULD be globally unique, and SHOULD be an address at which this graph definition is (or will be) published. The URL SHOULD include the major version of the graph definition. For more information see [Technical and Business Versions](resource.html#versions)url : uri [0..1]The identifier that is used to identify this version of the graph definition when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the graph definition author and is not expected to be globally unique. For example, it might be a timestamp (e.g. yyyymmdd) if a managed version is not available. There is also no expectation that versions can be placed in a lexicographical sequenceversion : string [0..1]A natural language name identifying the graph definition. This name should be usable as an identifier for the module by machine processing applications such as code generationname : string [1..1]The status of this graph definition. Enables tracking the life-cycle of the content (this element modifies the meaning of other elements)status : code [1..1] « The lifecycle status of a Value Set or Concept Map. (Strength=Required)PublicationStatus! »A boolean value to indicate that this graph definition is authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usage (this element modifies the meaning of other elements)experimental : boolean [0..1]The date (and optionally time) when the graph definition was published. The date must change if and when the business version changes and it must change if the status code changes. In addition, it should change when the substantive content of the graph definition changesdate : dateTime [0..1]The name of the individual or organization that published the graph definitionpublisher : string [0..1]Contact details to assist a user in finding and communicating with the publishercontact : ContactDetail [0..*]A free text natural language description of the graph definition from a consumer's perspectivedescription : markdown [0..1]The content was developed with a focus and intent of supporting the contexts that are listed. These terms may be used to assist with indexing and searching for appropriate graph definition instancesuseContext : UsageContext [0..*]A legal or geographic region in which the graph definition is intended to be usedjurisdiction : CodeableConcept [0..*] « Countries and regions within which this artifact is targeted for use (Strength=Extensible)Jurisdiction ValueSet+ »Explaination of why this graph definition is needed and why it has been designed as it haspurpose : markdown [0..1]The type of FHIR resource at which instances of this graph startstart : code [1..1] « One of the resource types defined as part of FHIR. (Strength=Required)ResourceType! »The profile that describes the use of the base resourceprofile : uri [0..1]LinkA FHIR expression that identifies one of FHIR References to other resourcespath : string [0..1]Which slice (if profiled)sliceName : string [0..1]Minimum occurrences for this linkmin : integer [0..1]Maximum occurrences for this linkmax : string [0..1]Information about why this link is of interest in this graph definitiondescription : string [0..1]TargetType of resource this link refers totype : code [1..1] « One of the resource types defined as part of FHIR. (Strength=Required)ResourceType! »A set of parameters to look upparams : string [0..1]Profile for the target resourceprofile : uri [0..1]CompartmentDefines how the compartment rule is used - whether it it is used to test whether resources are subject to the rule, or whether it is a rule that must be followeduse : code [1..1] « Defines how a compartment rule is used (Strength=Required)GraphCompartmentUse! »Identifies the compartmentcode : code [1..1] « Identifies a compartment (Strength=Required)CompartmentType! »identical | matching | different | no-rule | customrule : code [1..1] « How a compartment must be linked (Strength=Required)GraphCompartmentRule! »Custom rule, as a FHIRPath expressionexpression : string [0..1]Documentation for FHIRPath expressiondescription : string [0..1]Compartment Consistency Rulescompartment[0..*]Additional links from target resourcelink[0..*]Potential target for the linktarget[0..*]Links this graph makes rules aboutlink[0..*]

XML Template

<GraphDefinition xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 0..1 Logical URI to reference this graph definition (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 this was 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><!-- 0..* UsageContext Context 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 value="[uri]"/><!-- 0..1 Profile on base resource -->
 <link>  <!-- 0..* Links this graph makes rules about -->
  <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 value="[uri]"/><!-- 0..1 Profile for the target resource -->
   <compartment>  <!-- 0..* Compartment Consistency Rules -->
    <use value="[code]"/><!-- 1..1 condition | requirement -->
    <code value="[code]"/><!-- 1..1 Identifies the compartment -->
    <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>
   <link><!-- 0..* Content as for GraphDefinition.link Additional links from target resource --></link>
  </target>
 </link>
</GraphDefinition>

JSON Template

{doco
  "resourceType" : "GraphDefinition",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // Logical URI to reference this graph definition (globally unique)
  "version" : "<string>", // Business version of the graph definition
  "name" : "<string>", // 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 this was 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 }], // Context 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" : "<uri>", // Profile on base resource
  "link" : [{ // Links this graph makes rules about
    "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" : "<uri>", // Profile for the target resource
      "compartment" : [{ // Compartment Consistency Rules
        "use" : "<code>", // R!  condition | requirement
        "code" : "<code>", // R!  Identifies the compartment
        "rule" : "<code>", // R!  identical | matching | different | custom
        "expression" : "<string>", // Custom rule, as a FHIRPath expression
        "description" : "<string>" // Documentation for FHIRPath expression
      }],
      "link" : [{ Content as for GraphDefinition.link }] // Additional links from target resource
    }]
  }]
}

Turtle Template

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


[ 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:GraphDefinition.url [ uri ]; # 0..1 Logical URI to reference this graph definition (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:GraphDefinition.experimental [ boolean ]; # 0..1 For testing purposes, not real usage
  fhir:GraphDefinition.date [ dateTime ]; # 0..1 Date this was 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:GraphDefinition.useContext [ UsageContext ], ... ; # 0..* Context 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 [ uri ]; # 0..1 Profile on base resource
  fhir:GraphDefinition.link [ # 0..* Links this graph makes rules about
    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.min [ integer ]; # 0..1 Minimum occurrences for this link
    fhir:GraphDefinition.link.max [ string ]; # 0..1 Maximum occurrences for this link
    fhir:GraphDefinition.link.description [ string ]; # 0..1 Why this link is specified
    fhir:GraphDefinition.link.target [ # 0..* Potential target for the link
      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 [ uri ]; # 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:GraphDefinition.link.target.compartment.code [ code ]; # 1..1 Identifies the compartment
        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
      ], ...;
      fhir:GraphDefinition.link.target.link [ See GraphDefinition.link ], ... ; # 0..* Additional links from target resource
    ], ...;
  ], ...;
]

Changes since DSTU2

This resource did not exist in Release 2

This analysis is available as XML or JSON.

 

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

PathDefinitionTypeReference
GraphDefinition.status The lifecycle status of a Value Set or Concept Map.RequiredPublicationStatus
GraphDefinition.jurisdiction Countries and regions within which this artifact is targeted for useExtensibleJurisdiction ValueSet
GraphDefinition.start
GraphDefinition.link.target.type
One of the resource types defined as part of FHIR.RequiredResource Types
GraphDefinition.link.target.compartment.use Defines how a compartment rule is usedRequiredGraphCompartmentUse
GraphDefinition.link.target.compartment.code Identifies a compartmentRequiredCompartmentType
GraphDefinition.link.target.compartment.rule How a compartment must be linkedRequiredGraphCompartmentRule

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 summarise 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 the search:

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

This is a requset 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 the text representation defined below:

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

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:

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?

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 parantheses (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 preform 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:

  • path = GraphDefinition.link.path
  • 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:

  • ResourceType = GraphDefinition.link.target.type
  • 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:

  • ResourceType = GraphDefinition.link.target.type
  • params = GraphDefinition.link.target.params
  • 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 it's form, is irrelevant. For the purposes of clarity, the content is laid ot on different lines, but this is not required.

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.

NameTypeDescriptionExpressionIn Common
datedateThe graph definition publication dateGraphDefinition.date
descriptionstringThe description of the graph definitionGraphDefinition.description
jurisdictiontokenIntended jurisdiction for the graph definitionGraphDefinition.jurisdiction
namestringComputationally friendly name of the graph definitionGraphDefinition.name
publisherstringName of the publisher of the graph definitionGraphDefinition.publisher
starttokenType of resource at which the graph startsGraphDefinition.start
statustokenThe current status of the graph definitionGraphDefinition.status
urluriThe uri that identifies the graph definitionGraphDefinition.url
versiontokenThe business version of the graph definitionGraphDefinition.version