Section: 6

exchange-module.html

Work Group Standards Status:Informative

FHIR Exchange Module

Introduction / Index

FHIR is designed as an interface specification - it specifies the content of the data exchanged between healthcare applications, and how the exchange is implemented and managed. FHIR defines the following methods for exchanging data between systems:

Each of these approaches can be used to exchange information, and each has its own strengths and weaknesses and applicability. Note that applications are allowed to use any other method to exchange resources; the methods described in this specification are the common methods that are used enough to justify the effort to describe or standardize their use.

RESTful API

Most implementers focus on RESTful API. This is a client/server API designed to follow the principles of RESTful design for Create, Read, Update and Delete operations, along with Search and Execute (Operations) support.

The RESTful API is a general purpose interface that can be used to push and pull data between systems. Which is appropriate depends on architecture and deployment considerations. The RESTful API also supports Asynchronous Use and GraphQL.

Messaging

In addition to the RESTful API, a messaging exchange framework is documented, which supports exchange between systems by sending routed messages from system to system. This exchange can be implemented on the RESTful API, or using some other messaging technology.

Implementers should note that the messaging framework is not provided to fill any functional deficiency in the RESTful API (or vice versa), these frameworks are provided to allow implementers to choose how to exchange content based on their own architectural and deployment considerations. Messaging may be more suitable for exchange between disparate organizations with low levels of process integration and/or trust.

Documents

This specification also defines a document based exchange framework, where content to be exchanged is wrapped by a Composition that provides the context of the content, and that has a fixed presentation for a human reader. The document framework is provided to help with computer-assisted human to human communication uses - which are not uncommon in healthcare.

Typically, exchanging documents is associated with exchanging clinical information across clinical governance borders, while data based exchange using the RESTful API is appropriate within where there are well established clinical governance arrangements.

Services / SOA

In addition, this specification describes the use of FHIR in a services framework(e.g. a SOA). Note that any use of any of the above approaches in production is a 'service' by some or many definitions. The services description provides context regarding the use of FHIR (and particularly the RESTful API) in a wider enterprise architecture.

Database / Persistent Store

Another way to make use of the resources defined by FHIR is to store them natively in a database or persistent store, where different applications or modules write and read the resources as part of their implementation. Using resources in this fashion is described here.

Security and Privacy

All forms of data exchange should be appropriately secured. This requires the following:

This subject is described further in the Security Page.

With regard to the RESTful API, implementers should always consider the Smart App Launch protocol as part of the overall secure API approach

Developmental Roadmap

RESTful API This is stable and currently being balloted as Normative. No breaking changes are expected. No significant development is planned, but HL7 will continue to respond to user experience
Messaging Messaging has only be implemented in a few projects; some of the infrastructure has not yet been used in production. It is not clear whether significant development will be needed or appropriate
Documents Documents have mostly only been used in prototype projects, though there is considerable impetus around implementation at this time. No significant development is planned, but HL7 will continue to respond to user experience
Services At this point in time, it's not clear whether further work is required or appropriate in terms of service orientated architecture / enterprise integration. HL7 will continue to monitor implementer experience and feedback
Database / Persistent Storage This is a new area with considerable action at this time, and many production implementations, though RDF itself is not getting much use. At this time, HL7 is monitoring implementer experience and feedback to see whether additional standardization is required

Note to balloters: There's some interest in standardizing the use of ProtocolBuffers directly in the specification itself (basis). Ballot comments are welcome.


extensibility-definitions.html

Extension - Detailed Descriptions

Maturity Level: NormativeStandards Status:Normative

extensibility-examples.html

Extensibility Examples

Maturity Level: N/AStandards Status:Informative

In order to use an extension, there is a three-step process:

  1. Define the extension
  2. Register the extension
  3. Use it in the instance

This page contains examples of how this process executes.

Patient Consent for Record Sharing

The basic patient resource contains no information relating to patient consent, and/or the policy under which the patient consents to their registration details. A social web provider of personal healthcare record (PHR) services might be obliged to keep track of the particular policy under which a patient has created their relationship with the PHR provider, and share this with their participants via their FHIR API. If they wish, they can extend the patient resource to represent the patient's participation agreement. Note that other approaches to this problem are possible and preferred, but this example suffices to demonstrate the extension process.

For the purposes of this example, we assume that the patient agrees to a participation policy as part of their sign up, and that as the provider has to change their policy, they ask patients to agree to new participation details. Each participation agreement has a URI by which it is identified, and the patient resource will carry this URI for each policy agreement that the patient has agreed to.

Define the Extension

For each extension, the first thing to do is to fill out the definitional properties of the extension:

Code"participation-agreement"
ContextThis extension is used in the patient resource
Short DefnAgreed agreement/policy
DefinitionA URI that identifies a participation agreement/policy to which the patient has agreed
CommentURI is a literal reference to agreement text (html)
Cardinality1..* (patient cannot participate without at least one agreement)
Typeuri
Invariantsno Invariants
is ModifierNo (The participation agreements do not affect that interpretation of the elements of the patient, though they will likely influence how the system interacts with the patient)
Binding(No binding - not a coded value)

Write the Definition of the Extension

From this table, we can build a formal extension definition. In this case, it looks like this:

<StructureDefinition xmlns="http://hl7.org/fhir">
  <url value="http://example.org/fhir/StructureDefinition/participation-agreement"/>
  <name value="Example Extension Definition"/>
  <!-- snip other metadata -->
  <kind value="complex-type"/>
  <context>
    <type value="element"/>
    <expression value="Patient"/>
  </context>
  <type value="Extension"/>
  <baseDefinition value="http://hl7.org.fhir/StructureDefinition/Extension"/>
  <derivation value="constraint"/>

  <differential>
    <element>
      <path value="Extension"/>
      <short value="Agreed agreement/policy"/>
      <definition value="A URI that identifies a participation agreement/policy
        to which the patient has agreed"/>
      <comment value="URI is a literal reference to agreement text (html).
        Systems SHALL conform to the policies as indicated.
        For further information, see the partnership agreement..."/>
      <mustSupport value="true"/>
      <isModifier value="false"/>
    </element>
    <element>
      <path value="Extension.url"/>
      <fixedUri value="http://example.org/fhir/StructureDefinition/participation-agreement"/>
    </element>
    <element>
      <path value="Extension.valueUri"/>
      <short value="The URI value"/>
      <min value="1"/>
      <max value="*"/>
      <type>
         <code value="uri"/>
      </type>
      <mustSupport value="true"/>
    </element>
  </differential>
</StructureDefinition>

Note that usually one would build the actual profile using a tool. This example was built by hand for this example.

Register the Extension

This means the profile shown above that defines the extension is placed on the web somewhere. By preference, it will be hosted at a FHIR Profile endpoint, and the best location of all is the HL7 FHIR Registry.

For this example, we assume that it has been uploaded to the PHR provider's own website at http://example.org/phr/documents/fhir/extensions.

Use it in the instance

To use the extension in an instance, the extension is placed in the root of the resource, because that was the declared context for the extension. Note that the URL of the extension refers to the registered location.

<Patient xmlns="http://hl7.org/fhir">
  <extension url="http://example.org/phr/documents/fhir/extensions/participation-agreement" >
    <valueUri value="http://example.org/phr/documents/patient/general/v1"/>
  </extension>
  <!-- ... -->
</Patient>

Using it in a Patient Profile

The extension definition above simply defines the extension "participation-agreement", and says that it is used with patient. But the profile above doesn't say that the server actually uses it. For the PHR provider to indicate that all Patient resources will use this resource, a StructureDefinition on the patient resource is used:

<StructureDefinition xmlns="http://hl7.org/fhir">
  <id value="patient-profile"/>
  <!-- snip other metadata, narrative -->
  <differential>

    <!-- first, the patient root element
      - can be copy/paste from the base patient profile -->
    <element>
      <path value="Patient"/>
      <!-- snip definition -->
    </element>

    <!-- now, the general definition for extensions
      - can be copied/pasted from the base patient profile,
      with changes for slicing  -->
    <element>
      <path value="Patient.extension"/>
      <!-- we're going to slice the extension element, and
        one of the extensions is one we have defined -->
      <slicing>
        <!-- extension is always sliced on url -->
        <discriminator>
          <type value="value"/>
          <path value="url"/>
        </discriminator>
        <!-- we don't care what the order of any extensions is -->
        <ordered value="false"/>
        <!-- Other extensions are allowed in addition to this one -->
        <rules value="open"/>
      </slicing>
      <!-- snip definition -->
    </element>

    <!-- now, the slice that contains our extension -->
    <element>
      <path value="Patient.extension"/>
      <sliceName value="agreement"/>
      <!-- clone information from the extension definition.
        duplicative, but this duplication makes it simpler overall -->
      <short value="Agreed agreement/policy"/>
      <definition value="A URI that identifies a participation agreement/policy
      to which the patient has agreed"/>
      <!--  min has to be 1, since the extension itself has min = 1 -->
      <min value="1"/>
      <max value="*"/>
      <type>
        <!-- obviously it has to be an extension -->
        <code value="Extension"/>
        <!-- and here is the link to the extension definition:
          this extension has to conform to the rules laid down in its definition -->
        <profile value="http://example.org/phr/documents/fhir/StructureDefinition/participation-agreement"/>
      </type>
      <isModifier value="false"/>
    </element>

  <!-- snip the rest of the profile -->

  </differential>
