Path | Short | Definition | Comments |
---|---|---|---|
Definition of a graph of resources | 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. | ||
url | Canonical identifier for this graph definition, represented as a URI (globally unique) | An absolute URI that is used to identify this graph definition when it is referenced in a specification, model, design or an instance; also called its canonical identifier. This SHOULD be globally unique and SHOULD be a literal address at which at which an authoritative instance of this graph definition is (or will be) published. This URL can be the target of a canonical reference. It SHALL remain the same when the graph definition is stored on different servers. | Can be a urn:uuid: or a urn:oid: but real http: addresses are preferred. Multiple instances may share the same URL if they have a distinct version. The determination of when to create a new version of a resource (same url, new version) vs. defining a new artifact is up to the author. Considerations for making this decision are found in [Technical and Business Versions](resource.html#versions). In some cases, the resource can no longer be found at the stated url, but the url itself cannot change. Implementations can use the [meta.source](resource.html#meta) element to indicate where the current master source of the resource can be found. |
version | Business version of the graph definition | 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 sequence. | There may be different graph definition instances that have the same identifier but different versions. The version can be appended to the url in a reference to allow a reference to a particular business version of the graph definition with the format [url]|[version]. |
name | Name for this graph definition (computer friendly) | 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 generation. | The name is not expected to be globally unique. The name should be a simple alphanumeric type name to ensure that it is machine-processing friendly. |
status | draft | active | retired | unknown | The status of this graph definition. Enables tracking the life-cycle of the content. | Allows filtering of graph definitions that are appropriate for use versus not. |
experimental | For testing purposes, not real usage | 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. | Allows filtering of graph definitions that are appropriate for use versus not. |
date | Date last changed | The date (and optionally time) when the graph definition was published. The date must change 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 changes. | Note that this is not the same as the resource last-modified-date, since the resource may be a secondary representation of the graph definition. Additional specific dates may be added as extensions or be found by consulting Provenances associated with past versions of the resource. |
publisher | Name of the publisher (organization or individual) | The name of the organization or individual that published the graph definition. | Usually an organization but may be an individual. The publisher (or steward) of the graph definition is the organization or individual primarily responsible for the maintenance and upkeep of the graph definition. This is not necessarily the same individual or organization that developed and initially authored the content. The publisher is the primary point of contact for questions or issues with the graph definition. This item SHOULD be populated unless the information is available from context. |
contact | Contact details for the publisher | Contact details to assist a user in finding and communicating with the publisher. | May be a web site, an email address, a telephone number, etc. |
description | Natural language description of the graph definition | A free text natural language description of the graph definition from a consumer's perspective. | This description can be used to capture details such as why the graph definition was built, comments about misuse, instructions for clinical use and interpretation, literature references, examples from the paper world, etc. It is not a rendering of the graph definition as conveyed in the 'text' field of the resource itself. This item SHOULD be populated unless the information is available from context (e.g. the language of the graph definition is presumed to be the predominant language in the place the graph definition was created). |
useContext | The context that the content is intended to support | The content was developed with a focus and intent of supporting the contexts that are listed. These contexts may be general categories (gender, age, ...) or may be references to specific programs (insurance plans, studies, ...) and may be used to assist with indexing and searching for appropriate graph definition instances. | When multiple useContexts are specified, there is no expectation that all or any of the contexts apply. |
jurisdiction | Intended jurisdiction for graph definition (if applicable) | A legal or geographic region in which the graph definition is intended to be used. | It may be possible for the graph definition to be used in jurisdictions other than those for which it was originally designed or intended. |
purpose | Why this graph definition is defined | Explanation of why this graph definition is needed and why it has been designed as it has. | This element does not describe the usage of the graph definition. Instead, it provides traceability of ''why'' the resource is either needed or ''why'' it is defined as it is. This may be used to point to source materials or specifications that drove the structure of this graph definition. |
start | Type of resource at which the graph starts | The type of FHIR resource at which instances of this graph start. | |
profile | Profile on base resource | The profile that describes the use of the base resource. | The code does not include the '$' prefix that is always included in the URL when the operation is invoked. |
link | Links this graph makes rules about | Links this graph makes rules about. | |
link.id | Unique id for inter-element referencing | Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. | |
link.extension | Additional content defined by implementations | May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. | There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. |
link.modifierExtension | Extensions that cannot be ignored even if unrecognized | May be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself). | There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. |
link.path | Path in the resource that contains the link | A FHIR expression that identifies one of FHIR References to other resources. | The path expression cannot contain a resolve() function. If there is no path, the link is a reverse lookup, using target.params. If the path is "*" then this means all references in the resource. |
link.sliceName | Which slice (if profiled) | Which slice (if profiled). | |
link.min | Minimum occurrences for this link | Minimum occurrences for this link. | |
link.max | Maximum occurrences for this link | Maximum occurrences for this link. | |
link.description | Why this link is specified | Information about why this link is of interest in this graph definition. | |
link.target | Potential target for the link | Potential target for the link. | |
link.target.id | Unique id for inter-element referencing | Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. | |
link.target.extension | Additional content defined by implementations | May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. | There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. |
link.target.modifierExtension | Extensions that cannot be ignored even if unrecognized | May be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself). | There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. |
link.target.type | Type of resource this link refers to | Type of resource this link refers to. | |
link.target.params | Criteria for reverse lookup | A set of parameters to look up. | At least one of the parameters must have the value {ref} which identifies the focus resource. |
link.target.profile | Profile for the target resource | Profile for the target resource. | |
link.target.compartment | Compartment Consistency Rules | Compartment Consistency Rules. | |
link.target.compartment.id | Unique id for inter-element referencing | Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces. | |
link.target.compartment.extension | Additional content defined by implementations | May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. | There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. |
link.target.compartment.modifierExtension | Extensions that cannot be ignored even if unrecognized | May be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions. Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself). | There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone. |
link.target.compartment.use | condition | requirement | Defines 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 followed. | All conditional rules are evaluated; if they are true, then the rules are evaluated. |
link.target.compartment.code | Identifies the compartment | Identifies the compartment. | |
link.target.compartment.rule | identical | matching | different | custom | identical | matching | different | no-rule | custom. | |
link.target.compartment.expression | Custom rule, as a FHIRPath expression | Custom rule, as a FHIRPath expression. | |
link.target.compartment.description | Documentation for FHIRPath expression | Documentation for FHIRPath expression. | |
link.target.link | Additional links from target resource | Additional links from target resource. |
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:
There is a close relationship between Profiles and
GraphDefinitions
:
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.
The GraphDefinition resource can be used to:
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 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.
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:
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... --> <link> <!-- 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 --> <link> <path value="List.entry.item"/> <target> <type value="Resource"/> </target> </link> </target> </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:
<link> <path value="Composition.section.entry"/> <target> <type value="List"/> <compartment> <use value="requirement"/> <code value="Patient"/> <rule value="identical"/> </compartment> </target> <link> <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> </link> </target> </link>
Another useful approach is to walk any link * (e.g. wildcard support):
<link> <!-- follow all links that refers to a list --> <path value="*"/> <target> <type value="List"/> <!-- and inside this list, follow any references --> <link> <path value="*"/> <target> <type value="Resource"/> </target> </link> </target> </link>
or you can follow any links in any resource:
<link> <!-- follow all links --> <path value="*"/> <target> <type value="Resource"/> <!-- and inside the target, follow any links --> <link> <path value="*"/> <target> <type value="Resource"/> </target> </link> </target> </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> <!-- 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> </link>
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:
GraphDefinition.link.path
GraphDefinition.link.min
and max = GraphDefinition.link.max
GraphDefinition.link.description
The resource type rules statement consists of one or more of the following, separated by ;
characters:
[ResourceType] (profile)
where:
GraphDefinition.link.target.type
GraphDefinition.link.target.profile
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:
GraphDefinition.link.target.type
GraphDefinition.link.target.params
GraphDefinition.link.min
and max = GraphDefinition.link.max
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 } }
start | Type of resource at which the graph starts | GraphDefinition.start |