</StructureDefinition>

Note - this step is optional.

Patient Name Parts

ISO 21090 (Healthcare Data Types) defines a concept called a "name part qualifier" that contains extra information about how a particular name part should be used or interpreted. In practice, this field is used rarely except in particular cultural contexts, where certain part qualifiers are used as a matter of practice. Following the FHIR design policy, such a field is not included in the overall definition of the core name data type, instead is it added as an extension.

In practice, for cases such as these in ISO 21090, HL7 defines common extensions, and these are defined either in this specification, or in the FHIR registry.

Define the Extension

For each extension, the first thing to do is to fill out the definitional properties of the extension:

Code"name-qualifier"
ContextThis extension can be used anywhere a HumanName.part appears
Short Defn(one of the codes) LS | AC | NB | PR | HON | BR | AD | SP | MID | CL | IN
DefinitionA set of codes each of which specifies a certain subcategory of the name part in addition to the main name part type
CommentUsed to indicate additional information about the name part and how it should be used
Cardinality0..* (this is always optional, but more than one can be used if required)
Typecode
InvariantsN/A
Is ModifierNo (Qualifiers do not change the fact that the part is a given or family name)
RIM MappingENXP.qualifier
v2 MappingN/A
BindingBound to a subset of the codes specified for EntityNamePartQualifierR2 in ISO 21090

Not all the codes of the EntityNamePartQualifierR2 are required in this context, because prefix and suffix are explicitly part of the name types. Rather than simply refer to the OID for EntityNamePartQualifierR2 (2.16.840.1.113883.5.1122), in this case we enumerate the available codes, and set the type of the extension to code. The type of "code" is only allowed if the profile itself defines the codes that can be used. Here is a table of the codes (see the EntityNamePartQualifierR2 reference for the full definitions):

LSLegal status For organizations, a suffix...
ACAcademicIndicates that a prefix like "D...
NBNobilityIn Europe and Asia, there are s...
PRProfessionalPrimarily in the British Im...
HONHonorificAn honorific such as 'The Rig...
BRBirthA name that a person was given at ...
ADAcquiredA name part a person acquired. ...
SPSpouseThe name assumed from the partner...
MIDMiddle NameIndicates that the name par...
CLCall meCall me is used to indicate which...
INInitialIndicates that a name part is ju...

This is all then represented formally in a profile. Such profiles do not need to include resource constraint statements; instead, they include just extension declarations and their associated bindings. In this case, the definition looks like this:

<StructureDefinition xmlns="http://hl7.org/fhir">
  <url value="http://hl7.org/fhir/StructureDefinition/iso21090-EN-qualifier"/>
  <name value="Iso21090NameQualifier"/>
  <title value="iso-21090 Name Qualifier"/>
  <!-- snip other metadata, including definition of RIM Mapping -->
  <kind value="complex-type"/>
  <context>
    <type value="element"/>
    <expression value="HumanName.given"/>
  </context>    
  <context>
    <type value="element"/>
    <expression value="HumanName.prefix"/>
  </context>    
  <context>
    <type value="element"/>
    <expression value="HumanName.family"/>
  </context>    
  <context>
    <type value="element"/>
    <expression value="HumanName.suffix"/>
  </context>    
  <type value="Extension"/>
  <baseDefinition value="http://hl7.org.fhir/StructureDefinition/Extension"/>
  <derivation value="constraint"/>
  <differential>
    <element>
      <path value="Extension"/>
      <short value="LS | AC | NB | PR | HON | BR | AD | SP | MID | CL | IN"/>
      <definition value="A set of codes each of which specifies a certain subcategory
          of the name part in addition to the main name part type"/>
      <comment value="Used to indicate additional information about the
             name part and how it should be used"/>
      <mustSupport value="false"/>
      <isModifier value="false"/>
    </element>
    <element>
      <path value="Extension.url"/>
      <fixedUri value="http://hl7.org/fhir/StructureDefinition/iso21090-EN-qualifier"/>
    </element>
    <element>
      <path value="Extension.value"/>
      <short value="LS | AC | NB | PR | HON | BR | AD | SP | MID | CL | IN"/>
      <min value="0"/>
      <max value="*"/>
      <type>
         <code value="code"/>
      </type>
      <binding>
        <strength value="required"/>
        <description value="A set of codes each of which specifies a certain subcategory
            of the name part in addition to the main name part type"/>
        <valueSet value="http://hl7.org/fhir/ValueSet/name-part-qualifier"/>
      </binding>
      <mapping>
         <identity value="RIM"/>
         <map value="ENXP.qualifier"/>
      </mapping>
    </element>
  </differential>
</StructureDefinition>

Note that usually one would build the actual profile using a tool. This example was built from a spreadsheet definition by the FHIR build tooling.

Register the Extension

For this example, it is registered at http://hl7.org/fhir/StructureDefinition/iso21090-EN-qualifier. This is the URL that will appear in the definition element when the extension is used.

Use it in the instance

To use the extension in an instance, the extension is nested within the attribute that is extended. Note that the URL of the extension refers to the registered location.

<name>
  <use value="official"/>
  <given value="Östlund">
     <extension url="http://hl7.org/fhir/StructureDefinition/iso21090-EN-qualifier" >
        <valueCode value="MID"/>
     </extension>
  </given>
</name>

This particular example is a Scandinavian mellannamn. See Datatypes examples for additional examples.

Complex Extension: Patient Clinical Trial

Defining complex extensions is a little different. They have the same metadata - context, etc. - but differ in the internal structure. As an example, consider enrolling a patient in a clinical trial. There are 3 data items to collect:

Code Name Cardinality Type Content
NCT Clinical Trial number 1..1 string The format for the US ClinicalTrials.gov registry number is "NCT" followed by an 8-digit number, e.g.: NCT00000419
period trialPeriod 0..1 Period The start and end times of the participation of this patient in the clinical trial
reason reason enrolled 0..1 CodableConcept Indication or reason that the patient is part of this trial

NOTE: This extension is included for example purposes only. In most cases, participation in clinical trials would be handled using the ResearchStudy resource, possibly referenced via the workflow-researchstudy extension.

Like simple extensions, the first thing to do is to assign a URI to the extension, e.g.: http://example.org/fhir/StructureDefinition/patient-clinicalTrial.

Internally, in the extension, the maximum cardinality of the value[x] element is set to 0 since it will not (and cannot) be used. The Extension.extension element is sliced by URL, and 3 slices are defined, each with a fixed relative URI which is the code from the table above. The relevant parts of the definition of this extension are as follows:

<StructureDefinition xmlns="http://hl7.org/fhir">
  <!-- metadata - setting up the base definition -->
  <url value="http://example.org/fhir/StructureDefinition/patient-clinicalTrial"/>
  <name value="ClinicalTrialParticipation"/>
  <title value="The patient's participation in clinical trials"/>
  <context>
    <type value="element"/>
    <expression value="Patient"/>
  </context>
  <type value="Extension"/>
  <baseDefinition value="http://hl7.org.fhir/StructureDefinition/Extension"/>
  <derivation value="constraint"/>
  <snapshot>
    <element>
      <path value="Extension"/>
      <!-- etc.-->
    </element>

    <!-- set up the slicing -->
    <element>
      <path value="Extension.extension"/>
      <slicing>
        <discriminator>
          <type value="value"/>
          <path value="url"/>
        </discriminator>
        <ordered value="true"/>
        <rules value="openAtEnd"/>
      </slicing>
    </element>

    <!-- first slice, NCT -->
    <element>
      <path value="Extension.extension"/>
      <sliceName value="NCT"/>
      <short value="National Clinical Trial number"/>
      <min value="1"/>
      <max value="1"/>
    </element>
    <element>
      <path value="Extension.extension.extension"/>
      <min value="0"/>
      <max value="0"/> <!-- not allowed to be used -->
    </element>
    <element>
      <path value="Extension.extension.url"/>
      <min value="1"/>
      <max value="1"/>
      <fixedUri value="NCT"/>
    </element>
    <element>
      <path value="Extension.extension.valueString"/>
      <min value="1"/>
      <max value="1"/>
      <type>
        <code value="string"/>
      </type>
    </element>

    <!-- second slice, period -->
    <element>
      <path value="Extension.extension"/>
      <sliceName value="period"/>
      <short value="The period of participation in the clinical trial"/>
      <min value="0"/>
      <max value="1"/>
    </element>
    </element>
    <element>
      <path value="Extension.extension.extension"/>
      <min value="0"/>
      <max value="0"/>
    </element>
    <element>
      <path value="Extension.extension.url"/>
      <min value="1"/>
      <fixedUri value="period"/>
    </element>
    <element>
      <path value="Extension.extension.valuePeriod"/>
      <type>
        <code value="Period"/>
      </type>
    </element>

    <!-- third slice, reason -->
    <element>
      <path value="Extension.extension"/>
      <sliceName value="reason"/>
      <short value="The reason for participation in the clinical trial"/>
      <min value="0"/>
      <max value="1"/>
    </element>
    <element>
      <path value="Extension.extension.extension"/>
      <min value="0"/>
      <max value="0"/>
    </element>
    <element>
      <path value="Extension.extension.url"/>
      <min value="1"/>
      <fixedUri value="reason"/>
    </element>
    <element>
      <path value="Extension.extension.valueCodeableConcept"/>
      <type>
        <code value="CodeableConcept"/>
      </type>
    </element>

    <!-- last (for order reasons): the fixed URI -->
    <element>
      <path value="Extension.url"/>
      <fixedUri value="http://example.org/fhir/StructureDefinition/patient-clinicalTrial"/>
    </element>
    <!-- and no value in the root -->
    <element>
      <path value="Extension.value[x]"/>
      <min value="0"/>
      <max value="0"/>
    </element>
  </snapshot>
</StructureDefinition>

Use it in the instance

With complex extensions, only the first URL is an absolute URL:

<Patient xmlns="http://hl7.org/fhir">
  <extension url="http://example.org/fhir/StructureDefinition/patient-clinicalTrial" >
    <extension url="NCT" >
      <valueString value="NCT00000419"/>
    </extension>
    <extension url="period" >
      <valuePeriod>
        <start value="200140105"/>
        <end value="20120105"/>
      </valuePeriod>
    </extension>
    <extension url="reason" >
      <valueCodeableConcept>
        <text value="healthy-volunteer"/>
      </valueCodeableConcept>
    </extension>
  </extension>
  <!-- ... -->
</Patient>

Using it in a Patient Profile

This is the same as for a simple extension:

<StructureDefinition xmlns="http://hl7.org/fhir">
  <id value="patient-profile"/>
  <!-- snip other metadata, narrative -->
  <differential>

    <!-- first, the patient root element
      - can be copy/paste from the base patient profile -->
    <element>
      <path value="Patient"/>
      <!-- snip definition -->
    </element>

    <!-- now, the general definition for extensions
      - can be copy/paste from the base patient profile,
      with changes for slicing  -->
    <element>
      <path value="Patient.extension"/>
      <!-- we're going to slice the extension element, and
        one of the extensions is one we have defined -->
      <slicing>
        <!-- extension is always sliced on url -->
        <discriminator>
          <type value="value"/>
          <path value="url"/>
        </discriminator>
        <!-- we don't care what the order of any extensions is -->
        <ordered value="false"/>
        <!-- Other extensions are allowed in addition to this one -->
        <rules value="open"/>
      </slicing>
      <!-- snip definition -->
    </element>

    <!-- now, the slice that contains our extension -->
    <element>
      <max value="1"/>
      <type>
        <!-- obviously it has to be an extension -->
        <code value="Extension"/>
        <!-- and here is the link to the extension definition:
          this extension has to conform to the rules laid down in its definition -->
        <profile value="http://example.org/fhir/StructureDefinition/patient-clinicalTrial"/>
      </type>
    </element>

  <!-- snip the rest of the profile -->

  </differential>
</StructureDefinition>


extensibility-registry.html

FHIR Core-defined Extension Registry

Maturity Level: N/AStandards Status:Informative

All extensions in this list are defined in this specification, and have a base URI of http://hl7.org/fhir/StructureDefinition/. Additional extensions can be registered on the HL7 FHIR registry at http://hl7.org/fhir/registry.


extensibility.html

Extensibility

Maturity Level: NormativeStandards Status:Normative

This exchange specification is based on generally agreed common requirements across healthcare - covering many jurisdictions, domains, and different functional approaches. It is common for specific implementations to have valid requirements that are not part of these agreed common requirements. Incorporating all valid requirements would make this specification very cumbersome and difficult to implement. Instead, this specification expects that additional valid requirements will be implemented as extensions.

As such, extensibility is a fundamental part of the design of this specification. Every element in a resource can have extension child elements to represent additional information that is not part of the basic definition of the resource. Applications should not reject resources merely because they contain extensions, though they may need to reject resources because of the specific contents of the extensions.

Note that, unlike in many other specifications, 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 simplicity for everyone.

To make the use of extensions safe and manageable, there is strict governance applied to the definition and use of extensions. Although any implementer can define and use extensions, there is a set of requirements that must be met as part of their use and definition.

Extension Element

Every element in a resource or data type includes an optional "extension" child element that may be present any number of times. This is the content model of the extension as it appears in each resource:

Notes:

Here is an example of an extension in XML (see definition):

<name>
  <extension url="http://hl7.org/fhir/StructureDefinition/iso-21090-EN-use" >
    <valueCode value="I" />
  </extension>
  <text value="Chief Red Cloud"/>
</name>

In this example the name with text = "Chief Red Cloud" is extended to have a name use code of "Indigenous" (defined in ISO 21090, but very rarely used in practice).

In JSON, extensions are represented similarly:

{
  "extension" : [{
    "url" : "http://hl7.org/fhir/StructureDefinition/iso-21090-EN-use",
    "valueCode" : "I"
  }],
  "text" : "Chief Red Cloud"
}

Making the types explicit in the representation means that all systems can read and write (and therefore store and/or exchange) extensions correctly without needing to access the definition of the extension.

Note that the JSON representation for extensions on primitive data types is handled differently. See Representing primitive types in JSON for further information.

Extensions can also contain extensions, either because the extension definition itself defines complex content - that is, a nested tree of values in the extension - or because the extension is extended with an additional extension defined separately.

In the case where an extension defines complex content, the identity of the parts of the extension are local/relative to the reference to the extension definition.

As an example, consider extending a patient with information about citizenship (see definition) containing 2 fields: code and period. In XML:

<Patient>
  <extension url="http://hl7.org/fhir/StructureDefinition/patient-citizenship" >
    <extension url="code" >
      <valueCodeableConcept>
        <coding>
          <system value="urn:iso:std:iso:3166" />
          <code value="DE" />
        </coding>
      </valueCodeableConcept>
    </extension>
    <extension url="period" >
      <valuePeriod>
        <start value="2009-03-14" />
      </valuePeriod>
    </extension>
  </extension>
  <!-- other data for patient -->
</Patient>

Or in JSON:

{
  "resourceType" : "Patient",
  "extension" : [{
    "url" : "http://hl7.org/fhir/StructureDefinition/patient-citizenship",
    "extension" : [{
      "url" : "code",
      "valueCodeableConcept" : {
          "coding" : [{
             "system" : "urn:iso:std:iso:3166",
             "code" : "DE"
          }]
       }
    }, {
      "url" : "period",
      "valuePeriod" : {
         "start" : "2009-03-14"
      }
    }]
	}]
}

This extension can be extended again, by adding a "passport-number" extension:

The passport number is defined as a separate extension (e.g. by an implementing organization, not in this specification) rather than part of the official citizenship extension. The URL of the extension is thus different. In XML:


<Patient>
  <extension url="http://hl7.org/fhir/StructureDefinition/patient-citizenship" >
    <extension url="code" >
      <valueCodeableConcept>
        <coding>
          <system value="urn:iso:std:iso:3166" />
          <code value="DE" />
        </coding>
      </valueCodeableConcept>
    </extension>
    <extension url="period" >
      <valuePeriod>
        <start value="2009-03-14" />
      </valuePeriod>
    </extension>
    <extension url="http://acme.org/fhir/StructureDefinition/passport-number" >
        <valueString value="12345ABC" />
      </extension>
    <!-- other data for patient -->
  </extension>
</Patient>

or in JSON:


{
  "resourceType" : "Patient",
  "extension" : [{
    "url" : "http://hl7.org/fhir/StructureDefinition/patient-citizenship",
    "extension" : [{
      "url" : "code",
      "valueCodeableConcept" : {
        "coding" : [{
          "system" : "urn:iso:std:iso:3166",
          "code" : "DE"
        }]
      }
    },{
      "url" : "period",
      "valuePeriod" : {
        "start" : "2009-03-14"
      }
    },
		{
      "url": "http://acme.org/fhir/StructureDefinition/passport-number",
      "valueString": "12345ABC"
    }]
  }]
}

Note that this passport number extension is shown here as an example defined by a fake organization, and not appropriate for re-use by implementers.

Modifier Extensions

There are some cases where the information provided in an extension modifies the meaning of the element that contains it. Typically, this means information that qualifies or negates the primary meaning of the element that contains it. Some examples:

Such extensions are known as "modifier extensions". For further information, see the definition of what makes an element - or an extension - a modifier. If modifier extensions are present, an application is restricted in its ability to safely process the resource unless it knows what the extension means for its own use of the data.

Implementers SHOULD avoid the use of modifier extensions where possible. Any use should be carefully considered against its possible downstream consequences. Inclusion of modifier extensions in an instance would be expected to significantly limit the ability of other systems to process the instance. However, implementers are often forced into these situations by the business arrangements around the use of resources, so this specification creates a framework for handling such cases. Implementers who are introducing an extension and are uncertain whether the extension should be marked as a modifier are encouraged to raise the question on chat.fhir.org.

This specification allows for such modifier elements to be included at the base of a resource or in any elements that do not have a data type (e.g. the elements that correspond to classes in the resource UML diagrams), and on a few specially selected data types. Other data types and elements inside data types SHALL NOT have modifier extensions, and extensions SHALL NOT have modifier extensions internally (except for the reusable structures allowed to appear in extensions, listed above).

Note that complex extensions are allowed to have elements in the complex extension that are marked Is-Modifier = true, which means that these elements modify the extension value itself. Internal extensions like this marked "Is-Modifier" are still represented using the extension element , not modifierExtension because the impact of the modifier element is expected to be known by applications that understand the containing extension.

Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself). Is-modifier elements not defined as part of an extension's definition cannot be conveyed.

In XML, these modifier elements are represented using an element named modifierExtension, which has same content as the extension element documented above:

Example: There's no element on MedicationRequest to write an "anti-prescription" - an instruction not to take a medication for a particular period. Classical clinical recording systems do not record this as a prescription - but one particular system does, and these "anti-prescription" records need to be shared within the institution where this happens as they are an important part of the workflow. Hence, applications are allowed to extend a resource with data like this:

<MedicationRequest>
  <modifierExtension url="http://example.org/fhir/StructureDefinition/anti-prescription">
    <valueBoolean value="true"/>
  </modifierExtension>
  <!-- ... other content ... -->
</MedicationRequest>

Or in JSON:

{
  "resourceType" : "MedicationRequest",
  "modifierExtension" : [{
    "url" : "http://example.org/fhir/StructureDefinition/anti-prescription",
    "valueBoolean" : true
  }],
  .. other content ...
}

Implementations processing the data in resources SHALL check for modifiers anywhere they could appear, and if a modifier extension is present on a data element that the application 'processes', SHALL do one of these things:

  1. recognize the modifier extension, and understand the impact of the extension when using the data
  2. reject instances that contain the modifier extension
  3. treat such instances as "for rendering purposes only" - i.e. check that the narrative status = extensions or generated, display the narrative and don't process the discrete data
  4. Ask for a human to check the modifier extension before proceeding to process the data
  5. carry a warning concerning the data along with any action or output that results from processing the data to inform users that it has not fully understood the source information

Processing the data of a resource typically means copying or filtering data out of a resource for use in another context (display to a human, decision support, exchange in another format where not all information is included, or storing it for this kind of use). Servers and background processes that simply move whole resources around unchanged are not "processing the data of the resource", and therefore these applications are not required to check for unknown modifier extensions.

#1: When an application understands this extension, it means that some developer has provided appropriate instructions for what to do with the data contained in it because of the existence of the modifier extension or has determined that the modifier does not impact on the system's computational functions. Note that this assessment needs to be repeated each time a system's computational behavior changes

#2: This means that implementations are not inherently required to "support" a modifier extension in any meaningful way - they can achieve this understanding by rejecting instances that contain this extension (a server, for instance, could return a HTTP 422 status code with an OperationOutcome if a client PUTs or POSTs a modifier extension it does not know). Applications might also be able to ignore a modifier extension if they know that it is safe to do so in their own context, though this would not usually be the case.

Implementations SHALL ensure that they do not process data containing unrecognized modifier extensions. Note that implementations might be able to be sure, due to their implementation environment (e.g. specific trading partner agreement), that modifier extensions will never occur, and can therefore meet the requirement to check for modifiers at the design stage. However, since integration and deployment options often change, applications SHOULD always check for modifier extensions when processing resources.

#3: One way to warn the user is to download the extension definition from the given URL, and then use the defined display name to present the extension to the user. An error message could look something like this:

Note that the narrative of the resource SHALL contain modifying information, so it is safe to show this to the user as an expression of the resource's content. A warning dialog box could be extended to offer the user the choice to see the original narrative.

Here is the prescription example from above with narrative:

<MedicationRequest xmlns="http://hl7.org/fhir">
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p><b>Note: This prescription is an instruction NOT to take a medication</b></p>
      <!-- snip actual narrative -->
    </div>
  </text>
  <!-- ...data... -->
  <modifierExtension url="http://example.org/fhir/StructureDefinition/anti-prescription">
    <valueBoolean value="true"/>
  </modifierExtension>
  <!-- ...data... -->
</MedicationRequest>

An application only needs to concern itself with modifier extensions on elements that it processes. Take, for example, a case where a procedure resource has a modifier extension on one of the performer elements indicating that they did not participate in the procedure. If an application is not using the performer details at all, the fact that one of the performers has a modifier extension is irrelevant and the application is free to ignore it. If the application does process the performers, and it sees the modifier extension, it must act in one of the ways outlined above.

Implementation Guides might place limitations on the appearance of modifier extensions within instances that comply with the implementation guide.

Summary: Conformance Rules for Modifier Extensions

Special Case: Missing data

In some cases, implementers might find that they do not have appropriate data for an element with minimum cardinality = 1. In this case, the element must be present, but unless the resource or a profile on it has made the actual value of the primitive data type mandatory, it is possible to provide an extension that explains why the primitive value is not present:

<uri>
  <extension url="http://hl7.org/fhir/StructureDefinition/data-absent-reason">
    <valueCode="unknown"/>
  </extension>
</uri>

In this example, instead of a value, a data missing code is provided. Note that it is not required that this particular extension be used. This extension is not a modifier extension, because the primitive data type has no value.

It is not valid to create a fictional piece of data for the primitive value, and then add an extension indicating that the data has been constructed to meet the data rules. This would be both a bad idea as well as a modifier extension, which is not allowed on simple data types.

Exchanging Extensions

Note: This section describes the use of "non-modifier extensions", except where "modifier extensions" are explicitly mentioned (see Modifier Extensions above for details).

Extensions are a way of allowing local requirements to be reflected in a resource using a common information based approach so that all systems can confidently process them using the same tools. However, when it comes to processing the information, applications will be constrained in their ability to handle extensions by the degree to which they are informed about them.

While the structured definition of an extension should always be available (see below for details), the mere availability of a definition does not automatically mean that applications know how to handle them correctly - generally, human decisions are required to determine how the data in extensions should be handled, along with the implicit obligations that surround the information.

For this reason, local requirements that manifest as extensions are an obstacle to integration and interoperability. The more the requirements are shared (i.e. regional or national scale), the less of an obstacle the extensions (and the requirements they represent) will represent. The consistent representation, definition and registration of extensions that this specification defines cannot resolve that problem - it only provides a framework within which such local variations can be handled more easily.

When it comes to deploying applications that support local requirements, situations will very likely arise where different applications exchanging information with each other are supporting different sets of extensions. This specification defines some basic rules that are intended to make management of these situations easier, but it cannot resolve them.

The degree to which a system can retain unknown extensions is a function of the type of system it is: a general purpose FHIR server, or a middleware engine would be expected to retain all extensions, while an application that manages patient registration through a user interface can only retain extensions to the degree that the information in them is part of the set managed by the user. Other applications will fall somewhere between these two extremes.

Summary: Handling extensions

Use the following rules as a guideline for handling resources:


fhirpatch.html

FHIRPath Patch

Maturity Level: 2Standards Status:Trial Use

This page documents how the Parameters resource is used to define a set of FHIRPath based patch operations.

Conceptual FHIRPath Operations

This table documents the FHIRPath operations that may be used to specify changes to a resource:

Type Path Name Value Index source destination Details
add Path at which to add the content Name of the property to add Data type to add at nominated place The content will be appended to the element identified in the path, using the name specified. Add can used for non-repeating elements as long as they do not already exist
insert Path of the collection in which to insert the content value (Data type) to add at nominated place index at which to insert The content will be inserted into the nominated list at the index specified (0 based). The index is mandatory, and must be equal or less than the number of elements in the list. Note: add is easier than insert at the end of the list
delete Path of the element to delete (if found) Only a single element can be deleted
replace Path of the element to replace value (Data type) to replace it with
move Path of the collection in which to move the content list index to move from list index to move to Move an element within a single list

There are a few base rules that apply for all operations:

Parameters Format

The FHIRPath patch operations are encoded in a Parameters resource as follows:

Parameter Type
type code
path string
name string
value *
index integer
source integer
destination integer

Here is an example of adding an element:

<Parameters xmlns="http://hl7.org/fhir">
  <parameter>
    <name value="operation"/>
    <part>
      <name value="type"/>
      <valueCode value="add"/>
    </part>
    <part>
      <name value="path"/>
      <valueString value="Patient"/>
    </part>
    <part>
      <name value="name"/>
      <valueString value="birthDate"/>
    </part>
    <part>
      <name value="value"/>
      <valueDate value="1930-01-01"/>
    </part>
  </parameter>
</Parameters>

Anonymous Types

Only some named data types (see the list) are allowed to be used directly in parameters. In order to add or insert other kinds of types - including anonymous elements (e.g. Observation.component, Timing.repeat), the content is defined by defining the name as described above, and instead of providing a value, a set of parts that are values are provided. Here is an example:

<Parameters xmlns="http://hl7.org/fhir">
  <parameter>
    <name value="operation"/>
    <part>
      <name value="type"/>
      <valueCode value="add"/>
    </part>
    <part>
      <name value="path"/>
      <valueString value="Patient"/>
    </part>
    <part>
      <name value="name"/>
      <valueString value="contact"/>
    </part>
    <part>
      <name value="value"/>
      <part>
        <name value="name"/>
        <valueHumanName>
          <text value="a name"/>
        </valueHumanName>
      </part>
    </part>
  </parameter>
</Parameters>

This pattern repeats as deep as necessary.

There is a set of test cases for implementers as part of the Test Case Downloads.


fhirpath.html

FHIRPath

Maturity Level: NormativeStandards Status:Normative

FHIRPath is a separate specification published at http://hl7.org/fhirpath in order to support wider re-use across multiple specifications.

FHIRPath is a path-based navigation and extraction language, somewhat like XPath. Operations are expressed in terms of the logical content of hierarchical data models, and support traversal, selection and filtering of data.

FHIRPath is used in several places in the FHIR and related specifications:

In addition, FHIRPath is used in pre-fetch templates in Smart on FHIR’s cds-hooks.

Using FHIRPath with Resources

FHIRPath uses a tree model that abstracts away the actual underlying datamodel of the data being queried. For FHIR, this means that the contents of the resources and data types as described in the Logical views (or the UML diagrams) are used as the model, rather than the JSON and XML formats, so specific xml or json features are not visible to the FHIRPath language (such as comments and the split representation of primitives).

More specifically:

Polymorphism in FHIR

For choice elements, where elements can be one of multiple types, e.g. Patient.deceased[x]. In actual instances these will be present as either Patient.deceasedBoolean or Patient.deceasedDateTime. In FHIRPath, choice elements are labeled according to the name without the '[x]' suffix, and children can be explicitly treated as a specific type using the as operation:

(Observation.value as Quantity).unit

FHIRPath statements can start with a full resource name:

Patient.name.given

The name can also include super types such as DomainResource:

DomainResource.contained(id = 23).exists()

These statements apply to any resource that specializes DomainResource.

Using FHIR types in expressions

The namespace for the types defined in FHIR (primitive data types, data types, resources) is FHIR. So, for example:

Patient.is(FHIR.Patient)

The first element - the type name - is not namespaced, but the parameter to the is() operation is.

Understanding the primitive types is critical: FHIR.string is a different type to System.String. The FHIR.string type specializes FHIR.Element, and has the properties id, extension, and also the implicit value property that is actually of type of System.String.

The evaluation engine will automatically convert the value of FHIR types representing primitives to FHIRPath types when they are used in expressions according to the following mapping:

FHIR primitive type FHIRPath type
FHIR.boolean System.Boolean
FHIR.string, FHIR.uri, FHIR.code, FHIR.oid, FHIR.id, FHIR.uuid, FHIR.sid, FHIR.markdown, FHIR.base64Binary System.String
FHIR.integer, FHIR.unsignedInt, FHIR.positiveInt System.Integer
FHIR.decimal System.Decimal
FHIR.date, FHIR.dateTime, FHIR.instant System.DateTime
FHIR.time System.Time

Since FHIR primitives may contain extensions, so that the following expressions are not mutually exclusive:

Patient.name.given = 'Ewout'         // value of Patient.name.given as a string
Patient.name.given.extension.first().value = true   // extension of the primitive value

The automatic conversion means that in most respects, a FHIR primitive can generally be treated as if it was the equivalent FHIRPath system type. The primary exception is the is() operation, where the difference is explicit:

Patient.name.given.is(FHIR.string);
Patient.name.given.is(System.string).not();
Patient.name.given.getValue().is(System.string);

As shown, all FHIR primitives have the operation .getValue() defined (see below) for the few edge cases where the automatic conversion isn't appropriate. Note that as() does not have such restrictions - both of the following are valid:

Patient.name.given.as(FHIR.string);
Patient.name.given.as(System.string);

FHIR Specific Variables

FHIR defines a specific variable that is always in scope when FHIRPath is used in any of the contexts above:

%resource // the resource that contains the original node that is in %context

The resource is very often the context, such that %resource = %context.

Additional functions

FHIR adds (compatible) functionality to the common set of functions:

extension(url : string) : collection

Will filter the input collection for items named "extension" with the given url. This is a syntactical shortcut for .extension.where(url = string), but is simpler to write. Will return an empty collection if the input collection is empty or the url is empty.

hasValue() : Boolean

Returns true if the input collection contains a single value which is a FHIR primitive, and it has a primitive value (e.g. as opposed to not having a value and just having extensions).

Note to implementers: The FHIR conceptual model talks about "primitives" as subclasses of the type Element that also have id and extensions. What this actually means is that a FHIR primitive is not a primitive in an implementation language. The introduction (section 2 above) describes the navigation tree as if the the FHIR model applies - primitives are both primitives and elements with children.

In FHIRPath, this means that FHIR primitives have a value child, but, as described above, they are automatically cast to FHIRPath primitives when comparisons are made, and that the primitive value will be included in the set returned by children() or descendants().

getValue() : System.[type]

Return the underlying system value for the FHIR primitive (see discussion above).

trace(name : string; selector : expression) : collection

When FHIRPath statements are used in an invariant, the log contents should be added to the error message constructed when the invariant is violated. For example:

"SHALL have a local reference if the resource is provided inline (url: height; ids: length,weight)"

  from

"reference.startsWith('#').not() or 
  (%context.reference.substring(1).trace('url') in %resource.contained.id.trace('ids'))"

The FHIRPath specification adds an additional parameter to the trace() function, a selection expression that can be used to shape what is logged for the collection that is traced. E.g.

  contained.where(criteria).trace('ids', type().name+"/"+id).process...

This will log the type/name for each contained resource that meets the criteria.

Note: the selector parameter is planned to be added to a future version of the base FHIRPath specification.

resolve() : collection

For each item in the collection, if it is a string that is a uri (or canonical or url), locate the target of the reference, and add it to the resulting collection. If the item does not resolve to a resource, the item is ignored and nothing is added to the output collection.

The items in the collection may also represent a Reference, in which case the Reference.reference is resolved.

ofType(type : identifier) : collection

In FHIR, only concrete core types are allowed as an argument. All primitives are considered to be independent types (so markdown is not a subclass of string). Profiled types are not allowed, so to select SimpleQuantity one would pass Quantity as an argument.

elementDefinition() : collection

Returns the FHIR element definition information for each element in the input collection.

slice(structure : string, name : string) : collection

Returns the given slice as defined in the given structure definition. The structure argument is a uri that resolves to the structure definition, and the name must be the name of a slice within that structure definition. If the structure cannot be resolved, or the name of the slice within the resolved structure is not present, an error is thrown.

For every element in the input collection, if the resolved slice is present on the element, it will be returned. If the slice does not match any element in the input collection, or if the input collection is empty, the result is an empty collection ({ }).

checkModifiers([{modifier : string}]) : collection

For each element in the input collection, verifies that there are no modifying extensions defined other than the ones given by the modifier argument. If the check passes, the input collection is returned. Otherwise, an error is thrown.

conformsTo(structure : string) : Boolean

Returns true if the single input element conforms to the profile specified by the structure argument, and false otherwise. If the structure cannot be resolved to a valid profile, an error is thrown. If the input contains more than one element, an error is thrown. If the input is empty, the result is empty.

memberOf(valueset : string) : Boolean

When invoked on a code-valued element, returns true if the code is a member of the given valueset. When invoked on a concept-valued element, returns true if any code in the concept is a member of the given valueset. When invoked on a string, returns true if the string is equal to a code in the valueset, so long as the valueset only contains one codesystem. If the valueset in this case contains more than one codesystem, an error is thrown.

If the valueset cannot be resolved as a uri to a value set, an error is thrown.

Note that implementations are encouraged to make use of a terminology service to provide this functionality.

For example:

Observation.component.where(code.memberOf('http://hl7.org/fhir/ValueSet/observation-vitalsignresult'))

This expression returns components that have a code that is a member of the observation-vitalsignresult valueset.

subsumes(code : Coding | CodeableConcept) : Boolean

When invoked on a Coding-valued element and the given code is Coding-valued, returns true if the source code is equivalent to the given code, or if the source code subsumes the given code (i.e. the source code is an ancestor of the given code in a subsumption hierarchy), and false otherwise.

If the Codings are from different code systems, the relationships between the code systems must be well-defined or a run-time error is thrown.

When the source or given elements are CodeableConcepts, returns true if any Coding in the source or given elements is equivalent to or subsumes the given code.

Note that implementations are encouraged to make use of a terminology service to provide this functionality.

subsumedBy(code: Coding | CodeableConcept) : Boolean

When invoked on a Coding-valued element and the given code is Coding-valued, returns true if the source code is equivalent to the given code, or if the source code is subsumed by the given code (i.e. the given code is an ancestor of the source code in a subsumption hierarchy), and false otherwise.

If the Codings are from different code systems, the relationships between the code systems must be well-defined or a run-time error is thrown.

When the source or given elements are CodeableConcepts, returns true if any Coding in the source or given elements is equivalent to or subsumed by the given code.

Note that implementations are encouraged to make use of a terminology service to provide this functionality.

htmlChecks : Boolean

When invoked on an xhtml element returns true if the rules around HTML usage are met, and false if they are not. The return value is undefined (null) on any other kind of element.

Changes to operators

~ (Equivalence)

Equivalence works in exactly the same manner, but with the addition that for complex types, equality requires all child properties to be equal, except for "id" elements.

In addition, for Coding values, equivalence is defined based on the code and system elements only. The version, display, and userSelected elements are ignored for the purposes of determining Coding equivalence.

For CodeableConcept values, equivalence is defined as a non-empty intersection of Coding elements, using equivalence. In other words, two CodeableConcepts are considered equivalent if any Coding in one is equivalent to any Coding in the other.

Environment variables

The FHIR specification adds support for additional environment variables:

The following environmental values are set for all contexts:

%sct        // (string) url for snomed ct
%loinc      // (string) url for loinc
%"vs-[name]" // (string) full url for the provided HL7 value set with id [name]
%"ext-[name]" // (string) full url for the provided HL7 extension with id [name]
%resource	// The original resource current context is part of. When evaluating a datatype, this would be the resource the element is part of. Do not go past a root resource into a bundle, if it is contained in a bundle.

// Note that the names of the `vs-` and `ext-` constants are quoted (just like paths) to allow "-" in the name.

For example:

Observation.component.where(code.memberOf(%"vs-observation-vitalsignresult"))

This expression returns components that have a code that is a member of the observation-vitalsignresult valueset.

Implementation Guides are allowed to define their own externals, and implementers should provide some appropriate configuration framework to allow these constants to be provided to the evaluation engine at run-time. E.g.:

%"us-zip" = '[0-9]{5}(-[0-9]{4}){0,1}'

Authors of Implementation Guides should be aware that adding specific environment variables restricts the use of the FHIRPath to their particular context.

Note that these tokens are not restricted to simple types, and they may have fixed values that are not known before evaluation at run-time, though there is no way to define these kind of values in implementation guides.

Restricted Subset ("Simple")

This page documents a restricted subset of the FHIRPath language that is used in a few contexts in this specification. When the restricted FHIRPath language subset is in use, the following rules apply:

These rules exist to keep processing the path simple to support use of the path by processors that are not backed by a full FHIRPath implementation.

The following locations use this restricted FHIRPath language:

Terminology Service API

Unlike this rest of this page, the FHIR Terminology service API is only draft (Maturity = 0). It will be advanced to a more mature status following the usual Maturity Model for FHIR.

In order to support terminological reasoning in FHIRPath statements, FHIR defines a general %terminologies object that FHIRPath implementations should make available. Calls to this object are passed through a standard FHIR terminology service.

Summary:

%terminologes.expand(valueSet, params) : ValueSet
%terminologies.lookup(coded, params) : Parameters
%terminologies.validateVS(valueSet, coded, params) : Parameters
%terminologies.validateCS(codeSystem, coded, params) : Parameters
%terminologies.subsumes(system, coded1, coded2, params) : code
%terminologies.translate(conceptMap, code, params) : Parameters

expand

%terminologes.expand(valueSet, params) : ValueSet

This calls the Terminology Service $expand operation (formal definition).

Parameters:

Return Value: a ValueSet with an expansion, or null if an error occurs.

lookup

%terminologies.lookup(coded, params) : Parameters

This calls the Terminology Service $lookup operation (formal definition).

Parameters:

Return Value:

validateVS

%terminologies.validateVS(valueSet, coded, params) : Parameters

This calls the Terminology Service $validate-code operation on a value set (formal definition).

Parameters:

Return Value: A Parameters resource with the results of the validation operation.

validateCS

%terminologies.validateCS(codeSystem, coded, params) : Parameters

This calls the Terminology Service $validate-code operation on a code system (formal definition).

Parameters:

Return Value: A Parameters resource with the results of the validation operation.

subsumes

%terminologies.subsumes(system, coded1, coded2, params) : code

This calls the Terminology Service $subsumes operation (formal definition).

Parameters:

Return Value: a code as specified for the subsumes operation.

translate

%terminologies.translate(conceptMap, coded, params) : Parameters

This calls the Terminology Service $translate operation (formal definition).

Parameters:

Return Value: A Parameters resource with the results of the translation operation.


financial-module.html

Work Group Standards Status:Informative

Financial Module

Introduction

The Financial module covers the resources and services provided by FHIR to support the costing, financial transactions and billing which occur within a healthcare provider as well as the eligibility, enrollment, authorizations, claims and payments which occur between healthcare providers and insurers and the reporting and notification between insurers and subscribers and patients.

See also the Administration and WorkFlow modules.

Index

Image showing the relationship between the financial resources

Support

Administrative

NameAliasesDescription

Billing

Claims, processing and responses

NameAliasesDescription

Payment

Used to support service payment processing and reporting

NameAliasesDescription

Other

Patient reporting and other purposes

NameAliasesDescription

Additional Resources will be added in the future. A list of hypothesized resources can be found on the HL7 Confluence. Feel free to add any you think are missing or engage with one of the HL7 Work Groups to submit a proposal to define a resource of particular interest.

Security and Privacy

Financial information in general and in particular when related to or including health information, such as claims data, are typically considered Protected Health Information and as such must be afforded the same protection and safeguards as would be afforded to purely clinical identified health data.

The Security and Privacy measures associated with FHIR, such as the use of Security labels and tags in the resource.meta, are encouraged in addition to the use of whatever measures for authorization and encryption are supported by the chosen exchange model, e.g. FHIR REST, Web Services, Direct, MLLP, SMTP and others.

For more general considerations, see the Security and Privacy module.

Glossary

Financial information in general and in particular when related to or including health information, such as claims data, are typically considered Protected Health Information and as such must be afforded the same protection and safeguards as would be afforded to purely clinical identified health data.

TermAliasResource TypeDescription
AdjudicationClaim, Preauthorization or Predetermination ProcessingClaimResponseThe processing by an insurer of a claim, preauthorization or predetermination to determine under the insurance plan what if any benefits are or would be payable.
Assignment of BenefitAssignmentn/aWhen a Beneficiary directs that any benefit they receive from the adjudication of a claim may be paid to the service provider who issued the claim.
AttachmentCommunicationA collection of information objects sent to a party to support their understanding or processing of another resource such as a claim.
BeneficiaryPatientPatientThe party who's health care expenses may be covered by a policy issued by an Insurer.
Benefit AmountBenefitn/aThe amount payable under an insurance policy for a given expense incurred by a patient.
ClaimClaimClaimA request to an Insurer to adjudicate the supplied charges for health care goods and services under the identified policy and to pay the determined Benefit amount, if any.
Coordination of BenefitCOBn/aThe the rules, usually regionally defined, which govern the order of application of multiple Insurance coverages or SelfPay to a given suite of health care expenses.
DependentPatient, RelatedPersonA person who receives their coverage via a policy which is own or subscribed to by another. Typically these include spouses, partners and minor children but may also include students, parents and disabled persons.
InsurerPayer, PayorOrganizationA public or private insurer which will adjudicate Claims for health care goods and services to determine if the there is any benefit payable, amount due, under the policy which covers the patient.
Networkn/aAn insurer defined grouping of Providers for which the Beneficiary's plan preferentially covers the costs of treatment, eg. closed, rental, etc.
PayerPayor, InsurerOrganizationA public or private insurer.
PayorPayer, InsurerOrganizationA public or private insurer.
PolicyContractA contract between an Insurer and an individual or other entity such as an employer to reimburse covered parties (Beneficiaries) for some or all of a prescribed suite of health-related goods and services.
Policy HolderPolicy ownerPatient, RelatedPerson, OrganizationThe party which owns the policy. It may be the employer for work-related policies or the individual for purchased or public policies.
PreauthorizationPrior Authorization, Pre-AuthClaimA request to an Insurer to adjudicate the supplied proposed future charges for health care goods and services under the identified policy and to approve the services and provide the expected benefit amounts and potentially to reserve funds to pay the benefits when Claims for the indicated services are later submitted.
PredeterminationPre-Determination, PreDClaimA request to an Insurer to adjudicate the supplied 'what if' charges for health care goods and services under the identified policy and report back what the Benefit payable would be had the services actually been provided.
Solicited AttachmentCommunicationAn attachment sent to provide supporting information in response to having received a request for additional information.
SubscriberPatient, RelatedPersonThe person who signs-up for the coverage. May be an employee or person with dependents.
Unsolicited AttachmentCommunicationAn attachment sent to provide supporting information without first having received a request for additional information.

Common Use Cases

The table below details various common business activities which occur in the financial realm, and the focal resources which may be exchanged, along with supporting resources, to accomplish the business activities. Whether the resources specified are actually needed requires consideration of the business itself and the exchange methodology and transport being used.

For example: If a content model is not required to obtain the appropriate status element then a SEARCH (GET) may be used, however if a content model is required to support the request for information then the content model will need to be CREATEd (POST). Alternately, if FHIR Operations are being used then the specified focal resource may be employed as one of the Operation parameters or might not be required.

Business ActivityRequest ResourceResponse Resource
Eligibility CheckCoverageEligibilityRequestCoverageEligibilityResponse
Enrollment UpdateEnrollmentRequestEnrollmentResponse
ClaimClaim (type={discipline}, use=claim)ClaimResponse
Claim with attachmentsBundle containing Claim and the attachmentsClaimResponse
PredeterminationClaim (type={discipline}, use=predetermination)ClaimResponse
PreauthorizationClaim (type={discipline}, use=preauthorization)ClaimResponse
ReversalCancelTask (code=cancel)Task (optional output=ClaimResponse)
NullifyNullifyTask (code=nullify)Task (output=error codes)
ReleaseReleaseTask (code=release)Task (output=error codes)
Re-adjudicationReprocessTask (code=reprocess)Task (output=ClaimResponse)
Status CheckStatusTask (code=status)Task (output=status code)
Pended Check (Polling)PollTask (code=poll)Task (output={Resource})
Payment NoticeTask (code=deliver, input=PaymentNotice)Task (output=error codes)
Payment ReconciliationTask (code=poll, input=PaymentReconciliation)Task (output=PaymentReconciliation)
Send AttachmentsTask (code=deliver, input=Communication)Task (output=error codes)
Request AttachmentsTask (code=poll, input=CommunicationRequest)Task (output=CommunicationRequest)
Request an Explanation of Benefits   Task (code=poll, input=ExplanationOfBenefit)Task (output=ExplanationOfBenefit)

{discipline} means the type of claim: OralHealth, Vision, Pharmacy, Professional or Institutional.

{Resource} means any pended or undelivered resource subject to the selection details specified in the request.

Tasks

See the Financial examples in Task.

In addition to supplying a reference to a focal resource in the .focus element, where appropriate an .input element of type 'origresponse' may also be provided with a reference to the resource which was the original response to the focal resource.

Cancel

The Cancel is the formal request to cease processing an incomplete prior request or to reverse a completed prior request or information submission. A copy of the original request may be retained. The Task will be updated to indicate whether the requested action was accepted and successful or whether errors were found in the request and may contain a reference to the ClaimResponse or such other resource as may be appropriate for expressing the outcome of the cancellation.

Nullify

The Nullify is the formal request to cease processing an incomplete prior request or to reverse a completed prior request or information submission. All copies of the original submission are to be purged, although audit logs may be retained. The Task will be updated to indicate whether the requested action was accepted and successful or whether errors were found in the request.

Poll

Poll provides supporting information for the poll request. The response to a Poll is a Task referring to: a previously undelivered response Resource; a Bundle containing one or more Resources; or, a Task which may contain errors.

A simple Poll request, one which doesn't specify additional .input parameters: origresponse, include, exclude, period or count; would return any single pended resource. Specific types of business behaviors may be supported by providing values for the filtering elements in the .input element, for example:

Upon processing of the request the Task or Bundle may contain errors or a reference to the resource(s) found.

Release

Release is the formal request for the release of any allocation or reserved resources such as funds or products reserved, for example on a preauthorization, which have not been consumed, eg. as indicated on claims, and which are no longer required. The preauthorization which request ed the reservation will be identified in the .focus element and the insurer's response confirming the reservation may be provided as a .input element.

Reprocess

Reprocess indicates the resource which is to be reprocessed in the .focus element, for example a claim to be re-adjudicated or a specimen or diagnostic image to be re-examined, and provides both supporting information for the reprocessing and the line items which are to be reprocessed in the .input element.

This is necessary for the limited supporters who require the ability to formally request the reprocessing of specified service sub-trees from an already processed resource such as a previously adjudicated Claim. Upon processing of the request the Task may contain errors or a reference to the ClaimResponse or such other resource as may be appropriate for expressing the outcome of the reprocessing.

Status

Status indicates the resource for which the processing status is requested in the .focus element and provides any supporting information for the status request. The

This is a formal request for systems which require requisition-level information or transports which don't support a 'Get Operation', for the processing status of a previously submitted processing request.

Upon processing of the status request the Task may contain errors or a .output parameter of 'status' containing the status of outcome code of the processing of the targeted resource.

Relative Order of Use

The table below details the relative order of events and use of financial resources for patient care during the care cycle. Not all steps or information exchanges may occur, and supporting information may be required more frequently than has been depicted below.

Business ActivityFocal Resource
Patient visits Provider
Provider checks for valid insurance coverageCoverageEligibilityRequest
Insurer responds with coverage status and optional plan detailsCoverageEligibilityResponse
Provider examines Patient and reviews treatment options
Provider submits Predetermination(s) for treatment options to determine potential reimbursementClaim {use=predetermination}
Insurer responds with potential reimbursementClaimResponse
Provider and Patient determine treatment plan
Treatment plan submitted to Insurer to reserve fundsClaim {use=preauthorization}
Insurer acknowledges receipt of preauthorizationClaimResponse
Insurer requests additional informationCommunicationRequest
Provider submits supporting informationCommunication
Insurer provides adjudicated response to pre-authorizationClaimResponse
Provider checks on status of pre-authorization processingTask {code=status}
Insurer responds indicating adjudication is readyTask
Provider retrieves pre-authorization adjudicationREAD or Task {code=poll}
Provider provides treatment
Provider submits patient's claim for reimbursementClaim {use=claim}
Insurer responds with claim adjudicationClaimResponse
Patient leaves treatment setting
Patient requests an Explanation of Benefit for their Personal Health Record applicationREAD or Task {code=poll}
Insurer responds with Explanation of BenefitExplanationOfBenefit
Provider requests the payment details associated with a bulk paymentSEARCH or Task {code=poll}
Insurer responds with a Payment ReconciliationPaymentReconciliation
Insurer notifies provider that payment has been issuedPaymentNotice
Insurer notifies parties that payment funds have been receivedPaymentNotice

Resource Status Life-cycle

Financial resources, such as claim and eligibility resources, begin with the status 'draft' and continue with this status during the development of the resource. When a resource is exchanged with an external party, for example when a provider claim is sent or otherwise created on the insurer's system before the exchange the status of the claim shall be changed to 'active'. A resource with the 'active' status is immutable and cannot be edited except for further change to the status in the event the resource is subsequently canceled resulting in a status of 'cancel'.

In the event that a resource is determined to have been entered in error, for example a wrong date of service or billing code, while the status is 'draft' then the status may be changed to 'entered-in-error' and no further editing of the resource is permitted. If the resource status is 'active' when the error is noted then the resource must be canceled and further interaction with whatever parties have been supplied the resource may be required to halt any processing or reverse any effects of the resource prior to creating an amended instance.

Secondary Uses

In addition to their primary use of conveying patient billing information to insurers for reimbursement either to the subscriber or the provider ( assignment of benefit), many of the financial resources, such as Claim and ExplanationOfBenefit, may be used to export data to other agencies to support reporting and analytics. Consequently the cardinalities of many elements are set to optional, '0..', to support reporting, for example of partial adjudications, where the cardinality for a normal claim profile or claim response profile would expect the cardinality to required, '1..'.

Profiles will usually be necessary to set tight constraints on cardinalities, require jurisdictional terminologies, and eliminate or introduce elements require to support various business needs and discipline requirements.

Attachments - Supporting Information

There is often a need to provide supporting information, commonly referred to as attachments, to document the need for a service and/or to confirm that the good or service was authorized or rendered. This information may be in many forms, including: scanned documents, PDFs, word processing files, XRays, images, CDAs and FHIR Resources.

Supporting information may be provided, as a reference or the actual material, to support the Claim (complete claim or Preauthorization) or ExplanationOfBenefit in a variety of manners:

Subrogation - Insurers recovering costs from other insurers

It is not always appropriate to send a Claim, or other eClaim requests such as eligibility or preauthorizations, to some insurers. This may be due to jurisdictional rules, for example the national health program may pay for workplace accident claims then recover costs directly against that program, or there may be no direct relationship between the provider and the insurer, for example for injury caused by another party or covered under property or accident insurance, the patient's primary health insurer may pay for services then recover a portion of their costs from that other insurer.

To support the downstream recovery of costs from the appropriate insurer it is necessary to supply the insurance coverage information for all logically potentially applicable coverages and to flag those which are provided for subrogation so that both the provider and payor systems know whether to expect to submit eClaims requests to or expect eClaims responses from these insurers. In the specific case of the Claim resource (claim, predetermination, preauthorization) the provider would list all insurance coverages, including only work or accident related if appropriate, but send Claims only to non-subrogation coverages (Coverage.subrogation=false) and not include ClaimResponses, nor would payors expect ClaimResponses to be provided, for subrogated coverages.

Coordination of Benefit - Handling multiple insurance coverages

When a patient has multiple Coverages there will generally be agreement within the jurisdiction as to the order of application of claims recovery against the coverages which is referred to as the Coordination of Benefit (COB) order. This would also be the order used to request preauthorization and predeterminations. Coverage eligibility is typically independent of the COB order as it is coverage specific.

While the jurisdiction rules must be consulted for COB specifics, generally: risk specific polices apply before risk-general policies; national policies will apply before personal or top-up policies; coverage obtained with full-time employment applies before coverage obtained with part-time employment; policies where the patient is the subscriber apply before a spouse's policy; and, there will be some understanding as to the order of application for policies which apply to dependents, for example, birthday order of the subscribers.

When sending Claims down the COB order all logically applicable policies will be listed, so that insurers may confirm adherence to the COB order, and, aside from subrogated coverages, will include the ClaimResponses from any coverages appearing earlier in the COB order so that each insurer may correctly calculate their portion of the overall cost of products and services supplied. The claims work their way through the COB order until the order is exhausted or their is no further outstanding balance, whichever comes first.

While it is most common, it is not always the case that all claims originate with the provider. In some jurisdictions, in some or all cases, the primary health insurer takes or is assigned responsibility to obtain the ClaimResponses from downstream insurers and to return the suite of ClaimResponses to the provider. This is similar to subrogation in that it removes the claim-cycle work from the provider but unlike subrogation the individual insurers still make their payments to the provider, if Assignment of Benefit is agreed, and a reversal of the base claim often requires the provider to handle reversal of the downstream claims as well.

Batches - Handling multiple eClaim requests or responses within a single exchange

eClaims request and response resources may be exchanged between providers and payors individually or via batches. eClaim requests, individual and batches, may be created on a payor system via FHIR REST or sent to the payor, either synchronously via FHIR operations or another request-response protocol such as: WSI Web Services, a SOA exchange, MLLP, etc.

Individual eClaim Requests and Responses

An individual eClaim request or response, for example a Claim (use=claim), may be either a simple Claim resource which refers to or contains any supporting resources or Bundle resource containing a single request, e.g. a Claim, and any associated resources (Patient, Practitioner, Organization, Coverage, etc.).

eClaim Batches

A batch of eClaim requests or responses is a (FHIR Bundle) containing one or more eClaim requests or responses, as above. The batch is simply a 'bag' of request or responses, typically of a consistent type of request or response, for example: all eligibility, preauthorizations, claim, payment notifications, etc. There is no assurance provided that when receiving a batch of 100 claim responses that they relate to the 100 claim just submitted.

Real-time eClaims Exchange

The eClaims resources are intended to support the real-time exchange of eClaim request and responses. While certain eligibility, claims, preauthorizations and predeterminations may be processed in real-time there are many cases where they cannot due to the complexity of the material submitted, the maturity of the jurisdictional styles and insurer processing systems, and the inclusion or requirements for supporting information which tends to require manual review. Therefore, in some cases the eClaim response will only indicate the receipt and typically validation that the request is processable (or that it contain errors which inhibit processing).

Deferred responses, those which could not be returned in real-time, and those returned asynchronously may be obtained either by FHIR REST (a GET or SEARCH) or via a Poll depending upon the style of information exchange supported.

Developmental Roadmap

The Financial Management Work Group (FM) is responsible for two subdomains:

Financial Accounts and Billing (FIAB) - resources for accounts, charges (internal costing transactions) and patient billing, and
Financial Claims and Reimbursement (FICR) - insurance information, enrollment, eligibility, predetermination, preauthorization, claims, patient reporting and payments.

To date FM has been focusing on the resources required to support the exchange of claims and related information between health care providers and insurers. The first draft of this work is nearing completion with the release of the first Financial Standard for Trial Use in STU4 of FHIR. Over the next year further refinements will be expected as implementers begin developing regional profiles and begin live pilots with resources.

Once the above is well underway FM can then look to developing the Enrollment-related resources and the resources to support the FIAB functions.

Terminology

In many cases an example valueset has been provided in this release. Financial Management will be devoting effort in the preparation to Release 5 of FHIR to develop more representative example sets and to determine where global codesets exist such that some of the valuesets may be elevated in strength to extensible or required.


fmg.html

FMG Summary Page

Maturity Level: N/AStandards Status:Informative

FMG Approvals


formats.html

Resource Formats

Maturity Level: NormativeStandards Status:Normative

This page documents how the content of the resources are described. In actual exchange, resources can be represented in the following formats: XML, JSON and Turtle. Additional Bulk Data Formats are also undergoing exploration. Other representations are allowed, but are not described by this specification (though see link below .

Resource Definition

The resources are described in several different ways:

In addition to this descriptive syntax, other definitional forms are available, including W3C schema, Schematron, JSON Schema, and the StructureDefinition syntax defined internally.

Logical table

The Logical View shows the resources as a tree structure with the following columns:

Column Content
Name The name of the element in the resource (manifests as XML element name or JSON or RDF property name). Some names finish with [x] - the meaning of this is discussed below. In addition, this column contains an icon that denotes the underlying type of the content. The icons are described below
Flags A set of information about the element that impacts how implementers handle them. The flags are described below
Card. Cardinality: the lower and upper bounds on how many times this element is allowed to appear in the resource
Type The type of the element (hyperlinked to the definition of the type). Note that the type of the element has one of two meanings, depending on whether the element has defined children. If the element has children, then the element has an anonymous type that specializes the given type. If the element has no children, then the element has properties and children as specified by the nominated type
Description & Constraints A description of the element, and details about constraints that are applied to it. Particularly, for coded elements, information about which codes can be used. The description comes from ElementDefinition.short

Here's an example:

Name Flags Card. Type Description & Constraints
.. Resource Name Base Type Definition
... nameA Σ 1..1 TypeA description of content
... nameB[x] ?! Σ 0..1 description
SHALL at least have a value
.... nameBType1 0..1 TypeB
.... nameBType2 I 0..1 typeC
... nameC 1..* BackboneElement Definition
.... nameD 1..1 TypeD Relevant Records

Key to Type Icons

Key to Flags

Notes:

The data type for a particular element is typically expressed as the name of the specified type with a hyperlink to its definition. However, there are two exceptions:

In profiles, references to types may be profiled - i.e. Instances of the element must comply with a specified profile or one of a list of profiles. The canonical URLs of any applicable profiles are listed inside {}.

Where an element can have a choice of data types, or is a Reference these are represented by showing the common type (Reference or Type), and then showing the applicable data type names or resource types in a stereotype, separated by the | character. Type is not formally otherwise defined by this specification, but is a super type of all the data types.

Choice of Data Types

A few elements have a choice of more than one data type for their content. All such elements have a name that takes the form nnn[x]. The "nnn" part of the name is constant, and the "[x]" is replaced with the title-cased name of the type that is actually used. The table view shows each of these names explicitly.

Elements that have a choice of data type cannot repeat - they must have a maximum cardinality of 1. When constructing an instance of an element with a choice of types, the authoring system must create a single element with a data type chosen from among the list of permitted data types.

Note: In object-orientated based implementations, this is naturally represented as a polymorphic property. However this is not necessary and the correct implementation varies according to the particular features of the language. In XML schema, these become an xs:choice of element. To help with code generation, a list of choice elements is published.

UML

The UML diagrams represent the same content as a series of classes that represent the elements of a resource.

NameA Documentationelement : [type] [0..*] DocumentationnameB : CodeableConcept [0..1] « Value Set Description (Strength=Preferred)Value Set Name? » NameC Documentationvalue[x] : Type [0..1] « Type1|Type2|Type3 » Docuementationreference : Reference [0..1] « Resource1|Resource2 » DocumentationnameC [0..1]

The elements and the data types are hyperlinks to the formal definitions of the parts. The UML diagrams also show the vocabulary bindings. These are hyperlinks to the value set details.

The actual order of the elements in XML cannot be determined from the diagram, nor whether a UML property becomes an element or an attribute in the XML representation.

Bindings to value sets are indicated by a stereotype on the element. The stereotype has 2 parts: the value set name, and a symbol that denotes the strength of the binding:

Serialization Format Representations

This specification defines the following ways to represent resources when they are exchanged:

Systems SHALL declare which format(s) they support in their Capability Statement. If a server receives a request for its Capability Statement in a format it does not otherwise support, it SHALL return a 406 Not Acceptable. Note: 406 is the appropriate response when the Accept header requests a format that the server does not support, and 415 Unsupported Media Type when the client posts a format that is not supported to the server.

Clients and servers can choose what syntax(s) to implement. In the interests of interoperability, servers SHOULD support both the XML and JSON formats, which have the same functionality, for different technical stacks. The RDF format has quite different benefits - primarily around data analysis rather than exchange.

Bulk Data Formats

Unlike this rest of this page, the bulk use formats are draft until further experience is gained with their use. Their status will be reviewed in a future version of FHIR.

The XML and JSON formats are designed to support typical system process based data exchange uses. FHIR is also used to exchange large amounts of data- 1000s of records, or more (up to billions). The formats above can be used for this, but more suitable formats exist. This specification documents (or is exploring documenting) the following formats:


foundation-module.html

Work Group Standards Status:Informative

Foundation Module

The Foundation Module is responsible for the overall infrastructure of the FHIR specification. Every implementer works with the content in the foundation module which ever way they use FHIR.

The Foundation Module maintains most of the basic documentation for the FHIR specification. In addition, the Foundation Module includes the following resources:

Foundation Framework

Content Management Resources.

Data Exchange Resources.

Relationships with other modules

Common Use Cases: ??

Developmental Roadmap

Much of the foundation module is well advanced through the maturity model process. Specifically, the following parts of the specification:

The focus over the next 18 months or so as the 4th release of FHIR is prepared is to focus on stability and move these artifacts to normative status. However, some parts of the foundation module are not as well explored, and are not as far advanced with regard to their development.