Section: 7

genomics.html

Genomics Implementation Guidance

Maturity Level: 1Standards Status:Trial Use

Table of Contents

  1. Background
  2. Overview
  3. MolecularSequence Resource
  4. Observation-genetics Profile
  5. DiagnosticReport-genetics Profile
  6. ServiceRequest-genetics Profile
  7. HLA genotyping results Profile
  8. Relationship among MolecularSequence resource and genetics profiles
  9. HL7 Domain Analysis Model Use Cases
  10. Other Genomics Use Cases
  11. Clinical Genomics Apps
  12. Appendix 1: From DSTU2 Genomics to STU3

The material on this page is currently undergoing work to be refactored in a future release as further analysis is done, for example as part of the Genomics Reporting Implementation Guide.

Background

Rapid advances in sequencing technologies, clinical genetics tests for whole genome and exome sequencing are allowing sophisticated genetics testing to be used by providers and patients in clinical decisions. Results from such tests are used to identify distinct genetic variants that may contribute to syndromes, conditions and/or predictive responses to treatments. The implementation of precision medicine will depend upon having such data to diagnose patients, choose medications, and predict the course of disease and care, but will require standards and effective user interfaces.

A current technical challenge exists in interoperability, the ability to access and share clinical and genetics data. The challenges of interoperability includes collection, coding, and retrieval to scale. An individual's genetic data set is large, complex and requires curation. Unfortunately, incompatible systems and nomenclatures are already in use. A standards-based ontology that could be adopted to integrate both genetic data and clinical information systems will be crucial to accelerating the integration of precision medicine and to make sense of genetic testing results in a complete clinical context.

One approach for collecting, coding, and retrieving genetics data comes from the Global Alliance for Genomics and Health (GA4GH). The GA4GH organization has built and is refining an API and data model for the exchange of full sequence genomic information across multiple research organizations and platforms. The GA4GH focuses on the needs of researchers.

A second approach is evolving from HL7 through FHIR. FHIR is attractive because it is relatively easy to implement because it is comprised of a set of modular components called resources, which can be easily and incrementally assembled into working systems. The clinical requirements for genetics data is, relative to genomics research needs, utilitarian and reductive because it is about distilling and extracting particular genetics data produced by ever more sophisticated testing for use at the point-of-care. This has made FHIR a very functional framework to initiate an interoperable clinical genetics data standardization to which multiple stakeholders have contributed to this guide.

FHIR DSTU2 introduced a standard genetics profile that applies to the FHIR Observation resource. Using this profile, Observation payloads can return genetic testing results in a standardized manner.

Extending Observations rather than creating a new, dedicated FHIR genetics data resource is consistent with the FHIR community mandate because it only adds new resources to an existing resource library when there is a compelling case to do so. We provide the case to add a MolecularSequence resource in this specification.

Overview

STU3 moves beyond FHIR DSTU2 Standard Genetics profile on Observation allowing increased granularity and less ambiguity by creating a new resource to be called MolecularSequence. This resource will be used to hold clinically relevant sequence data in a manner that is both efficient and versatile integrating new and as yet undefined types of genomic and other -omics data that will soon be commonly entered into health records for clinical use. MolecularSequence will be leveraged by other FHIR resources, including Observation. This is consistent with how all FHIR resources are designed and used.

The September 2014 Informative Ballot (“HL7 Clinical Genomics, Domain Analysis Model: Clinical Sequencing Release 1”) provided guiding use cases, which initially informed development of the initial Standard Genetics profile that is found in FHIR DSTU2. The same use cases also led to a second Project to develop a MolecularSequence resource (“Develop FHIR sequence resource for Clinical Genomics”). A preliminary effort to address these issues has been explored and published in context of the Substitutable Medical Applications and Reusable Technologies (SMART) Platforms Project and described in an article (“SMART on FHIR Genomics: Facilitating standardized clinico-genomic apps”).

MolecularSequence is designed to hold genetic sequences in blocks relevant to actionable clinical decision-making. Extensions to MolecularSequence address complex cases and can associate it with repositories for retrieving a patient’s full sequence data, such as those defined by GA4GH. Other changes include a suite of genetics profiles for other FHIR resources. In addition, the Observation-genetics profile adds new references so that an Observation can report genetics test results to be integrated into the EHR. There are also new genetics-extension profiles for DiagnosticReport, ServiceRequest and FamilyMemberHistory, respectively, to extend them to report genetics results. We have given all of these FHIR genetics profiles the suffix “-genetics” (e.g. “DiagnosticReport-genetics profile”). New profiles on top of DiagnosticReport have been created for reporting HLA genotyping results.

On the following pages, we elaborate upon the rationale for the proposed design, introducing in some detail the following resource and profiles:

With these resource and profiles, FHIR can support a large set of clinical use cases (see Section 9, 10 , and 11) and is thus positioned to address all emergent -omics use cases, including Next-Generation Sequencing (NGS). These tools are simple to implement, will optimize payload sizes, and help developers avoid redundant retrieval of data. Appendix 1 of this document shows how DSTU 2.0 can be mapped to the new additions to the resource.

MolecularSequence Resource

Structure Diagram

Description

The MolecularSequence resource is designed for next-generation sequencing data. Patients’ observed sequences should be represented by recording reference sequence id/string and detected variants. To specify how it proceed, here is a picture below:

MolecularSequence.coordinateSystem: This element shall be constrained into only two possible values: 0 for 0-based system and 1 for 1-based system. Below is the picture that could explain what’s the difference between these two systems:

coordinateSystem

Here are two examples that clarify the usage in both cases (they represent same segment part):

MolecularSequence.referenceSeq: Four optional ways are provided to represent reference sequence in MolecularSequence resource:

  1. MolecularSequence.referenceSeq.referenceSeqId: Reference sequence id in public database;
  2. MolecularSequence.referenceSeq.referenceSeqString: Reference sequence string;
  3. MolecularSequence.referenceSeq.referenceSeqPointer: Reference to observed sequence stored in another sequence entity;
  4. MolecularSequence.referenceSeq.genomeBuild, MolecularSequence.reference.chromosome: The combination of genome build and chromosome.

The window selects a range from the reference sequence (or genome) that is used to define building block of a current sequence (e.g. MolecularSequence resource instance 1).

MolecularSequence.referenceSeq.strand: Only two possible values can be made by strand, +1 for plus strand while -1 for minus strand. Since the directionality of the sequence string might be represented in different word in different omics scenario, below are simple example of how to map other expressions into its correlated value:

Map to +1 Map to -1
5′-to-3′ direction 3′-to-5′ direction
Watson Crick
Sense Antisense
Positive Negative

MolecularSequence.quality: Quality scores for bases in the sequence. It is intended to be compliant with emerging regulatory needs needs (eg: those found at PrecisionFDA).

MolecularSequence.variant: This complex element is used for encoding sequence. When the information of reference sequence and variants are provided, the observed sequence will be derived.

Internal Pointers

MolecularSequence.patient: This element points to a Patient identifier to show that this sequence is related to the same patient.

MolecularSequence.specimen: A pointer to specimen identifier, if needed.

MolecularSequence.device: A pointer to Device identifier which is used for describing sequencing method (such as chip id, chip manufacturer etc.)

MolecularSequence.pointer: A pointer to a MolecularSequence instance for the next sequence block to build a sequence graph.

External Pointers

MolecularSequence.repository: This complex element is used to provide a clarifying structure, a base URL, and/or relevant IDs when referring to an external repository.

GA4GH Repository Example. If the MolecularSequence resource refers to a GA4GH repository for read info, references to a GA4GH full sequence dataset should conform to GA4GH data models and accessed via the GA4GH API. The URL of a GA4GH repository, ids of a GA4GH variant and read group are contained in the MolecularSequence resource. The URL of a GA4GH repository is an api_base of a GA4GH server that could be called for sequence data. The GA4GH variant set is a collection of call sets and the GA4GH call set is a collection of variant calls, typically for one sample. A variant call represents a determination of genotype with respect to that variant.

VariantSet definition: A VariantSet is a collection of variants and variant calls intended to be analyzed together.

CallSet definition: A CallSet is a collection of calls that were generated by the same analysis of the same sample.

A read group is a collection of reads produced by a sequencer. A read group set typically models reads corresponding to one sample, sequenced one way, and aligned one way. The API reference of Google Genomics is a GA4GH repository built by Google and provides details of the data models, such as the resource representations.

Usage Examples

Different way to represent sequence record with variations

We provide a detailed example to show how sequence resource can be used to represent record of observed sequence by different method.

MolecularSequence Graph

The diagram above describes 4 optional ways provided in the MolecularSequence resource to encode sequencing data. Here are the corresponding examples

Example from precision FDA

We provide one example to show how precision FDA vcf data can be upload and comform FHIR specification, and how quality in sequence resource is represented by comparison between a reference sequence and the observed sequence.

Source: XML, JSON, Turtle.

Complex Variation example

We provide one example to show how a complex variant can be represented with the help of cigar. The deletion, insertion and mutation is represented in characters along with the number of repetition.

Source: XML, JSON, Turtle.

Observation-genetics Profile

Structure Diagram

Description

The Observation-genetics profile Observation-genetics profile is used to interpret variants from sequence resource. Clinical usage may need more specific representation of variant at locus or structural variant in whole genome.

Some of the attributes of the profile follow:

Additional Observations instance will be created for variant's further analysis. For example, Observation.component element will be used for knowledge-based interpretations of the sequence variant. Here are some examples for the component.code.

LOINC Code LOINC Element Name Comments
51963-7 Medication Assessed A coded medication accessed in a pharmacogenetic test (recommend RxNorm).
51967-8 Genetic disease assessed A coded disease that is associated with the region of DNA covered by the genetic test (recommend SNOMED).
53037-8 Genetic Disease Sequence Variant Interpretation Interpretation of the pathogenicity of the DNA Sequence Variant in the context of the assessed genetic disease.
53040-2 Drug Metabolism Sequence Variant Interpretation Predicted phenotype for drug efficacy. A sequence variant interpretation value known to allow (responsive) or prevent (resistant) the drug to perform.
51961-1 Drug Efficacy Sequence Variant Interpretation Predicted phenotype for ability of drug to bind to intended site in order to deliver intended effect. A Sequence Variant interpretation value known to allow (responsive) or prevent (resistant) the drug to perform.

In the meantime, the related element in this Observation instance will point to Observaiton-genetics profile to show these clinical interpretations are further analysis for the variant. (For example, sequence variant has its pointer back to the observation, see PGx example)

Usage Examples

An Observation-genetics instance and its two related Observation instances for interpretations

We provide an example of an Observation-genetics instance which records a variant detected in the patient. (we call this example A)

Source: XML, JSON, Turtle.

An example of an Observation instance which records knowledge-based clinical interpretations for the variant represented in A.

Source: XML, JSON, Turtle.

An example of an Observation instance which records PCR validation test for the variant in A.

Source: XML, JSON, Turtle.

Phenotype, Diplotype and Haplotye

We provide the following examples to reveal how PGx data can be harmonized within the FHIR specification. Detailed discussion will be put here.

DiagnosticReport-genetics Profile

Structure Diagram

This DiagnosticReport-genetics is built on top of DiagnosticReport. The new profile is used to describe a genetics test report. The result element in DiagnosticReport will refer to the Observation resource that can lead to a bundle of genetic observations. The element of code, effective[x], issued, performer, request, specimen are be used to describe the details of the genetic test. Extensions about AssessedCondition and FamilyMemberHistory are added. Overall, this profile extends the DiagnosticReport resource to enable reporting of structured genetic test results. In addition, it denotes condition context for genetic testing, which may influence reported variants and interpretations for large genomic testing panels.

Examples for analysis.code:

LOINC Code LOINC Element Name Comments
51968-6 Genetic Disease Analysis Overall Interpretation Interpretation of all identified DNA Sequence variants along with any known clinical information for the benefit of aiding clinicians in understanding the results overall in either the context of diagnosis or increased risk of disease.
51964-5 Drug Efficacy Analysis Overall Interpretation Overall predicted phenotype for drug efficacy for all DNA Sequence Variants identified in a single case.
51971-0 Drug metabolism analysis overall interpretation Overall predicted phenotype for drug metabolism for all DNA Sequence Variants identified in a single case.

Usage Examples

An example of a genetic test report for a patient with FamilyHistory.

Source: XML, JSON, Turtle.

An example of a comprehensive bone marrow report.

Source: XML, JSON, Turtle.

ServiceRequest-genetics profile

Structure Diagram

A complex extension is added on top of the ServiceRequest resource. Here is the structure of the extension:

Description

To describe an order requested sequence variants detection. User must set up the code for the request and they can also refer to the corresponding sequence instance for that variant.

Usage Example

An order for genetics test

Here is a diagnostic request for testing 185delAG variant. The mother of the patient received results from a mutation panel (eg. MyRisk from Myriad) and she has a BRCA1 185delAG mutation. The clinician the would like to request to test the patient only for an 185delAG mutation. In this case, the diagnostic request for the patient will specify the sequence variant - 185delAG.

HLA genotyping results Profile

Human leukocyte antigen (HLA) genotyping is fundamental for research and clinical practice in immunogenetics and histocompatibility. Pointers to external locations refer to registered methods, raw NGS reads, and reference standards can be conveyed in this profile. Information about allele assignment including ambiguous results and the allele database used for assignments is stored in extensions.

The structure of the HLA typing report in this profile attempts to follow the principles outlined in the Minimum Information for ReportIng Next-generation sequence Genotyping (MIRING). These principles were identified through a series of meetings with international group of stakeholders in the application of Next Generation Sequencing (NGS) technology for genotyping the HLA and KIR loci as well as other immune-related loci (http://igdawg.org/ngs.html). MIRING describes eight principles, described in detail in Human Immunology. 2015 Dec; 76(12):954-962. These include detailed metadata about:

  1. MIRING Annotation
  2. Reference Context
  3. Full Genotype
  4. Consensus Sequence
  5. Novel Polymorphisms
  6. Platform Documentation
  7. Read Processing Documentation
  8. Primary Data
(see the publication above for details about each)

These principles were implemented in a technical specification by extending an existing XML based format for exchanging histocompatibility and immunogenetic genotyping data called Histoimmunogenetics Markup Language (HML) to include results from NGS methodologies (https://bioinformatics.bethematchclinical.org/hla-resources/hml/). The resulting schema may be found in https://schemas.nmdp.org/. The National Marrow Donor Program (NMDP)/Be The Match uses this format for reporting HLA genotyping from potential donors and for patients needing stem cell transplants.

Both MIRING and HML were used to inform mapping data elements to FHIR resources such as Patient, Specimen, MolecularSequence, Observation-Genetic Profile, and DiagnosticReport where possible. Several additional data elements were needed specifically for this use case, resulting in the development of a specific profile for reporting HLA genotyping results (Diagnostic Report Profile for HLA Genotyping Results).

Structure Diagram of HLA genotyping results Profile

Both hla-genotyping-results-glstring and hla-genotyping-results-haploid are complex extensions.

The development of these extensions were informed from the allele-assignment structure found in HML. While allele assignment for individual loci can be reported in an Observation, here they are used to summarize the assignments at a report level. Two methods may be used for reporting HLA allele-assignments: Haploid and GL String.

Structure of hla-genotyping-results-haploid:

Haploid reporting is a method that is used to report an individual allele, or a list of possible alleles if the results are ambiguous, using NMDP Multiple Allele Codes (MAC) which is a shorthand for describing allele ambiguity (https://bioinformatics.bethematchclinical.org/hla-resources/allele-codes/). MACs are widely used for reporting HLA typing results because they are able to report long allele lists in a small amount of space, but the system has a number of shortcomings (Tissue Antigens. 2013 Aug;82(2):106-12). When reporting data using haploid, typical use is one or two haploid elements for a particular locus, but possibly more if multiple loci are covered (ex: two HLA-DRB1 haploids + one HLA-DRB3 haploid).

Within Haploid, Method indicates whether the general methodology is DNA based typing (e.g., Sequence Specific Primers (SSP), Sequence Specific Oligonucleotide Probes (SSOP), or Sequence Based Typing (SBT)), or SER which indicates serology based methods.

Example of using two hla-genotyping-results-haploid extensions to report a HLA-A genotype of HLA-A*01:AB and HLA-A*02:MN which expands to HLA-A*01:01/HLA-A*01:02 and HLA-A:02:01/HLA-A:02:02/HLA-A:02:03

  <extension url="http://hl7.org/fhir/StructureDefinition/hla-genotyping-results-haploid" >
    <extension url=”locus”>
        <valueCodeableConcept>
            <coding>
                <system value="http://www.genenames.org"/>
                <code value="4931"/>
                <display value="HLA-A"/>
            </coding>
            <text value="HLA-A"/>
        </valueCodeableConcept>
    </extension>
    <extension url=”type”>
        <valueCodeableConcept>
             <coding>
                <system value="https://bioinformatics.bethematchclinical.org/hla-resources/allele-codes/"/>
                <code value="AB"/>
                <display value="01/02"/>
            </coding>
            <text value="HLA-A*01:AB"/>
        </valueCodeableConcept>
    </extension>
    <extension url=”method”>
        <valueCodeableConcept>
            <text value=”DNA”/>
        </valueCodeableConcept>
    </extension>
  </extension>
  <extension url="http://hl7.org/fhir/StructureDefinition/hla-genotyping-results-haploid" >
    <extension url=”locus”>
        <valueCodeableConcept>
            <coding>
                <system value="http://www.genenames.org"/>
                <code value="4931"/>
                <display value="HLA-A"/>
            </coding>
            <text value="HLA-A"/>
        </valueCodeableConcept>
    </extension>
    <extension url=”type”>
        <valueCodeableConcept>
             <coding>
                <system value="https://bioinformatics.bethematchclinical.org/hla-resources/allele-codes/"/>
                <code value="AB"/>
                <display value="01/02/03"/>
            </coding>
            <text value="HLA-A*02:MN"/>
        </valueCodeableConcept>
    </extension>
    <extension url=”method”>
        <valueCodeableConcept>
            <text value=”DNA”/>
        </valueCodeableConcept>
    </extension>
  </extension>

Because of limitations with MAC, another method called GL Strings was developed that encodes the results in a text string with hierarchical set of operators to describe the relationships between alleles, lists of possible alleles, phased alleles, genotypes, lists of possible genotypes, and multilocus unphased genotypes, without losing typing information or increasing typing ambiguity. (Tissue Antigens. 2013 Aug;82(2):106-12).

The structure of HLA-genotyping-results-glstring:

While the string format is easily parsed into separate components to be rendered for user viewing, GL Strings by themselves are potentially quite long and difficult to read. It often advantageous to point to a URI which may return the GL String on demand to avoid manual data entry. This is available through the URI element in this extension.

Example of using the hla-genotyping-results-glstring to report a GL String in both text and URI formats

  <extension url="http://hl7.org/fhir/StructureDefinition/hla-genotyping-results-glstring">
    <extension url=”text”>
        <valueString value="HLA-A*01:01:01:01/HLA-A*01:02+HLA-A*02:01:02/HLA-A*02:02:02/HLA-A*02:03:01"/>
    </extension>
    <extension url=”uri”>
        <valueUri value="https://gl.nmdp.org/imgt-hla/3.23.0/genotype/1h"/>
    </extension>
  </extension>

Whether reporting in Haploid or GL String formats, it is important to identify the version of the IMGT/HLA allele database, as new HLA alleles are constantly being discovered and allele assignment is based on the known alleles at the time, and so results may need to be reinterpreted later. This is done through the Allele Database element.

Structure of hla-genotyping-results-allele-database

Example of using hla-genotyping-results-allele-database to report using the IMGT/HLA database, version 3.23

  <extension url="http://hl7.org/fhir/StructureDefinition/hla-genotyping-results-allele-database">
    <valueCodeableConcept>
        <coding>
            <system value="http://www.ebi.ac.uk/ipd/imgt/hla"/>
            <version value="3.23"/>
        </coding>
        <text value="IMGT/HLA 3.23"/>
    </valueCodeableConcept>
  </extension>

Overall methodology may be reported using hla-genotyping-results-method. Here a codeable concept may be used to refer to method entered into a public registry, such as the NCBI Genetic Test Registry, or a local private registry.

Structure of hla-genotyping-results-method

Example of hla-genotyping-results-method to report a lab test registered in the NCBI Genetic Test Registry

  <extension  uri="http://hl7.org/fhir/StructureDefinition/hla-genotyping-results-method">
    <valueCodeableConcept>
          <coding>
              <system value="http://www.ncbi.nlm.nih.gov/gtr/"/>
              <code value="GTR000000000.0"/>
          </coding>
          <text value=”NGS based HLA-A genotyping”
    </valueCodeableConcept>
  </extension>

Usage Example

Example of a HLA genotyping report

Source: XML, JSON, Turtle.

In the above example, three Observations are referenced, each containing the details surrounding the genotyping of each gene/locus. Those observations would further refer to other observations (using Observation.related) that point to phased exon sequences which are the basis for individual allele assignment. This strategy is illustrated in the following figure for one gene, and sequencing two exons for each allele. Note that references from DiagnosticReport and Observation back to Patient/Donor and Specimen are not shown for clarity, although we would include them in the resource instances.

Phasing

Relationship among MolecularSequence resource and genetics profiles

Pointers to MolecularSequence resource

MolecularSequence resource is used to transmit and represent sequencing data. In FHIR Genomics, there are several genetics profiles containing internal pointers to MolecularSequence resource for genetic data reporting. Here is the summary:

MolecularSequence.pointer: A bundle of MolecularSequence instances can be connected by MolecularSequence.pointer to build sequence graph described in Section 3. MolecularSequence.pointer will point to the next sequence block.

MolecularSequence extension in Observation-genetics profile: Observation-genetics profile is used to report a genetic variant found in patients. MolecularSequence extension contains a pointer to MolecularSequence identifier which has related sequencing read info. It will provide reference/observed allele information and quality scores for each base/sequence block.

Pointer to Observation resource (based on genetics profile)

Observation-genetics based Observation resource is used for interpretative genetic data. MolecularSequence resource and genetics profiles will use internal pointers to Observation-genetics-profile based Observation instance for variant report.

MolecularSequence.observation: A pointer to genetics Observation instance which is used for interpretations of this sequence block. Interpretations are generally about genetic variant found in this sequence block.

DiagnosticReport.result: A pointer to Observation instance. This element is used for reporting genetic result.

Item extension in ServiceRequest-genetics profile: It is used to describe the genetic test order.

FamilyMemberHistory: A pointer to genetics Observation instance to report genetic test results of family member

Observation vs. MolecularSequence

MolecularSequence is used for raw sequencing data while genetic-profile-based Observation resource is used for reporting interpretative genetic information (eg. DNA/amino acid variant detected in the patient). Although both MolecularSequence and Observation-genetics profiles contain variant info, they are used differently: MolecularSequence.variant is used for encoding the sequence block; the Observation-genetics profile is mainly used for a variants test result or interpretations of raw data in MolecularSequence resource.

Usage example

This picture depicts the logical relationship among these resources. The definition of pointers are described above:

Here are the details and examples mentioned above.

Resource Details of data structures and pointers Links of resources example
MolecularSequence MolecularSequence Data Structure Example Here
Observation Observation Data Structure Example Here
ServiceRequest ServiceRequest Data Structure Example Here
DiagnosticReport DiagnosticReport Data Structure Example Here

Here is a specific use case to depict the whole story of FHIR in the clinical genomics setting: a ServiceRequest is requested, then a Diagnosticreport are reported. Two MolecularSequence instance, two Observation-haplotype instance, a Observation-diplotype and a Observation-phenotype for further interpretation are also created. (You can see the xml code and json code if you click the link.)

You can see the relationship among these resources in following picture:

HL7 Domain Analysis Use Cases

Simulated use of the proposed MolecularSequence resource and profiles on other FHIR resources are shown for many of the examples in Section 5 – Use Case Scenarios in the HL7 Domain Analysis Model (DAM): Clinical Genomics, Release 1, September 2014 Informative Ballot.

We show use of the FHIR design we are proposing for these cases:

  1. Specimen Identification
    1. Get references to all variants obtained from germline analysis.
    2. Explore antibacterial drug resistance over time (non-patient DNA)
  2. Clinical Sequencing – Germline Testing
  3. Cancer Profiling
  4. Decision Making Tools – Family History and Drug Dosage Calculators
    1. Today clinicians translate (i.e. manually re-enter) genetic data into tools for decision making. This includes family history tools and drug dosage calculators. In the future, this data will automatically be incorporated into clinical decision making tools.
    2. Get pharmacogenomic reporting and disease risk or diagnosis associated with variant
  5. Public Health
  6. Clinical and Research Data Warehouses

Specimen Identification

Get references to all variants obtained from germline analysis

GET   /Observation?
    _profile=http://hl7.org/fhir/StructureDefinition/observation-genetics&
    GenomicSourceClass=http://loinc.org|LA6683-2

*Return a bundle of genetics-profile-based Observation instances

Clinical Sequencing – Germline Testing

For a chart review, get references to all DNA sequences related to mutations with an interpretation “Unknown Significance”

GET /Observation?
    subject=123&
    component-code-value-[x]= http://loinc.org|53037-8$LA6682-4

53037-8: LOINC code for “Genetic disease sequence variant interpretation”

LA6682-4: LOINC answer code for “Unknown Significance”.

Cancer Profiling

The goal of this profile methodology is to get references from all variants obtained from somatic analysis. Changes in the population of cells with particular mutations will change overtime as well as in conjunction with events such as therapy. For instance, targeted chemotherapy may kill a specific population of cancer cells with specific mutations and other cancer cell populations may survive and continue to divide. Therefore, clearly annotating these specimens as somatic variants and capturing annotations related to a time relevant to a treatment timeline may be critical for analysis.

GET /Observation?
    _profile=http://hl7.org/fhir/StructureDefinition/observation-genetics&
    GenomicsSourceClass=http://loinc.org|LA6684-0&
    date=2015-07-04&
    subject=123

Decision Making Tools – Family History and Drug Dosage Calculators

Today clinicians translate (i.e. manually re-enter) genetic data into tools for decision making. This includes family history tools and drug dosage calculators. In the future, this data will automatically be incorporated into clinical decision making tools.

Get family history related to one observation:

GET /DiagnosticReport?
    _profile=http://hl7.org/fhir/StructureDefinition/diagnosticreport-genetic&
    subject=123

Get pharmacogenomic reporting and disease risk or diagnosis associated with variant

GET /Observation?
    _profile=http://hl7.org/fhir/StructureDefinition/observation-genetics&
    subject=123&
    Interpretation.component-code= http://loinc.org|51963-7

51963-7 : LOINC code for “Medication Assessed ”

Public Health

Today Registrars manually translate clinical data into public health reporting systems. This data is used to monitor and improve public health (e.g. surveillance and clinical research). In the future, this data will be extracted from the EHR in an automated (or semi-automated) fashion.

For a breast cancer clinical genomic study, get all genetic-profile-based observations of patients with breast cancer:

GET /DiagnosticReport?
    _profile=http://hl7.org/fhir/StructureDefinition/diagnosticreport-genetic&
    AssessedCondition.code=http://snomed.info/sct|254837009

Clinical and Research Data Warehouses

Health data warehousing should persist data in its standardized formats, while allowing users to export subsets of the data in the warehouse into multiple ‘data marts’, optimized for specific use cases, analysis type or reporting needs.

Get all genetic-profile-based observations of patients with the variant c.181T>G

GET /Observation?
    _profile=http://hl7.org/fhir/StructureDefinition/observation-genetics&
    DNAVariantID=http://www.ncbi.nlm.nih.gov/projects/SNP|rs58238560

Other Genomics Use Cases

During the development of the FHIR Genomics design, CGWG participants have commented on the earlier use cases and/or proposed new use cases. In this section, we list describe of these new cases and demonstrate how the proposed design will address them.

Get a patient’s family members genetics report

This example is proposed by Kevin Hughes. Family history is useful for clinicians to know more about the condition of the patient.

Get /FamilyMemberHistory?
    _profile=http://hl7.org/fhir/StructureDefinition/familymemberhistory-genetic&
    patient=123

Panel

Search for results from nephrotic syndrome panel

Get /DiagnosticReport&
    _profile=http://hl7.org/fhir/StructureDefinition/diagnosticreport-genetic&
    code=N0336&
    patient=123

Basic Queries

Find patients by condition and affected status

GET /Condition?
    component-code-value-[x]=http://snomed.info/sct|439401001

Find patients by phenotypical attribute

Get /Observation?
    =http://hl7.org/fhir/StructureDefinition/observation-geneticsGene&
    CodeableConcept=http://loinc.org|79716-7

79716-7: LOINC code for “CYP2C9 gene product metabolic activity interpretation”


Find patients by molecular data type available

Get /Observation?
    =http://hl7.org/fhir/StructureDefinition/observation-genetics&
    Interpretation.component-code=http://loinc.org|34193-3

34193-3: LOINC code for “SMPD1 gene mutations tested for in Blood or Tissue by Molecular genetics method Nominal"


Find patients by specific molecular marker (genomic region, position, gene, SNP)

Get /Observation?
    =http://hl7.org/fhir/StructureDefinition/observation-genetics&
    DNARegionName=NC_000017.10:g.497469T>A

53035-2: LOINC code for “DNA marker assessed"


Find mutation by mutation type and position

Get /Observation?
    =http://hl7.org/fhir/StructureDefinition/observation-geneticsVariant&
    Name=NM_000059.3:c.706C;A&
	Type=http://loinc.org|81289-1 

Find patients based on mode of inheritance (genomic region, position, gene, SNP)

Get /FamilyMemberHistory?
    _profile=http://hl7.org/fhir/StructureDefinition/familymemberhistory-genetic&
    reasonCode=http://snomed.info/sct|272398008

7272398008: SNOMED code for “ Inheritance types "


Search for patient by ID

Get /Patient?
    subject=123

Search for diagnostic reports with a given variant

GET /DiagnosticReport?
    _profile=http://hl7.org/fhir/StructureDefinition/diagnosticreport-genetics&
    geneticsAnalysis=http://www.ncbi.nlm.nih.gov/projects/SNP|rs58238560

Given diagnostic report, return associated family history information

GET /DiagnosticReport?
    _profile=http://hl7.org/fhir/StructureDefinition/diagnosticreport-geneticsFamilyMemberHistory&
    id=123

Search for variants given gene and variant classification

GET /Observation?
    =http://hl7.org/fhir/StructureDefinition/observation-genetics&
    Gene=http://www.genenames.org|3236&
	GenomicSourceClass=http://loinc.org|LA6684-0

Search for patients based on genetic ancestry

GET /Observation?
    =http://hl7.org/fhir/StructureDefinition/observation-genetics&
    Ancestry=http://www.genenames.org|186044009
	GenomicSourceClass=http://snomed.info/sct|LA6684-0

Boolean Queries

Find all patients with a set of variants

GET /Observation?
    _profile=http://hl7.org/fhir/StructureDefinition/observaiton-genetics&
    DNAVariantID=http://www.ncbi.nlm.nih.gov/projects/SNP|rs58238560$rs58238559$rs58238565

rs58238560: variant: NC_000017.10:g.497469T>A

rs58238559: variant: NC_000007.13:g.87082273T>C

rs58238565: variant: NC_000005.10:g.131929452C>A


Specimen-based Queries

Find specimens collected from specific specimen body sites

GET /Specimen?
   bodySite=http://snomed.info/sct|85151006

Find specimens from this patient's pedigree

Get /FamilyMemberHistory?
    =http://hl7.org/fhir/StructureDefinition/familymemberhistory-genetic&
    patient=123

Find specimens based on patient disease status

Get /DiagnosticReport?
    =http://hl7.org/fhir/StructureDefinition/diagnosticreport-genetic&
    AssessedCondition.code=http://snomed.info/sct|254837009&
    patient=123

Find specimens based on specimen disease status

Get /Specimen?
    status=available&

Find specimens based on technology platform

Get /Specimen?
    =http://hl7.org/fhir/StructureDefinition/shareablecodesystem&
    code=Information Technology

Find specimens based on instrument identifier

Get /Specimen?   
    container.identifier=48736-15394-75465

Time-based Queries

Find specimens collected within an absolute date range

Get /Specimen?   
    receivedTime=2011-03-04T07:03:00Z

Find specimens collected within a relative date range

Get /Specimen?
    =http://hl7.org/fhir/StructureDefinition/specimen-treatmentTime&   
    duration=quot

MolecularSequence Test Metrics

Clinical Genomic Apps

The idea for a MolecularSequence resource grew out, in part, the SMART Platforms Project, which explored creating clinical genomic apps to integrated traditional EMR clinical data and genomic data to show data visualization and analysis, including CDS that depended upon both types of data. Below are a couple of examples. Several apps have already been designed including Genomics Advisor, SMART Precision Cancer Medicine, and Diabetes Bear EMR. Below, one of these apps will be described. To include other apps in this section, please feel free to add a note on it and how it uses FHIR/Genomics calls.

Genomics Advisor

The SMART on FHIR Genomics Advisor was an app incorporating genomics data to show risk of disease, drug susceptibility, and related conditions based upon genotype. Technically, this app was architected (see below) by combining data from independent data services, a SMART on FHIR clinical server for clinical information and one for a SMART on FHIR Genomics data server for genomic data. The set of FHIR API calls that are necessary to support this app are shown below:

The presentation of the app looks like this:

Appendix 1: From DSTU2 Genomics to STU3

The table shows how the data elements in the DSTU2 Observation resource as extended by the Standard Genetics Profile would be mapped to the new MolecularSequence resource.

DSTU2 Standard Genetics profile on Observation Observation-genetics profile Maps to MolecularSequence (Proposed)
geneticsGenomeBuild MolecularSequence extension referenceSeq.genomicsBuild
geneticsChromosome MolecularSequence extension referenceSeq.chromosome
geneticsGenomicsStart MolecularSequence extension variant.start
geneticsGenomicsStop MolecularSequence extension variant.end
geneticsReferenceAllele MolecularSequence extension variant.referenceAllele
geneticsObservedAllele MolecularSequence extension variant.observedAllele
geneticsSpecies MolecularSequence extension specimen
geneticsAllelicState Allelic State extension
geneticsAllelicFrequency Allelic Frequency extension
geneticsReadCoverage MolecularSequence extension readCoverage
geneticsCopyNumberEvent Copy number event extension
geneticsTranscriptReferenceSequenceId Transcript reference sequence identifier extension
geneticsProteinReferenceSequenceId Protein reference sequence identifier
geneticsCIGAR MolecularSequence extension variant.cigar
geneticsVariationId DNA variation id extension
geneticsVariationType DNA sequence variation type extension
geneticsAminoAcidChange Amino acid change extension
geneticsAminoAcidChangeType Amino acid change type extension
geneticsGene Gene extension
geneticsDNARegionName DNA region name extension
geneticsGenomicSourceClass Genomic source class extension

glossary.html

Language Glossary

Maturity Level: N/AStandards Status:Informative

This page lists a set of words and acronyms that this specification uses in a particular way that might not be inherently obvious from their english definition. These words often present a challenge when describing/documenting FHIR in a language other than english. This pages contains suggested alternatives for these words in some languages where implementers have asked for such support. To add additional languages to this page, ask on http://chat.fhir.org

English Portuguese
FHIR = Fast Healthcare Interoperability Resources
Accept Aceitar
Authentication Autenticação
Authorization Autorização
Client Cliente
Conformance Conformidade
Connectathon Connectathon
Content-Type Tipo de Conteúdo
Create Criar
Delete Remover
Documents Documentos
Extensibility Extensibilidade
History Histórico
Implementers Implementadores
Interface Interface
Interoperability Interoperabilidade
JSON JSON
Messages Mensagens
Metadata Metadados
Ontology Ontologia
Operation Operação
Profile Perfil
RESTful API RESTful API
Read Ler
Request Pedido
Resource Recurso
Resource Instance Instância do recurso
Resource Type Tipo de Recurso
Response Resposta
Search Pesquisa
Server Servidor
Specification Especificação
Standard Standard
Transaction Transação
URL URL
Update Actualizar
Version Versão
XHTML XHTML
XML XML

graphql.html

Using GraphQL with FHIR

Maturity Level: 0Standards Status:Trial Use

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. This page describes how to use GraphQL with FHIR. The GraphQL interface may be implemented by any server, and may be provided as a facade service in front of a conformant RESTful API. For GraphQL documentation, see http://graphql.org.

This page is a draft. For ongoing discussion, see chat.fhir.org.

Status of GraphQL

Implementers should note that GraphQL is not a formal standard, and no standards path has been dscribed for it. At present, GraphQL is copyright by Facebook, and licensed under a standard BSD-3 license. The GraphQL language is still under development.

Invoking GraphQL

The standard end points for graphQL are as defined on the $graphql operation:

[base]/$graphql

A System level query. The query must start by selecting a resource type and some search criteria, as defined below.

[base]/[Type]/[id]/$graphql

A Resource Instance level the query assumes a single resource is in scope, and just queries on the data available in the given resource.

GraphQL can be invoked by get with a query parameter, or a POST with the graphQL as the body, or a JSON body. (see the GraphQL documentation).

The mime type of the response is application/json. Other formats are not described by the specification. The mimetype is *not* application/fhir+json - the response is not a FHIR resource, though it may look like one closely.

Conformance

Servers that conform to FHIR/GraphQL specification:

Note that most servers only provide a subset of the full functionality described by the FHIR interface. Where servers support FHIR features, and implement GraphQL, they must make them available as defined by this page, but these rules do not require that servers implement all (or even any) of the functionality defined here. Also, these rules do not prevent servers providing additional end-points, queries or mutations that provide additional functionality.

Error Handling

With regard to handling errors, FHIR GraphQL servers:

A graphQL error response with an OperationOutcome looks like this:

{
  "data": null,
  "errors": [
    {
      "extensions": {
        "resource" : {
          "resourceType": "OperationOutcome",
          "issue": [
            {
              "severity": "error",
              "code": "exception",
              "diagnostics": "500: Internal server error"
            }
          ]
        },
      },  
      "message": "500: Internal server error"
    }
  ]
}

The error response SHALL include at least one error. Each error SHALL include a message, and MAY include the graphQL locations and path properties. Each error SHOULD include an OperationOutcome in the resource property in the graphQL extensions element. Note that in this usage, there MAY be multiple OperationOutcome, one for each errors item, with one issue matching the message.

Field Selection

Any FHIR defined field can be used directly e.g. this graphql against the Patient resource (r3)

 { 
  name { text given family } 
 }

Example: http://test.fhir.org/r3/Patient/example/$graphql?query={name{text,given,family}} (note: examples are only informative).

Polymorphic fields are represented by their JSON property name E.g. for Observation.value[x]:

 { 
  valueQuantity { value unit } 
 }

Example: http://test.fhir.org/r3/Observation/example/$graphql?query={valueQuantity{value,unit}} (note: examples are only informative).

Note: This is because the leaf names have to correspond to scalar types, so there is no use selecting all the variants at once

Extensions on primitives: the JSON convention for primitives is observed. e.g. use _[name] for accessing extensions on primitives. So

 {
  birthDate _birthDate { extension {valueDateTime} } 
 }

results in

 {
  "birthDate":"2016-05-18",
  "_birthDate":{
    "extension":[{
      "valueDateTime":"2016-05-18T10:28:45Z"
     }]
  }
 }

Example: http://test.fhir.org/r3/Patient/example/$graphql?query={birthDate,_birthDate{extension{valueDateTime}}} (note: examples are only informative).

Field Arguments: List Navigation

Primitive fields SHALL NOT have any arguments at all. Complex fields may have one of more of the following parameters, all of which help select a subset of a repeating element:

FHIRPath:

Use a FHIRPath statement selecting which of the set of notes in a list is to be included:

 { 
  name(fhirpath: "family.exists()") { text given family } 
 }

Example: http://test.fhir.org/r3/Patient/example/$graphql?query={name(fhirpath:%22family.exists()%22){text,given,family}} (as compared to http://test.fhir.org/r3/Patient/example/$graphql?query={name{text,given,family}}) (note: examples are only informative).

Field Filter:

Not all systems support FHIRPath, so a simpler syntax is provided, where the client specifies a single sub-element by name, and a specified value that must be matched for the field to be included:

 { 
  name(use: official) { text given family } 
 }

Example: http://test.fhir.org/r3/Patient/example/$graphql?query={name(use:official){text,given,family}} (note: examples are only informative).

One way this can be used is to select particular extensions:

 { 
  myext: extension(url: "http://myextension.url/details") { value : valueString } 
 }

will result in

 {
  "myext" : {
    "value" : "some value"
   }
 }

List offsets: _offset and _count

For some large resources, it may be desired to select only a subset of a long list of elements, and to make repeated requests reading further into the list as long as required. This can be done with the _count and offset filters:

 { 
  entry(_count: 5, _offset: 5) { deleted item { reference } } 
 }

Example: http://test.fhir.org/r4/List/long/$graphql?query={entry(_count:5,_offset:5){deleted item{reference}}} (note: examples are only informative).

This will select the second set of 5 entries in the nominated List resource. Clients can use this approach to iterate through a list. If a filter is applied to this (as documented above), the offset and count apply to the filtered list. Clients would iterate the list until there are no more entries returned.

Additional Selectors

Resource references

An object of type Reference can have an additional selection resource. This is an instruction to the server to resolve the reference, and then include the contents of the resource as specified by sub-selections in the property name "resource" (can be aliased). e.g. On Observation:

 { 
   subject { reference, resource {active} } 
 }

The resource selector has two arguments:

Example: http://test.fhir.org/r4/Observation/example/$graphql?query={id,subject{reference,resource{...on%20Patient{birthDate}...on%20Practioner{practitionerRole{speciality}}}}code{coding{system,code}}} (note: examples are only informative).

but slightly denser:

 { 
  id
  subject { 
   reference
    resource(type : Patient) { birthDate }
    resource(type : Practioner) { practitionerRole {  speciality } }
  }  
  code {coding {system code} }
 }
 

Example: http://test.fhir.org/r4/Observation/example/$graphql?query={id,subject{reference,resource(type:Patient){birthDate}resource(type:Practioner){practitionerRole{speciality}}}code{coding{system,code}}} (note: examples are only informative).

Clients can use either approach - type selection as a parameter, of using a fragment type condition - the first is shorter while the second aligns with the GraphQL schema more explicitly.

Searching resources

When a GraphQL statement is run at the system level, rather than against a particular resource, the first thing the query must do is select the resource(s) of interest. The logic of this follows the FHIR search API, but reimplements in a GraphQL centric way.

There are 3 ways to query, for a single resource, for a simple list of resources, and a full API. For a single resource, the client names the type of the resource, and provides an id:

 { 
   Patient(id: example) { id, active } 
 }

This returns a single Patient with the name id. The output from this is a single resource:

 {
   "data" : {
     "Patient" { 
       "id" : "example",
       "active" : "true",
     }
   }
 }

Example: http://test.fhir.org/r4/$graphql?query={Patient(id:example){id,name{given,family}}} (note: examples are only informative).

Alternatively, the client can ask for a list of resources. Here, the client simply asks for a list of resources:

 { 
   ConditionList(clinical_status: relapse, patient: example) { id, clinicalStatus } 
 }

This is a request to list all the Condition resources that have a status if 'relapsed' for the patient with id = example. The arguments are most of the search parameters defined on or for the specified resource. Notes:

The output of this is a list:

 {
   "data" : {
     "ConditionList" : [{ 
       "id" : "100",
       "clinicalStatus" : "relapse"
     },{ 
       "id" : "100",
       "clinicalStatus" : "relapse"
     }]
   }
 }

Example: http://test.fhir.org/r4/$graphql?query={PatientList(name:%22pet%22){name{family,given}}} (note: examples are only informative).

Servers may reject the request if there are too many matches to return in a single request. If they do so, they SHALL return an error indicating that the query could not be fulfilled. (rather than silently filtering the list).

The simple list approach does not allow for the management of long lists. To do this, clients are able to request a Connection based approach (based on http://graphql.org/learn/pagination/, but adapted to the existing FHIR Search API).

 { 
   ConditionConnection (clinical_status: active, patient: example) { 
     count offset pagesize
     edges {
       mode, score, resource { id, active }
     }
     first previous next last
   } 
 }

The arguments are the same as for the simple List case, with the addition of the special argument 'cursor' (see below). The server returns a connection object that contains information about the search, along with a list of 'edges', one for each match. Each edge has 3 properties: mode, score (match the same properties on Bundle.entry.search) and "resource" which is the actual matches.

 {
  "data" : {
    "ConditionConnection" : {
      "count": 50,
      "offset" : 0,
      "pageSize" : 25,
      "next" : "45f9ada8-db37-4498-ba7d-75a044668387:3"
      "edges" : [{
         "resource" : { 
           "id" : "100",
           "clinicalStatus" : "relapse",
         }
     },{ 
       "resource" : {
         "id" : "100",
         "clinicalStatus" : "relapse",
        }
     }]
   }
  }
 }

Example 1: http://test.fhir.org/r4/$graphql?query={PatientConnection(name:%22pet%22){count,offset,pagesize,first,previous,next,last,edges{mode,score,resource{name{family,given}}}}} (note: examples are only informative).

Example 2 (cursor): http://test.fhir.org/r4/$graphql?query={PatientConnection(){count,offset,pagesize,first,previous,next,last,edges{mode,score,resource{resourceType,id,name{family,given}}}}}}}} (note: examples are only informative).

Notes:

The client can follow up on the first/previous/next/last links using the argument 'cursor':

 { 
   ConditionConnection (_cursor : "45f9ada8-db37-4498-ba7d-75a044668387") { 
     count offset pagesize
     edges {
       id, clinicalStatus
     }
     first previous next last
   } 
 }

Example: http://test.fhir.org/r4/$graphql?query={PatientConnection(cursor:%225b0719b5-0f01-442e-9576-5b0514c19a:50%22){count,offset,pagesize,first,previous,next,last,edges{mode,score,resource{resourceType,id,name{family,given}}}}}}}} (note: examples are only informative). (note, though, that to make this one work, you have to replace the cursor token with one that you got from the link above).

Notes:

List vs Connection Searches

The specification defines the 2 forms of searches to meet differing requirements. For the List search:

In general, clients should use the simple search, for efficiency purposes, where appropriate (e.g. where the user is not going see a 'next' button). This particularly applies when doing reverse reference resolution.

Reverse References

It's also possible to use search is a special mode, doing reverse lookups - e.g. list all the resources that refer to this resource. An example of this use is to look up a patient, and also retrieve all the Condition resources for the patient.

This is a special case of search, above, but with an additional mandatory parameter _reference. For example:

 {
   name { [some fields] }
   ConditionList(_reference: patient) {
    [some fields from Condition]
   }
 }

There must be at least the argument "_reference" which identifies which of the search parameters for the target resource is used to match the resource that has focus. In addition, there may be other arguments as defined above in search (except that the "id" argument is prohibited here as nonsensical)

The response for the query above would be

{
  "name: [ [some fields] ],
  "ConditionList" : [
    { [some fields from matching Condition resource] }
  ]
}

Example: http://test.fhir.org/r4/Patient/example/$graphql?query={name{family,given}ConditionList(_reference:patient){id,clinicalStatus}} (note: examples are only informative).

The "connection" based search option is also supported, as described above, with the addition of _reference. If the client wishes to pursue any of the cursor based links in the graphQL results it asks for back, then it initiates this a new separate query as defined above, rather than repeating the nested query. I.e. the 'cursor' argument is prohibited, except at the root of query.

Example: http://test.fhir.org/r4/Patient/example/$graphql?query={name{family,given}ConditionConnection(_reference:patient){count,offset,pagesize,first,previous,next,last,edges{mode,score,resource{...onCondition{resourceType,id,clinicalStatus}}}}} (note: examples are only informative).

Operations

It's also possible to apply graphql to the results of other operations. This is done by adding the parameter "_graphql" when invoking the operation. e.g.

  GET [base]/ValueSet/doc-typecodes/$validate-code?system=http://loinc.org&code=1963-8&display=test&_graphql={result:parameter(name:"result"){value:valueBoolean}}

Example: http://test.fhir.org/r4/ValueSet/doc-typecodes/$validate-code?system=http://loinc.org&code=1963-8&display=test&_graphql={result:parameter(name:%22result%22){value:valueBoolean}} (note: examples are only informative).

The graphQL is executed on the output of the operation. If the operation fails, and returns an operation outcome, then the graphQL is not executed.

Data Flattening Directives

GraphQL is a very effective language for navigating a graph and selecting subset of information from it. However for some uses, the physical structure of the result set is important. This is most relevant when extracting data for statistical analysis in languages such as R. In order to facilitate these kind of uses, FHIR servers should consider supporting the following directives that allow implementers to flatten the return graph for easier analysis

Flattening a node

@flatten

This directive indicates that the field to which it is attached is not actually produced in the output graph. Instead, its children will be processed and added to the output graph as specified in its place.

Notes:

For an example, take this graphQL, and apply it to the patient example:

{
  identifier { system value }
  active 
  name { text given family } 
}

This will give the output:

{
  "identifier": [{
      "system": "urn:oid:1.2.36.146.595.217.0.1",
      "value": "12345"
  }],
  "active": true,
  "name": [{
    "given": ["Peter","James"],
    "family": "Chalmers"
  },{
    "given": ["Jim"]
  },{
    "given": ["Peter","James"],
    "family": "Windsor"
  }]
}

Adding the @flatten directive changes the output:

{
  identifier @flatten { system value }
  active 
  name @flatten { text given family } 
}

This has the output:

{
  "system":["urn:oid:1.2.36.146.595.217.0.1"],
  "value":["12345"],
  "active":true,
  "given":["Peter","James","Jim","Peter","James"],
  "family":["Chalmers","Windsor"]
}

Short cut for selecting only the first element

@first

This is a shortcut for a FHIR path filter [$index = 0] and indicates to only take the first match of the elements. Note that the selection of the first element only applies to the immediate context of the field in the source graph, not to the output graph

Example:

{
  identifier @flatten { system value }
  active 
  name @flatten { text given @first family } 
}

Gives the output:

{
  "system":["urn:oid:1.2.36.146.595.217.0.1"],
  "value":["12345"],
  "active":true,
  "given":["Peter","Jim","Peter"],
  "family":["Chalmers","Windsor"]
}

Managing output cardinality

@singleton

This directive indicates that an field collates to a single node, not a list. It is only used in association with fields on which a parent has @flatten, and overrides the impact of flattening the parent in making it a list. The server SHALL return an error if there is more than one value when flattening

Extending the previous example, adding @singleton:

{
  identifier @flatten { system @singleton value @singleton }
  active 
  name @flatten @first { text given family @singleton } 
}

Gives the output:

{
  "system":"urn:oid:1.2.36.146.595.217.0.1",
  "value":"12345",
  "active":true,
  "given":["Peter","James"],
  "family":"Chalmers"
}

Converting Lists to singletons

@slice(fhirpath)

This indicates that in the output graph, each element in the source will have "." and the result of the FHIRPath as a string appended to the specified name. This slices a list up into multiple single values. For example

{ name @slice(path: "$index") @flatten {given @first @singleton family}}

For a resource that has 2 names will result in the output

{
"Given.0" : "first name, first given",
"Family.0" : ["first name family name"],
"Given.1" : "second name, first given",
"Family.1" : ["second name family name"]
}

Other uses might be e.g. Telecom @slice(use) to generate telecom.home for instance.

Notes:

Examples:

{
  identifier @flatten { system value }
  active 
  name @flatten @slice(path: "use") { given family @singleton } 
}

produces

{
  "system":["urn:oid:1.2.36.146.595.217.0.1"],
  "value":["12345"],
  "active":true,
  "given.official":["Peter","James"],
  "family.official":"Chalmers",
  "given.usual":["Jim"],
  "given.maiden":["Peter","James"],
  "family.maiden":"Windsor"
}

and

{
  identifier @flatten { system value }
  active 
  name @flatten @slice(path: "$index") { given family @singleton } 
}

produces

{
  "system":["urn:oid:1.2.36.146.595.217.0.1"],
  "value":["12345"],
  "active":true,
  "given.0":["Peter","James"],
  "family.0":"Chalmers",
  "given.1":["Jim"],
  "given.2":["Peter","James"],
  "family.2":"Windsor"
}

Mutations

Mutations are defined for the operations Create, Update, and Delete.

Create:

 PatientCreate(res : Patient) {
   returns a Patient 
 }

Like the API, the Patient resource might or might not have an ID; if it is present, the value is overwritten by the server.

Update:

 PatientUpdate(id : ID, res : Patient) {
   returns a Patient 
 }

Delete:

 PatientDelete(id : ID) {
   [no return]
 }

The parameters are input types that are resources that exactly match the output types. If these operations fail, an http error is returned.

Todo: mutations for patch, batch, transaction?


help.html

Glossary

FHIR Infrastructure Work GroupMaturity Level: N/AStandards Status: Informative

This page will be the FHIR Glossary, but it has not, as yet, been created.

Looking for volunteers to take this on...


history.html

Version History since DSTU #1

FHIR Infrastructure Work GroupMaturity Level: N/AStandards Status: Informative

For background to this version history, see FHIR Version Management Policy.

Major Milestones:

Feb 21, 2017 3.0.1 Release 3 (STU - Standard for Trial Use)
Oct 24, 2015 1.0.2 DSTU2 (Second Draft Standard for Trial Use)
Sept 30, 2014 0.0.82 DSTU1 (First Draft Standard for Trial Use)

This is the developmental version of FHIR. The only changes tracked here are the changes made after the publication of the first DSTU release. For earlier changes, see the DSTU #1 Version History. Note that a full archive history of everything is available through the HL7 GitHub archives.

Version Changes
3.6.0 Current build after 3.5.0 release
3.5.0

Release R4 Ballot #1: Sept 20, 2018. R4 ballot #2

Major changes from R4 Ballot 1 (3.3.0):

Description Committee + Tasks Pages
All Ballots
Change the canonical URL for all v2 and v3 CodeSystems and ValueSets (and some FHIR ones too), to
http://terminology.hl7.org (from the Unified Terminology Process) Breaking change!
(no task: Vocab committee decision) todo
Normative / Infrastructure
Added reference.typeFHIR-I:
Clarify definition of is-modifier + impacts on modifier extensions. Note: this lead to breaking changes
on a few extensions (changed from modifierExtension to normal extension)
FHIR-I:
Add mode parameter to /metadata FHIR-I:
Enhance/extend rules around changes between versionsFHIR-I:
Add fhirVersion parameter to application/fhir mime type FHIR-I:
Add the $versions operationFHIR-I:
Allow exponential form for decimals (with corresponding consequences for precision) FHIR-I:
Describe use of exponential form when searching numbers (+ clarifications for precision) FHIR-I:
Remove support for operations on historical resources Breaking change! FHIR-I:
Change Money Type to make it simpler Breaking change! FHIR-I:
Change ElementDefinition.binding.valueSet to only be of type canonical Breaking change! FHIR-I:
Remove restriction on Bundle containing multiple versions of the same resource Breaking change! FHIR-I:
Rename Binary.content to Binary.data and exclude it from summary (which makes it optional) Breaking change! FHIR-I:,
Normative / Conformance + Terminology
Remove ValueSet.$expand profile parameter, and add parameters from ExpansionProfile Breaking change! Vocab: &
Remove ValueSet.$expand.limitedExpansion parameter, and document how to use count instead Breaking change! Vocab:
Move Valueset.extensible to an extension Vocab:
Add CapabilityStatement.implementation.custodian FHIR-I:
Add CapabilityStatement.imports FHIR-I:
Normative / Observation
Update definition of subject and add note safety page the focus element OO:
Changed cardinality of Observation.interpretation and
Observation.component.interpretation from 0..1 to 0..*
OO:
Changed Observation.context to Observation.encounter with type Reference(Encounter). Breaking change! OO:

This is only the major changes. More comprehensive lists can be found in the ballot introduction (later removed).

Major changes in the other parts of the specification:

3.4.0 Current build after 3.3.0 release
3.3.0

Release R4 Ballot #1: Apr 3, 2018. R4 ballot #1. Major changes from R3:

3.2.0

Release R4 Draft: Dec 21, 2017. R4 draft ballot. Major changes:

3.1.0 R4 development begins
3.0.0

Release 3: Mar 21, 2017. STU3

This is the full FHIR Release 3 (R3). R3 is a complete overhaul of the specification from R2, with over 2400 change proposals process, and applied in R3. Of those changes, 380+ are labeled as a breaking change. Given this level of change, there is no useful way to present a single change list. Users can use the R2/R3 difference comparison, the R2 <-> R3 transforms, or the "Compare to R2" link at the foot of every page to help visualise the differences between R2 and R3.

Many of the changes made in this release (since 1.8.0) are in response to Quality Assurance processes in HL7, with a goal of readying the specification for Normative processes in R4:

Roll up: Of all the many changes (thousands) between R2 and R3, these are the most significant:

1.9.0

FHIR Rolling Build, 2016 Dec onwards

1.8.0

FHIR QA Release, Dec 6, 2016

STU 3 Candidate, and also the basis for several implementation guide ballots and the San Antonio Jan 2017 Connectathon

Breaking Changes Summary:

These are only the more significant changes, there were many 100s of changes made in response to ballot comments and ongoing implementation experience. These include breaking changes to may resources. Structural changes are summarized here, and Transforms between DSTU 2 and STU 3 are provided for many resources.

1.6.0

FHIR STU3 ballot, Aug 11, 2016

STU 3 ballot version, and also the basis for the Baltimore Sept 2016 Connectathon

Publication Changes:

  • Move the US Realm implementation guides out of the specification (see http://www.fhir.org/guides/registry)
  • Rework the home page, and introduce modules as a way to navigate the specification + add significant new implementer advice (e.g. "Getting Started")
  • Change the Navigation menu to focus on indexes to the content in the specification
  • Move FHIRPath expression language to its long term home

Technical Changes:

  • RESTful API
    • Change the FHIR mime type to application/fhir+xml|json instead of application/xml|json+fhir (breaking change, for conformance to W3C+IETF rules)
    • Add new uses for the Prefer header (return OperationOutcome, and manage behavior related to unknown / unsupported search parameters
    • Deprecate use of the OPTIONS command to retrieve the CapabilityStatement
    • Add support for conditional references to the transaction interaction
    • Add reverse chaining
  • Formats: No change to XML + JSON formats. Add Turtle Format, and related validation tools
  • For Data Types and Resources, there is formal difference analysis from DSTU2 (also found throughout the specification), and transforms between DSTU 2 and STU 3 are provided for many resources
1.5.0

FHIR Current Build Update, July 8 2016

Update current version to 1.5 to prevent confusion with implementations still running the May 2016 version.

  • There are many changes in this version from 1.4.0, but no formal list is provided. A formal list will be provided for 1.6 (as a diff to 1.4)
1.4.0

FHIR Connectathon 12 Snapshot, Mar 30 2016

Frozen base for Connectathon 12 & For Comment ballots:

1.2.0

FHIR Connectathon 11 Snapshot, Dec 11 2015

Frozen base for Connectathon 11:

  • Remove GuidanceRequest
  • Add new draft resources: MolecularSequence, ExpansionProfile
  • Modifications to Financial Resource & TestScript resource

Note: this version is temporary, and was removed after Connectathon 11 was complete

1.1.0

GAO Ballot + technical corrections, Dec 2 2015

A ballot publication for the GAO Ballot that also includes:

  • Various technical corrections to the generated snapshots
  • Populate FHIRPath expressions in extensions for all search parameters and invariants
  • Add new draft resources: GuidanceRequest, GuidanceResponse, ModuleMetadata, ModuleDefinition, Library, DecisionSupportServiceModule, DecisionSupportRule, OrderSet, Measure
  • Major restructure of Questionnaire
1.0.2

Technical Correction 1, Oct 24 2015

A series of technical corrections to the specification following extensive review:

  • Corrections to Extension cardinalities in implementation guides
  • Corrections in the conformance resources that support the specifications
  • Correct several erroneous invariants
  • Various typos, broken links, and fixes in examples
  • For a comprehensive list of corrections, see the Task list for FHIR DSTU2 Technical Correction 1
1.0.1

DSTU 2, Sept 23 2015

Changes of significance during the QA process:

  • Remove the Clinical Quality Improvement Framework (CQIF) from this published version
  • made fixes to generated schematrons
  • updated generated comformance resources (StructureDefinitions and SearchParameters) so they were consistent with the specification
  • Many spelling / grammar / broken link fixes
1.0.0

DSTU 2 QA Preview, Aug 31 2015

This version had extensive change as a result of the May 2015 DSTU ballot, ongoing testing, and the open change proposals (1317 tasks). The extent of the changes is best illustrated by the number of the list of changes labeled 'breaking change' - 158 changes of 1317 total tasks. Below is a list of the most important changes:

0.5.0

DSTU Ballot, May 2015

This version had extensive change as a result of the January 2015 Draft ballot, ongoing testing, and the open change proposals (over 800 tasks). The list below is a summary of the major changes to resource content. It shows only a limited number of the overall changes.

Enumerations

  • All spaces removed
  • Extensive content changes not noted here

New Data Types

Changed Data Types

  • Coding - remove valueSet property
  • Attachment - add creation
  • Identifier - replace label with type
  • Timing - major rework of content
  • ElementDefinition - add label, code, rename 'formal' to definition, rename synonym to alias, add language to mapping, remove conformance and isExtensible and replace with strength

New Resources

Removed Resources

  • CarePlan2 -> collapsed into CarePlan
  • FamilyHistory -> broken up into FamilyMemberHistory
  • InstitutionalClaim, OralHealthClaim, PharmacyClaim, ProfessionalClaim, VisionClaim -> collapsed into Claim
  • Other - use Basic instead
  • PendedRequest,Readjudicate, Reversal, StatusRequest, StatusResponse - use ProcessRequest/Response instead
  • SupportingDocumentation - use DocumentManifest instead
  • ProcessRequest, ProcessResponse - use Task instead

Renamed Resources

  • Alert -> Flag: 'alert' made people think it was an action like an alarm
  • SecurityEvent -> AuditEvent: it wasn't just for security purposes
  • ClinicalAssessment -> ClinicalImpression: people got confused with 'assessment' tools like APGAR score
  • Profile -> StructureDefinition: 'Profile' is the process, a package of statements

Changes Inside Resources

  • Parameters - allow parameter.part to contain a resource
  • AllergyIntolerance - rename subject to patient
  • Appointment - remove lastModifiedBy/lastModified, add location
  • AppointmentResponse - remove lastModifiedBy/lastModified, add rename individual to actor
  • AuditEvent - add .event.purposeOfEvent, participant.location, .policy, and .purposeOfUse
  • Bundle - major reorganization
  • CarePlan - pull goal out + other reorganization
  • ClinicalImpression - add status, replace careplan & referral with trigger, rename diagnosis to finding, make plan 0..*,
  • Composition - change .section.content to refer to List only, not any
  • ConceptMap - change identifier to url, add useContext, change telecom to contact,
  • Condition - rename subject to patient, rename status to clinicalStatus, change to bodySite = code or Reference(BodySite), rename .codeableConcept to .code
  • Conformance (now CapabilityStatement) - change identifier to url, add useContext, change telecom to contact, add requirements and copyright, add support for conditional operations,
  • Contract - extensive rewrite
  • Coverage - add bin, subscriberId
  • DataElement (now StructureDefinition) - total rewrite to use ElementDefinition
  • Device - add status, manufactureDate
  • DeviceMetric - rename operationalState to operationalStatus, add measurementMode, rename calibrationInfo to calibration, change color to an enumerations
  • DeviceRequest/DeviceUseStatement - change to bodySite = code or Reference(BodySite)
  • DiagnosticRequest- change to bodySite = code or Reference(BodySite)
  • DiagnosticReport - add encounter
  • DocumentManifest - add options for how content is referred to
  • DocumentReference - add format, remove policyManager, make content : Attachment, and remove several related attributes, remove service reference and add context.practiceSetting, sourcePatientInfo, and related
  • Encounter - add incomingReferralRequest, allow reason to repeat, rename diet to dietPreference
  • EpisodeOfCare - rename currentStatus to status, allow referralRequest to repeat,
  • Flag - rename subject to patient, change from note to code
  • Goal - add targetDate, statusDate, author, priority
  • HealthcareService - extensive rewrite
  • ImagingObjectSelection - remove retrieveAETitle, rename retrieveUrl to url, add frames
  • ImagingStudy - add laterality, change url to attachment
  • Immunization - add encounter, rename subject to patient, rename refusedIndicator to wasNotGiven, rename refusalReason to reasonNotGiven
  • ImmunizationRecommendation - rename subject to patient
  • List - add title, status, change ordered to orderedBy, add note
  • Location - remove status
  • Media - remove created (-> Attachment)
  • Medication - add batch
  • MedicationAdministration - add reasonGiven, note, text. remove timing & maxDosePerPeriod
  • MedicationDispense - collapse to a single dispense, add daysSupply, note and substitution, change quantity to allow range
  • MedicationRequest - add note, change quantity to allow range,
  • MedicationStatement - add informationSource, status, dateAsserted, replace whenGiven with effective[x], remove device, add dosage.text
  • NamingSystem - add date, publisher,
  • NutritionOrder - extensive rewrite
  • Observation - change name to code, allow more types of value[x], change type of dataAbsentReason, change to bodySite = code or Reference(BodySite), allow identifier to repeat, add device,
  • OperationDefinition - change identifier to url, add useContext, change telecom to contact, change name to title, add reuqirements, idempotent,
  • OperationOutcome - change type of .issue.type
  • OrderResponse - rename code to orderStatus
  • Organization - remove location and contact.gender
  • Patient - communication to allow 'preferred'
  • Person - rename other to target
  • Practitioner - change type of birthDate, allow multiple roles per practitioner
  • Procedure - add status and category, change to bodySite = code or Reference(BodySite), allow date to be period too, add location, change followUp to code 0..*, add device tracking
  • ServiceRequest - change to bodySite = code or Reference(BodySite)
  • Provenance - change integritySignature to signature & make it a type, allow reference by Reference as well as URI
  • Questionnaire - add telecom
  • Schedule - move lastModified
  • SearchParameter - change telecom to contact, add status, experimental, date,
  • Slot - move lastModified
  • Specimen - change source to parent, change to bodySite = code or Reference(BodySite)
  • StructureDefinition - complete rewrite
  • Subscription - change type of tag, reanme url to endPoint,
  • ValueSet - change identifier to url, add useContext, change telecom to contact, replace purpose with useContext, add requirements, rename stableDate to lockedDate, change type of expansion.identifier, add expansion parameters
0.4.0

Draft For Comment, January 2015 Ballot

Breaking Changes (full list):

  • Replace atom and taglist with a native Bundle format (3728, 3558, 2889) (and also Binary)
  • JSON: change how extensions are represented (3471)
  • RESTful API: change how version specific upgrades work (3451)
  • DataTypes:
  • Rename Schedule to Timing (3536, 3236)
  • Rename Contact to ContactPoint (3533) and swap order of elements (3108))
  • Address - change zip to postCode (2888)
  • Quantity: Correct schema spelling for "QuantityCompararator" (3531)
  • Change allowable values for the id type to include capital letters, and allow up to 64 chars (3750)
  • Restructure Profile - only one structure, and pull ExtensionDefinition out of Profile (3647, 3498), and pull SearchParameter out (3626)
  • Profile: allow 0..* discriminator (3131), and change the way discriminators work across resource boundaries (3124) + generate multiple types properly (2856)
  • remove _validate interaction, and replace with $validate operation (3686)
  • Patient: separate birth time from birthDate (3731), Change Administrative Gender from a CodableConcept to a Code. Also fixed the values as male|female|other|unknown with mappings to v2 and v3 (3070)
  • DocumentReference: change encoding of Hash to Base64 (3291)
  • Group: rename header to title (3126)
  • Condition: split relatedItem into two (3111)
  • Questionnaire: drop questionnaire.group.question.remarks (3255) and move omitReason from extension to base resource (3260)
  • QuestionnaireResponse: allow multiple answers (3146)
  • ValueSet: replace ValueSet.compose.include.code with ValueSet.compose.include.concept (3258), added new rules about expansion content (3138)
  • Media: Rename element 'dateTime' to 'created' (3174) and length to duration (2866)
  • Remove DeviceObservationReport and Query
  • Collapse AdverseReaction into AllergyIntolerance
  • Appointment changes - individual field renamed to actor, and added mappings to HL7 v2 and HL7 v3
  • FamilyMemberHistory combined with List replaces FamilyHistory (with corresponding updates to related profiles)
  • Flag replaces Alert including improved clarification of how it is used and replacement of "note" with "code"
  • CarePlan significantly refactored including splitting Goal out as a distinct resource, moving elements between activity and detail, introduction of several new elements and supported relationship types

New Resources:

New Implementation Guides (see discussion of status)

0.3.0
  • Renamed Namespace to NamingSystem
  • Split QuestionnaireResponse from Questionnaire and significantly revamped the Questionnaire in response to feedback from the Connectathon.
  • Added DataElement (now StructureDefinition) resource (has been previously discussed as ObservationDefinition)
  • Defined Subscription resource for evaluation
  • Add time data type
  • Define RPC-type operations on the RESTful interface, and add Operation Definition
  • Defined operations on several resources including ConceptMap, Questionnaire and ValueSet
  • Conformance (now CapabilityStatement): Change Conformance.rest.operation to Conformance.rest.interaction and Conformance.rest.resource.operation to Conformance.rest.resource.interaction, and add Conformance.rest.operation to point to Operation Definition
  • Profile: add Profile.url, Profile.structure.snapshot and Profile.structure.differential, and remove query definition (now in OperationDefinition)
  • Add pages for LOINC, RxNorm, and SNOMED CT
  • Significant rework for ConceptMap so it can be used to map between structures as well as value sets
  • Add Contraindication and Risk Assessment and added examples to other resources in support of these
  • Add Referral Request
  • Add supportingInformation to DiagnosticRequest
  • Add fulfills to Encounter
  • Add date and age[x] to FamilyHistory
  • Change cardinality of Location.identifier to 0..*
  • Change cardinality of Practitioner.address to 0..*
  • Add Observation.encounter to 0..*
  • Temporarily added content for the Structured Data Capture implementation guide, including profiles on several resources, conformance instances, etc. This content will be moved to an external specification once the necessary tooling is in place to support that form of publication.
0.2.1
  • Minor new optional elements on value set for metadata, new extensions for all the rest of the VSD project metadata, formal profile to express basic minimum metadata for value set
0.2.0
  • Namespace: adjustments based on Grahame's feedback
0.1.0

Note: a useful tool for displaying the differences between pages is the W3C HTML Diff engine.


http.html

RESTful API

Maturity Level: NormativeStandards Status:Normative

FHIR is described as a 'RESTful' specification based on common industry level use of the term REST. In practice, FHIR only supports Level 2 of the REST Maturity model as part of the core specification, though full Level 3 conformance is possible through the use of extensions. Because FHIR is a standard, it relies on the standardization of resource structures and interfaces. This may be considered a violation of REST principles but is key to ensuring consistent interoperability across diverse systems.

Each "resource type" has the same set of interactions defined that can be used to manage the resources in a highly granular fashion. Applications claiming conformance to this framework claim to be conformant to "RESTful FHIR" (see Conformance).

Note that in this RESTful framework, transactions are performed directly on the server resource using an HTTP request/response. The API does not directly address authentication, authorization, and audit collection - for further information, see the Security Page. All the interactions are all described for synchronous use, and an Asynchronous use pattern is also defined.

The API describes the FHIR resources as a set of operations (known as "interactions") on resources where individual resource instances are managed in collections by their type. Servers can choose which of these interactions are made available and which resource types they support. Servers SHALL provide a Capability Statement that specifies which interactions and resources are supported.

In addition to a number of General Considerations this page defines the following interactions:

Instance Level Interactions
readRead the current state of the resource
vreadRead the state of a specific version of the resource
updateUpdate an existing resource by its id (or create it if it is new)
patchUpdate an existing resource by posting a set of changes to it
deleteDelete a resource
historyRetrieve the change history for a particular resource
Type Level Interactions
createCreate a new resource with a server assigned id
searchSearch the resource type based on some filter criteria
historyRetrieve the change history for a particular resource type
Whole System Interactions
capabilitiesGet a capability statement for the system
batch/transactionUpdate, create or delete a set of resources in a single interaction
historyRetrieve the change history for all resources
searchSearch across all resource types based on some filter criteria

In addition to these interactions, there is an operations framework, which includes endpoints for validation, messaging and Documents. Also, implementers can use GraphQL.

General Considerations

Note: Where the FHIR specification does not specify behavior with regards to HTTP capabilities (such as OPTIONS), implementers cannot expect greater consistency than is mandated in the underlying HTTP protocol.

Style Guide

The interactions on this page are defined like this:

  VERB [base]/[type]/[id] {?_format=[mime-type]}

Implementations constructing URLs using these patterns SHOULD conform to RFC 3986 Section 6 Appendix A which requires percent-encoding for a number of characters that occasionally appear in the URLs (mainly in search parameters).

This specification uses the underscore as a prefix to disambiguate reserved names from other names in 3 cases:

In addition, the character $ is used as a prefix to operation names that are RPC-like additions to the base API defined either by this specification or by implementers.

Service Base URL

The Service Base URL is the address where all of the resources defined by this interface are found. The Service Base URL takes the form of

http{s}://server{/path}

The path portion is optional, and does not include a trailing slash. Each resource type defined in this specification has a manager (or "entity set") that lives at the address /[type] where the [type] is the name of the resource type. For instance, the resource manager for the type Patient will live at:

https://server/path/Patient

All the logical interactions are defined relative to the service root URL. This means that if the address of any one FHIR resource on a system is known, the address of other resources may be determined.

Note: All URLs (and ids that form part of the URL) defined by this specification are case sensitive. Clients SHOULD encode URLs using UTF-8, and servers SHOULD decode them assuming they are UTF-8 (for background, see here).

Note that a server may use a path of the form http://server/...[xx]... where the [xx] is some variable portion that identifies a particular instantiation of the FHIR API. Typically, the variable id identifies a patient or a user, and the underlying information is completely compartmented by the logical identity associated with [xx]. In this case, the FHIR API presents a patient or user centric view of a record, where authentication/authorization is explicitly granted to the URL, on the grounds that some identifiable user is associated with the logical identity. It is not necessary to explicitly embed the patient id in the URL - implementations can associate a FHIR end-point with a particular patient or provider by using an OAuth login. See Compartments for the logical underpinning.

Identity

Systems often need to compare two URLs to determine whether they refer to the same underlying object or not. For the purposes of this specification, the following rules apply:

For example: http://myserver.com/Patient/1 and https://myserver.com/Patient/1 refer to the same underlying object, while http://myserver.com:81/Patient/1 is a distinct entity from either of the above. This does not mean that the two addresses need to be treated the same, or that a server must serve both addresses, or that the content from the two addresses must be identical, but just that if these two addresses have the same identity, and if both are served, they must both represent the same underlying object. Systems are not required to check that this is true. Note: the identity comparison for protocols other than http:/https: is undefined.

Resource Metadata and Versioning

Each resource has an associated set of resource metadata elements. These map to the HTTP request and response using the following fields:

Metadata ItemWhere found in HTTP
Logical Id (.id)The Id is represented explicitly in the URL
Version Id (.meta.versionId)The Version Id is represented in the ETag header
Last modified (.meta.lastUpdated)HTTP Last-Modified header

Note that the Version Id is considered a "weak" ETag and ETag headers should be prefixed with W/ and enclosed in quotes, for example:

ETag: W/"3141"

Security

Using HTTPS is optional, but all production exchange of healthcare data SHOULD use SSL and additional security as appropriate. See HTTP Security for further information. Most operations will require user authentication, and all operations that do so are subject to RBAC and/or ABAC, and some operations may depend on appropriate consent being granted.

Note: to support browser-based client applications, servers SHOULD implement cross-origin resource sharing (CORS) for the interactions documented here.

See the HTTP Security guidance for further information about both security generally and the use of CORS.

HTTP Status Codes

This specification makes rules about the use of specific HTTP status codes in particular circumstances where the status codes SHALL map to particular states correctly, and only where the correct status code is not obvious. Other HTTP status codes may be used for other states as appropriate, and this particularly includes various authentication related status codes and redirects. Authentication redirects should not be interpreted to change the location of the resource itself (a common web programming error).

FHIR defines an OperationOutcome resource that can be used to convey specific detailed processable error information. For some combinations of interactions and specific return codes, an OperationOutcome is required to be returned as the content of the response. The OperationOutcome may be returned with any HTTP 4xx or 5xx response, but this is not required - many of these errors may be generated by generic server frameworks underlying a FHIR server.

Managing Return Content

If the server has a default timezone, it SHOULD return the default timezone in the HTTP Response headers using the "Date" header.

In the interests of managing band-width, this specification allows clients to specify what kind of content to return for resources.

conditional read

Clients may use the If-Modified-Since, or If-None-Match HTTP header on a read request. If so, they SHALL accept either a 304 Not Modified as a valid status code on the response (which means that the content is unchanged since that date) or full content (either the content has changed, or the server does not support conditional request).

Servers can return 304 Not Modified where content is unchanged because the If-Modified-Since date-time or the If-None-Match ETag was specified, or they can return the full content as normal. This optimisation is relevant in reducing bandwidth for caching purposes and servers are encouraged but not required to support this. If servers don't support conditional read, they just return the full content.

create/update/patch/transaction

These interactions are performed using POST, PUT or PATCH, and it may be appropriate for a server to return either only a status code, or also return the entire resource that is the outcome of the create or update (which may be different to that provided by the client). In the case of transactions this means returning a Bundle with just the Bundle.entry.response populated for each entry, and not the Bundle.entry.resource values.

The client can indicate whether the entire resource is returned using the HTTP return preference:

Prefer: return=minimal
Prefer: return=representation
Prefer: return=OperationOutcome

The first of these asks to return no body. The second asks to return the full resource. The third asks the server to return an OperationOutcome resource containing hints and warnings about the operation rather than the full resource. Servers SHOULD honor this header. In the absence of the header, servers may choose whether to return the full resource or not (but not the OperationOutcome; that should only be returned if explicitly requested). Note that this setting only applies to successful interactions. In case of failure, servers SHOULD always return a body that contains an OperationOutcome resource.

See also the Asynchronous use pattern for another use of the Prefer header.

Content Types and encodings

The formal MIME-type for FHIR resources is application/fhir+xml or application/fhir+json. The correct mime type SHALL be used by clients and servers:

Servers SHALL support server-driven content negotiation as described in section 12 of the HTTP specification.

Implementation Notes:

UTF-8 encoding SHALL be used for the mime type application/fhir. This MAY be specified as a MIME type parameter to the application/fhir mime type, but is not required.

FHIR Version Parameter

This specification defines the MIME-type parameter fhirVersion as a parameter to indicate which version of the FHIR release a resource is based on:

  Accept: application/fhir+json; fhirVersion=4.0

The value of this parameter is the publication and major version number for the specification:

FHIR R1 (DSTU 1) 0.0
FHIR R2 (DSTU 2) 1.0
FHIR R3 (STU3, or just R3) 3.0
FHIR R4 (this version) 4.0 (once published)

Intermediate balloted releases may also be encountered occasionally - see publications directory. Versions from before the publication of the first DSTU (which is 0.0) are not supported.

This parameter can be used anywhere that the FHIR Mime type is used. When used in an HTTP request, the version parameter may be used on either the Content-Type header, or the Accept header, or both, and applies to the entire interaction (the behavior of the interactions as described on ths page, the search parameters and functionality, and the accompanying conformance resources). It is an error for a client to attempt to use two different versions in the same interaction. For further information about specifying FHIR version, see Managing FHIR Versions.

General parameters

The following parameters are defined for use with all of the interactions defined on this page:

_format Override the HTTP content negotiation - see immediately below
_pretty Ask for a pretty printed response for human convenience - see below
_summary Ask for a predefined short form of the resource in response - see Search Summary
_elements Ask for a particular set of elements to be returned - see Search Elements

Note that the impact of _elements is not defined for interactions other than search where the response is a bundle that contains more than one type of resource.

_format

In order to support various implementation limitations, servers SHOULD support the optional _format parameter to specify alternative response formats by their MIME-types. This parameter allows a client to override the accept header value when it is unable to set it correctly due to internal limitations (e.g. XSLT usage). For the _format parameter, the values xml, text/xml, application/xml, and application/fhir+xml SHALL be interpreted to mean the XML format, the codes json, application/json and application/fhir+json SHALL be interpreted to mean the JSON format, and the codes ttl, application/fhir+turtle, and text/turtle SHALL be interpreted to mean the Turtle RDF format. In addition, the values html and text/html are allowed.

Note: the _format parameter does not override the Content-Type header for the type of the body of a POST request. If neither the accept header nor the _format parameter are specified, the MIME-type of the content returned by the server is undefined and may vary.

_pretty

Clients that wish to request for pretty-printed resources (either in JSON or XML) can use the _pretty parameter:

GET [base]/Patient/example?_pretty=true

Value values are true and false. Since pretty printed or not makes no difference to the content, this is only of interest for development tools, and servers MAY choose to support this parameter.

Support for Versions

Servers that support this API SHOULD provide full version support - that is, populate and track versionId correctly, support vread, and implement version aware updates. Supporting versions like this allows for related systems to track the correct version of information, and to keep integrity in clinical records. However, many current operational systems do not do this, and cannot easily be re-engineered to do so.

For this reason, servers are allowed to not provide versioning support and this API does not enforce that versioning is supported. Clients may elect to only interact with servers that do provide full versioning support. Systems declare their support for versioning in their Capability Statements, where they can indicate one of three levels for versioning support:

Servers that do not support versioning SHALL ensure that Resource.meta.versionId is not present on resources they return, and SHALL update the value of Resource.meta.lastUpdated correctly.

read

The read interaction accesses the current contents of a resource. The interaction is performed by an HTTP GET command as shown:

  GET [base]/[type]/[id] {?_format=[mime-type]}

This returns a single instance with the content specified for the resource type. This url may be accessed by a browser. The possible values for the Logical Id ("id") itself are described in the id type. The returned resource SHALL have an id element with a value that is the [id]. Servers SHOULD return an ETag header with the versionId of the resource (if versioning is supported) and a Last-Modified header.

Note: Unknown resources and deleted resources are treated differently on a read: a GET for a deleted resource returns a 410 status code, whereas a GET for an unknown resource returns 404. Systems that do not track deleted records will treat deleted records as an unknown resource. Since deleted resources may be brought back to life, servers MAY include an ETag on the error response when reading a deleted record to allow version contention management when a resource is brought back to life.

In addition, the search parameter _summary can be used when reading a resource:

  GET [base]/[type]/[id] {?_summary=text}

This requests that only a subset of the resource content be returned, as specified in the _summary parameter, which can have the values true, false, text, count and data. Note that a resource that only contains a subset of the data is not suitable for use as a base to update the resource, and might not be suitable for other uses. The same applies to the _elements parameter - both that it should be supported, and the subset implications. Servers SHOULD define a Resource.meta.tag with the SUBSETTED as a Simple Tag to explicitly mark such resources.

A HEAD request can also be used - see below.

vread

The vread interaction performs a version specific read of the resource. The interaction is performed by an HTTP GET command as shown:

  GET [base]/[type]/[id]/_history/[vid] {?_format=[mime-type]}

This returns a single instance with the content specified for the resource type for that version of the resource. The returned resource SHALL have an id element with a value that is the [id], and a meta.versionId element with a value of [vid]. Servers SHOULD return an ETag header with the versionId (if versioning is supported) and a Last-Modified header.

The Version Id ("vid") is an opaque identifier that conforms to the same format requirements as a Logical Id. The id may have been found by performing a history interaction (see below), by recording the version id from a content location returned from a read or from a version specific reference in a content model. If the version referred to is actually one where the resource was deleted, the server should return a 410 status code.

Servers are encouraged to support a version specific retrieval of the current version of the resource even if they do not provide access to previous versions. If a request is made for a previous version of a resource, and the server does not support accessing previous versions (either generally, or for this particular resource), it should return a 404 Not Found error, with an operation outcome explaining that history is not supported for the underlying resource type or instance.

A HEAD request can also be used - see below.

update

The update interaction creates a new current version for an existing resource or creates an initial version if no resource already exists for the given id. The update interaction is performed by an HTTP PUT command as shown:

  PUT [base]/[type]/[id] {?_format=[mime-type]}

The request body SHALL be a Resource with an id element that has an identical value to the [id] in the URL. If no id element is provided, or the id disagrees with the id in the URL, the server SHALL respond with an HTTP 400 error code, and SHOULD provide an OperationOutcome identifying the issue. If the request body includes a meta, the server SHALL ignore the provided versionId and lastUpdated values. If the server supports versions, it SHALL populate the meta.versionId and meta.lastUpdated with the new correct values. Servers are allowed to review and alter the other metadata values, but SHOULD refrain from doing so (see metadata description for further information). Note that there is no support for updating past versions - see notes on the history interaction.

A server SHOULD accept the resource as submitted when it accepts the update, and return the same content when it is subsequently read. However systems might not be able to do this; see the note on transactional integrity for discussion. Also, see Variations between Submitted data and Retrieved data for additional discussion around update behavior. Note that update generally updates the whole content of the resource. For partial updates, see patch below.

If the interaction is successful, the server SHALL return either a 200 OK HTTP status code if the resource was updated, or a 201 Created status code if the resource was created (or brought back to life/re-created), with a Last-Modified header, and an ETag header which contains the new versionId of the resource. If the resource was created (i.e. the interaction resulted in a 201 Created), the server SHOULD return a Location header (this is for HTTP conformance; it's not otherwise needed). The body of response is as described in Managing Return Content.

Note: Servers MAY choose to preserve XML comments, instructions, and formatting or JSON whitespace when accepting updates, but are not required to do so. The impact of this on digital signatures may need to be considered.

Update as Create

Servers MAY choose to allow clients to PUT a resource to a location that does not yet exist on the server - effectively, allowing the client to define the id of the resource. Whether a server allows this is a deployment choice based on the nature of its relationships with the clients. While many servers will not allow clients to define their ids, there are several reasons why it may be necessary in some configurations:

Alternatively, clients may be sharing an agreed identification model (e.g. key server, scoped identifiers, or UUIDs) where clashes do not arise. Note that this use of update has security implications.

Servers can choose whether or not to support client defined ids, and indicate such to the clients using CapabilityStatement.rest.resource.updateCreate.

Rejecting Updates

Servers are permitted to reject update interactions because of integrity concerns or other business rules, and return HTTP status codes accordingly (usually a 422). Note that there are potential security issues relating to how rejections are handled. See the security page for more information.

Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):

Any of these errors SHOULD be accompanied by an OperationOutcome resource providing additional detail concerning the issue. In general, if an instance fails the constraints documented in the CapabilityStatement then the response should be a 400, whereas if the instance fails other non-externally described business rules, the response would be a 422 error. However, there's no expectation that servers will tightly adhere to this differentiation (nor is it clear that it makes much difference whether they do or not). In practice, servers may also return 5xx errors in these cases without being deemed non-conformant.

For additional information on how systems may behave when processing updates, refer to the Variations between Submitted data and Retrieved data page.

Conditional update

Unlike this rest of this page, the conditional create, update, patch and delete are trial use until further experience is gained with their use. Their status will be reviewed in a future version of FHIR.

The conditional update interaction allows a client to update an existing resource based on some identification criteria, rather than by logical id. To accomplish this, the client issues a PUT as shown:

  PUT [base]/[type]?[search parameters]

When the server processes this update, it performs a search using its standard search facilities for the resource type, with the goal of resolving a single logical id for this request. The action it takes depends on how many matches are found:

This variant can be used to allow a stateless client (such as an interface engine) to submit updated results to a server, without having to remember the logical ids that the server has assigned. For example, a client updating the status of a lab result from "preliminary" to "final" might submit the finalized result using PUT path/Observation?identifier=http://my-lab-system|123

Note that transactions and conditional create/update/delete are complex interactions and it is not expected that every server will implement them. Servers that don't support the conditional update SHOULD return an HTTP 400 error and MAY include an OperationOutcome.

The resource MAY contain an id element, but does not need to (this is one of the few cases where a resource exists without an id element). If an id is provided, the server SHALL ignore it - see documentation for the update interaction.

Managing Resource Contention

Lost Updates, where two clients update the same resource, and the second overwrites the updates of the first, can be prevented using a combination of the ETag and If-Match header. This is also known as 'Optimistic Locking'.

To support this usage, servers SHOULD always return an ETag header with each resource:

HTTP 200 OK
Date: Sat, 09 Feb 2013 16:09:50 GMT
Last-Modified: Sat, 02 Feb 2013 12:02:47 GMT
ETag: W/"23"
Content-Type: application/fhir+json

If provided, the value of the ETag SHALL match the value of the version id for the resource. Servers are allowed to generate the version id in whatever fashion that they wish, so long as they are valid according to the id data type, and are unique within the address space of all versions of the same resource. When resources are returned as part of a bundle, there is no ETag, and the versionId of the resource is used directly.

If the client wishes to request a version aware update, it submits the request with an If-Match header that quotes the ETag from the server:

PUT /Patient/347 HTTP/1.1
If-Match: W/"23"

If the version id given in the If-Match header does not match, the server returns a 412 Precondition Failed status code instead of updating the resource.

Servers can require that clients provide an If-Match header by returning 400 Client Error status codes when no If-Match header is found. Note that a 409 Conflict can be returned when the server detects the update cannot be done (e.g. due to server side pessimistic locking).

patch

As an alternative to updating an entire resource, clients can perform a patch operation. This can be useful when a client is seeking to minimize its bandwidth utilization, or in scenarios where a client has only partial access or support for a resource. The patch interaction is performed by an HTTP PATCH command as shown:

  PATCH [base]/[type]/[id] {?_format=[mime-type]}

The body of a PATCH operation SHALL be either:

In either case, the server SHALL process its own copy of the resource in the format indicated, applying the operations specified in the document, following the relevant PATCH specification. When the operations have all been processed, the server processes the resulting document as an Update operation; all the version and error handling etc. apply as specified, as does the Prefer Header.

Processing PATCH operations may be very version sensitive. For this reason, servers SHALL support conditional PATCH, which works exactly the same as specified for update in Concurrency Management. Clients SHOULD always consider using version specific PATCH operations so that inappropriate actions are not executed.

Unlike this rest of this page, the conditional create, update, patch and delete are trial use until further experience is gained with their use. Their status will be reviewed in a future version of FHIR.

In addition, servers that support PATCH, and that support Conditional Update SHOULD also support conditional PATCH. When the server processes a conditional PATCH, it performs a search using its standard search facilities for the resource type, with the goal of resolving a single logical id for this request. The action it takes depends on how many matches are found:

The server SHALL ensure that the narrative in a resource is not clinically unsafe after the PATCH operation is performed. Exactly how this is defined and can be achieved depends on the context, and how narrative is being maintained, but servers may wish to consider:

Processing XML Patch documents is tricky because of namespace handling. Servers SHALL handle namespaces correctly, but note that FHIR resources only contain two XML namespaces, for FHIR (http://hl7.org/fhir) and XHTML (http://www.w3.org/1999/xhtml).

For PATCH Examples, see the FHIR test cases.

Patch operations may be performed as part of Batch or Transaction Operations using the FHIRPath Patch format.

Patch is not defined for all resources - see not about PATCH on Binary.

delete

The delete interaction removes an existing resource. The interaction is performed by an HTTP DELETE command as shown:

  DELETE [base]/[type]/[id]

The request body SHALL be empty.

A delete interaction means that subsequent non-version specific reads of a resource return a 410 HTTP status code and that the resource is no longer found through search interactions. Upon successful deletion, or if the resource does not exist at all, the server should return either a 200 OK if the response contains a payload, or a 204 No Content with no response payload, or a 202 Accepted if the server wishes to be non-commital about the outcome of the delete.

Whether to support delete at all, or for a particular resource type or a particular instance is at the discretion of the server based on the policy and business rules that apply in its context. If the server refuses to delete resources of that type as a blanket policy, then it should return the 405 Method not allowed status code. If the server refuses to delete a resource because of reasons specific to that resource, such as referential integrity, it should return the 409 Conflict status code. Note that the servers MAY choose to enforce business rules regarding deletion of resources that are being referenced by other resources, but they also MAY NOT do so. Performing this interaction on a resource that is already deleted has no effect, and the server should return either a 200 OK if the response contains a payload, or a 204 No Content with no response payload. Resources that have been deleted may be "brought back to life" by a subsequent update interaction using an HTTP PUT.

Many resources have a status element that overlaps with the idea of deletion. Each resource type defines what the semantics of the deletion interactions are. If no documentation is provided, the deletion interaction should be understood as deleting the record of the resource, with nothing about the state of the real-world corresponding resource implied.

For servers that maintain a version history, the delete interaction does not remove a resource's version history. From a version history respect, deleting a resource is the equivalent of creating a special kind of history entry that has no content and is marked as deleted. Note that there is no support for deleting past versions - see notes on the history interaction. Since deleted resources may be brought back to life, servers MAY include an ETag on the delete response to allow version contention management when a resource is brought back to life.

Note that irrespective of this rule, servers are free to completely delete the resource and it's history if policy or business rules make this the appropriate action to take.

Conditional delete

Unlike this rest of this page, the conditional create, update, patch and delete are trial use until further experience is gained with their use. Their status will be reviewed in a future version of FHIR.

The conditional delete interaction allows a client to delete an existing resource based on some selection criteria, rather than by a specific logical id. To accomplish this, the client issues an HTTP DELETE as shown:

  DELETE [base]/[type]/?[search parameters]

When the server processes this delete, it performs a search as specified using the standard search facilities for the resource type. The action it takes depends on how many matches are found:

This variant can be used to allow a stateless client (such as an interface engine) to delete a resource on a server, without having to remember the logical ids that the server has assigned. For example, a client deleting a lab atomic result might delete the resource using DELETE /Observation?identifier=http://my-lab-system|123.

Note that transactions and conditional create/update/delete are complex interactions and it is not expected that every server will implement them. Servers that don't support the conditional update SHOULD return an HTTP 400 error and MAY include an OperationOutcome.

create

The create interaction creates a new resource in a server-assigned location. If the client wishes to have control over the id of a newly submitted resource, it should use the update interaction instead. The create interaction is performed by an HTTP POST command as shown:

  POST [base]/[type] {?_format=[mime-type]}

The request body SHALL be a FHIR Resource. The resource does not need to have an id element (this is one of the few cases where a resource exists without an id element). If an id is provided, the server SHALL ignore it. If the request body includes a meta, the server SHALL ignore the existing versionId and lastUpdated values. The server SHALL populate the id, meta.versionId and meta.lastUpdated with the new correct values. Servers are allowed to review and alter the other metadata values, but SHOULD refrain from doing so (see metadata description for further information).

A server SHOULD otherwise accept the resource as submitted when it accepts the create, and return the same content when it is subsequently read. However some systems might not be able to do this; see the note on transactional integrity for discussion.

The server returns a 201 Created HTTP status code, and SHALL also return a Location header which contains the new Logical Id and Version Id of the created resource version:

  Location: [base]/[type]/[id]/_history/[vid]

where [id] and [vid] are the newly created id and version id for the resource version. The Location header should be as specific as possible - if the server understands versioning, the version is included. If a server does not track versions, the Location header will just contain [base]/[type]/[id]. The Location MAY be an absolute or relative URL.

Servers SHOULD return an ETag header with the versionId (if versioning is supported) and a Last-Modified header. The body of response is as described in Managing Return Content.

When the resource syntax or data is incorrect or invalid, and cannot be used to create a new resource, the server returns a 400 Bad Request HTTP status code. When the server rejects the content of the resource because of business rules, the server returns a 422 Unprocessable Entity error HTTP status code. In either case, the server SHOULD include a response body containing an OperationOutcome with detailed error messages describing the reason for the error.

Note: Servers MAY choose to preserve XML comments, instructions, and formatting or JSON whitespace when accepting creates, but are not required to do so. The impact of this on digital signatures may need to be considered.

Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):

In general, if an instance fails the constraints documented in the CapabilityStatement then the response should be a 400, whereas if the instance fails other non-externally described business rules, the response would be a 422 error. However, there's no expectation that servers will tightly adhere to this differentiation (nor is it clear that it makes much difference whether they do or not). In practice, servers may also return 5xx errors in these cases without being deemed non-conformant.

For additional information on how systems may behave when processing updates, refer to the Variations between Submitted data and Retrieved data page.

Conditional create

Unlike this rest of this page, the conditional create, update, patche and delete are trial use until further experience is gained with their use. Their status will be reviewed in a future version of FHIR.

The conditional create interaction allows a client to create a new resource only if some equivalent resource does not already exist on the server. The client defines what equivalence means in this case by supplying a FHIR search query using an HL7 defined extension header "If-None-Exist" as shown:

  If-None-Exist: [search parameters]

The parameter just contains the search parameters (what would be in the URL following the "?").

When the server processes this create, it performs a search as specified using its standard search facilities for the resource type. The action it takes depends on how many matches are found:

This variant can be used to avoid the risk of two clients creating duplicate resources for the same record. For example, a client posting a new lab result might specify If-None-Exist: identifier=http://my-lab-system|123 to ensure it does not create a duplicate record.

Note that transactions and conditional create/update/delete are complex interactions and it is not expected that every server will implement them. Servers that don't support the conditional update SHOULD return an HTTP 400 error and MAY include an OperationOutcome.

search

This interaction searches a set of resources based on some filter criteria. The interaction can be performed by several different HTTP commands.

  GET [base]/[type]{?[parameters]{&_format=[mime-type]}}

This searches all resources of a particular type using the criteria represented in the parameters.

Because of the way that some user agents and proxies treat GET and POST requests, in addition to the get based search method above, servers that support search SHALL also support a POST based search:

POST  [base]/[type]/_search{?[parameters]{&_format=[mime-type]}}
Content-Type: application/x-www-form-urlencoded

param1=value&param2=value

This has exactly the same semantics as the equivalent GET command. Note that in the POST variant, parameters may appear in both the URL and the body. Parameters have the same meaning in either place. Since parameters can repeat, putting them in both places is the same as repeating them (which is valid for some parameters and not for others).

Note: Supporting GET means that PHI (Personal health information) might appear in search parameters, and therefore in HTTP logs. For this reason logs should be regarded as being as sensitive as the resources themselves. This is a general requirement irrespective of the use of GET - see the security page for further commentary.

All these search interactions take a series of parameters that are a series of name=value pairs encoded in the URL (or as an application/x-www-form-urlencoded (Specification) submission for a POST). (See W3C HTML forms).

Note: application/x-www-form-urlencoded is supported for POST so that invoking a search by GET or POST can be done from HTML forms in a browser (though considerable active content might be required in the browser), although this is not the main usage.

A HEAD request can also be used - see below.

Searches are processed as specified for the Search handling mechanism.

If the search succeeds, the server SHALL return a 200 OK HTTP status code and the return content SHALL be a Bundle with type = searchset containing the results of the search as a collection of zero or more resources in a defined order. Note that resources returned in the search bundle MAY be located on the another server than the one that performs the search (i.e. the Bundle.entry.fullUrl may be different to the [base] from the search URL).

The result collection can be long, so servers may use paging. If they do, they SHALL use the method described below (adapted from RFC 5005 (Feed Paging and Archiving) for breaking the collection into pages if appropriate. The server MAY also return an OperationOutcome resource within the searchset Bundle entries that contains additional information about the search; if one is sent it SHALL NOT include any issues with a fatal or error severity, and it SHALL be marked with a Bundle.entry.search.mode of outcome.

If the search fails (cannot be executed, not that there are no matches), the return value return value SHALL be a status code 4xx or 5xx with an OperationOutcome.

Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):

Variant Searches

To search a compartment, for either all possible resources or for a particular resource type, respectively:

  GET [base]/[Compartment]/[id]/*{?[parameters]{&_format=[mime-type]}}
  GET [base]/[Compartment]/[id]/[type]{?[parameters]{&_format=[mime-type]}}

In the first URL the character "*" appears in the URL as a literal to mean 'all types'. So, for example, to retrieve all the observation resources for a particular LOINC code associated with a particular encounter:

  GET [base]/Encounter/23423445/Observation?code=2951-2  {&_format=[mime-type]}

Note that there are specific operations defined to support fetching an entire patient record or all record for an encounter.

It is also possible to search across multiple resource types:

  GET [base]?_type=Condition,Observation&[parameters]{&_format=[mime-type]}

This is a request to search on both Condition and Observation. In this case, the only parameters that can be used are those defined for both Condition and Observation (using SearchParameter.base - see Cross-resource Search Parameters), or the parameters defined for all resources. If a search lists types not listed in SearchParameter.base for any of the parameters, this is an error, and a server SHOULD return a 400 status. It is also possible to search on all types at once:

  GET [base]?[parameters]{&_format=[mime-type]}

When searching all resources at once, the only search parameters that be can be used in global search like this are the base parameters that apply to all resources.

capabilities

The capabilities interaction retrieves the information about a server's capabilities - which portions of this specification it supports. The interaction is performed by an HTTP GET command as shown:

  GET [base]/metadata{?mode=[mode]} {&_format=[mime-type]}

Applications SHALL return a resource that describes the functionality of the server end-point. The information returned depends on the value of the mode parameter:

full (or mode not present)A Capability Statement that specifies which resource types and interactions are supported
normativeAs above, but only the normative portions of the Capability Statement
terminologyA TerminologyCapabilities resource that provides further information about terminologies which are supported by the server

Servers MAY ignore the mode parameter and return a CapabilityStatement resource. Note: servers might be required to support this parameter in further versions of this specification.

If a 404 Unknown is returned from the GET, FHIR (or the specified version) is not supported on the nominated service url. An ETag header SHOULD be returned with the Response. The value of the ETag header SHALL change if the returned resource changes.

Servers SHOULD check for the fhirVersion MIME-type parameter when processing this request.

The resource returned typically has an arbitrary id, and no meta element, though it is not prohibited. Capability statements can become quite large; servers are encouraged to support the _summary and _elements parameters on the capabilities interaction, though this is not required. In addition, servers are encouraged to implement the $subset and $implements operations to make it easy for a client to check conformance.

In addition to this capabilities interaction, a server may also choose to provide the standard set of interactions (read, search, create, update) defined on this page for the CapabilityStatement Resource end-point. This is different from the capabilities interaction:

capabilities interactionreturns a capability statement describing the server's current operational functionality
CapabilityStatement end-pointmanages a repository of capability statements (e.g. the HL7 capability statement registry)

All servers are required to support the capabilities interaction, but servers may choose whether they wish to support the CapabilityStatement end-point, just like any other end-point.

In DSTU 2 and earlier, the resource that this interaction returned was named "Conformance". Clients often connect to a server, and use the capabilities interaction to check whether they are version and/or feature compatible with the server. Such clients should be able to process either a Conformance or a CapabilityStatement resource.

batch/transaction

The batch and transaction interactions submit a set of actions to perform on a server in a single HTTP request/response. The actions may be performed independently as a "batch", or as a single atomic "transaction" where the entire set of changes succeed or fail as a single entity. Multiple actions on multiple resources of the same or different types may be submitted, and they may be a mix of other interactions defined on this page (e.g. read, search, create, update, delete, etc.), or using the operations framework.

The transaction mode is especially useful where one would otherwise need multiple interactions, possibly with a risk of loss of referential integrity if a later interaction fails (e.g. when storing a Provenance resource and its corresponding target resource, or and IHE-MHD transaction "Provide Document Resources" with a DocumentManifest, and some number of DocumentReference, List, and Binary resources).

Note that transactions and conditional create/update/delete are complex interactions and it is not expected that every server will implement them. Servers that don't support the batches or transactions SHOULD return an HTTP 400 error and MAY include an OperationOutcome.

A batch or transaction interaction is performed by an HTTP POST command as shown:

  POST [base] {?_format=[mime-type]}

The content of the post submission is a Bundle with Bundle.type = batch or transaction. Each entry SHALL carry request details (Bundle.entry.request) that provides the HTTP details of the action in order to inform the system processing the batch or transaction what to do for the entry. If the HTTP command is a PUT or POST, then the entry SHALL contain a resource for the body of the action. The resources in the bundle are each processed separately as if they were an individual interaction or operation as otherwise described on this page, or the Operations framework. The actions are subject to the normal processing for each, including the meta element, verification and version aware updates, and transactional integrity. In the case of a batch each entry is treated as if an individual interaction or operation, in the case of a transaction all interactions or operations either succeed or fail together (see below).

Examples:

Batch Processing Rules

For a batch, there SHALL be no interdependencies between the different entries in the Bundle that cause change on the server. The success or failure of one change SHOULD not alter the success or failure or resulting content of another change. Servers SHOULD validate that this is the case. Note that it is considered that servers execute the batch in the same order as that specified below for transactions, though the order of execution should not matter given the previous rule.

References within a Bundle.entry.resource to another Bundle.entry.resource that is being created within the batch are considered to be non-conformant.

When processing the batch, the HTTP response code is 200 Ok if the batch was processed correctly, regardless of the success of the operations within the Batch. To determine the status of the operations, look inside the returned Bundle. A response code on an entry of other than 2xx (200, 202 etc) indicates that processing the request in the entry failed.

Transaction Processing Rules

For a transaction, servers SHALL either accept all actions and return a 200 OK, along with a response bundle (see below), or reject all resources and return an HTTP 400 or 500 type response. It is not an error if the submitted bundle has no resources in it. The outcome of processing the transaction SHALL NOT depend on the order of the resources in the transaction. A resource can only appear in a transaction once (by identity).

Because of the rules that a transaction is atomic where all actions pass or fail together and the order of the entries doesn't matter, there is a particular order in which to process the actions:

  1. Process any DELETE interactions
  2. Process any POST interactions
  3. Process any PUT or PATCH interactions
  4. Process any GET or HEAD interactions
  5. Resolve any conditional references

If any resource identities (including resolved identities from conditional update/delete) overlap in steps 1-3, then the transaction SHALL fail.

A transaction may include references from one resource to another in the bundle, including circular references where resources refer to each other. When the server assigns a new id to any resource in the bundle which has a POST method as part of the processing rules above, it SHALL also update any references to that resource in the same bundle as they are processed (see about Ids in a bundle). References to resources that are not part of the bundle are left untouched. Version-specific references should remain as version-specific references after the references have been updated. Note that when building a transaction, a client can use arbitrarily chosen version references since they will all be re-assigned anyway. Servers SHALL replace all matching links in the bundle, whether they are found in the resource ids, resource references, elements of type uri, url, oid, uuid, and <a href="" & <img src="" in the narrative. Elements of type canonical are not replaced.

When processing a "POST" (create), the full URL is treated as the id of the resource on the source, and is ignored; the server generates an id for the resource. For updates, the server performs a mapping between the fullUrl specified and the local URL the server knows that instance as, if possible. If the server does not have a mapping for the fullUrl, the server ignores the base URL and attempts an update assuming the base is the same as the server base. This allows the same transaction bundle to be sent to multiple systems without changing the fullUrls for each target.

When processing a batch or transaction, a server MAY choose to honor existing logical ids (e.g. Observation/1234 remains as Observation/1234 on the server), but since this is only safe in controlled circumstances, servers may choose to assign new ids to all submitted resources, irrespective of any claimed logical id in the resource, or fullUrl on entries in the batch/transaction.

Conditional References

When constructing the bundle, the client might not know the logical id of a resource, but it may know identifying information - e.g. an identifier. This situation arises commonly when building transactions from v2 messages. The client could resolve that identifier to a logical id using a search, but that would mean that the resolution to a logical id does not occur within the same transaction as the commit (as well as significantly complicating the client). Because of this, in a transaction (and only in a transaction), references to resources may be replaced by a search URI that describes how to find the correct reference:

 <Bundle xmlns="http://hl7.org/fhir">
   <id value="20160113160203" />
   <type value="transaction" />
   <entry>
     <fullUrl value="urn:uuid:c72aa430-2ddc-456e-7a09-dea8264671d8" />
     <resource>
       <Observation>
         <subject>
            <reference value="Patient?identifier=12345"/>
         </subject>
         <--! rest of resource omitted -->
       </Observation>
     </resource>
     <request>
       <method value="POST" />
     </request>
   </entry>
 <Bundle>

The search URI is relative to the server's [base] path, and always starts with a resource type: [type]?parameters.... Only filtering parameters are allowed; none of the parameters that control the return of resources are relevant.

When processing transactions, servers SHALL:

Batch/Transaction Response

For a batch, or a successful transaction, the response the server SHALL return a Bundle with type set to batch-response or transaction-response that contains one entry for each entry in the request, in the same order, with the outcome of processing the entry. For a failed transaction, the server returns a single OperationOutcome instead of a Bundle.

A client may use the returned Bundle to track the outcomes of processing the entry, and the identities assigned to the resources by the server. Each entry element SHALL contain a response element which details the outcome of processing the entry - the HTTP status code, and the location and ETag header values, which are used for identifying and versioning the resources. In addition, a resource may be included in the entry, as specified by the Prefer header.

Accepting other Bundle types

A server may choose to accept bundle types other than batch or transaction when POSTed to the [base] URL.

Bundles of type history inherently have the same structure as a transaction, and can be treated as either a transaction or batch, so servers SHOULD accept a history Bundle - this makes it possible to replicate data from one server to another easily using a pub/sub model. Note, however, that the original transaction boundaries might not be represented in a history list, and a resource may occur more than once in a history list, so servers processing history bundles must have some strategy to manage this. When processing a history bundle via a transaction, any entries with the request method of POST must use the Bundle.entry.resource.id (which must match the Bundle.entry.response.location) for that resource so that references are preserved.

For other Bundle types, should the server choose to accept them, there will be no request element (note that every entry will have a resource). In this case, the server treats the entry as either a create or an update interaction, depending on whether it recognizes the identity of the resource - if the identity of the resource refers to a valid location on the server, it should treat it as an update to that location. Note: this option allows a client to delegate the matching process to the server.

history

The history interaction retrieves the history of either a particular resource, all resources of a given type, or all resources supported by the system. These three variations of the history interaction are performed by HTTP GET command as shown:

  GET [base]/[type]/[id]/_history{?[parameters]&_format=[mime-type]}
  GET [base]/[type]/_history{?[parameters]&_format=[mime-type]}
  GET [base]/_history{?[parameters]&_format=[mime-type]}

The return content is a Bundle with type set to history containing the specified version history, sorted with oldest versions last, and including deleted resources. Each entry SHALL minimally contain at least one of: a resource which holds the resource as it is at the conclusion of the interaction, or a request with entry.request.method The request provides information about the result of the interaction that led to this new version, and allows, for instance, a subscriber system to differentiate between newly created resources and updates to existing resources. The principal reason a resource might be missing is that the resource was changed by some other channel rather than via the RESTful interface. If the entry.request.method is a PUT or a POST, the entry SHALL contain a resource.

The interactions create, update, and delete create history entries. Other interactions do not (note that these operations may produce side-effects such as new AuditEvent resources; these are represented as create interactions in their own right). New resources or updates to existing resources that are triggered by operations also appear in the history, as do updates to the resources that result from interactions outside the scope of the RESTful interface.

A HEAD request can also be used - see below.

A create interaction is represented in a history interaction in the following way:

  <entry>
    <resource>
      <Patient>
        <!-- the id of the created resource -->
        <id value="23424"/>
        <!-- snip -->
      </Patient>
    </resource>
    <request>
      <!-- POST: this was a create -->
      <method value="POST"/>
      <url value="Patient"/>
    </request>
    <!-- response carries the instant the server processed the create -->
    <response>
      <lastModified value="2014-08-15T10:35:02.034Z"/>
    </response>
  </entry>

A delete interaction is represented in a history interaction in the following way:

  <entry>
    <!-- no resource included for a delete -->
    <request>
      <method value="DELETE"/>
      <url value="Patient/[id]"/>
    </request>
    <!-- response carries the instant the server processed the delete -->
    <response>
      <lastModified value="2014-08-20T11:05:34.174Z"/>
    </response>
  </entry>

Notes:

In addition to the standard _format parameter, the parameters to this interaction may also include:

_count : integerThe maximum number of search results on a page, excluding related resources included by _include or _revinclude or OperationOutcomes. The server is not bound to return the number requested, but cannot return more
_since : instantOnly include resource versions that were created at or after the given instant in time
_at : date(Time)Only include resource versions that were current at some point during the time period specified in the date time value (see Search notes on date searching)
_list : referenceOnly include resource versions that are referenced in the specified list (current list references are allowed)

Each of these parameters SHALL NOT appear more than once.

The history list can be restricted to a limited period by specifying a _since parameter which contains a full date time with time zone. Clients should be aware that due to timing imprecision, they may receive notifications of a resource update on the boundary instant more than once. Servers are not required to support a precision finer than by second.

The updates list can be long, so servers may use paging. If they do, they SHALL use the method described below for breaking the list into pages if appropriate, and respect the specified _count across pages.

The history interaction can be used to set up a subscription from one system to another, so that resources are synchronized between them. Refer to the Subscription resource for an alternate means of system synchronization.

Additional Notes about maintaining a history of resources:

Thereis a caveat with the _list parameter, associated with changes to the list while making repeated periodic queries; if the list changes, the response will include changes to the resources in the list for the period specified, but will omit both later changes to items no longer in the list, or older changes associated with items in the list. This might not be a problem, but implementers should be aware of this issue.

Transactional Integrity

When processing create and update interactions, a FHIR server is not obliged to accept the entire resource as it is; when the resource is retrieved through a read interaction subsequently, the resource may be different. The difference may arise for several reasons:

Note that there is no general-purpose method to make merging with existing content or altering the content by business rules safe or predictable - what is possible, safe and/or required is highly context dependent. These kinds of behaviors may be driven by security considerations. With regard to incomplete support, clients can consult the server's base CapabilityStatement profile references to determine which features or values the server does not support.

The PATCH operation offers some support for making changes to a part of a resource and should be used where a client wishes to change just part of a resource, though transactional integrity issues are still important.

To the degree that the server alters the resource for any of the 3 reasons above, the FHIR server will create implementation consequences for the eco-system that it is part of, which will need to be managed (i.e. it will cost more). For this reason, servers SHOULD change the resource as little as possible, given the constraints of the system exposing the FHIR resource. However due to the variability that exists within healthcare, this specification allows that servers MAY alter the resource on create/update.

Similarly, to the degree that an implementation context makes special rules about merging content or altering the content, that context will become more expensive to maintain.

Although these rules are stated with regard to servers, a similar concept applies to clients - to the degree that different client systems interacting with the server do not support the same feature set, the clients and/or the server will be forced to implement custom logic to prevent information from being lost or corrupted.

Some of these problems can be mitigated by following a pattern built on top of version-aware updates. In this pattern:

If clients follow this pattern, then information from other systems that they do not understand will be maintained through the update.

Note that it is possible for a server to choose to maintain the information that would be lost, but there is no defined way for a server to determine whether the client omitted the information because it wasn't supported (perhaps in this case) or whether it wishes to delete the information.

Conformance

Both client and server systems SHOULD clearly document how transaction integrity is handled, in the documentation in the CapabilityStatement.

Paging

Servers SHOULD support paging for the results of a search or history interaction, and if they do, they SHALL conform to this method (adapted from RFC 5005 (Feed Paging and Archiving) for sending continuation links to the client when returning a Bundle (e.g. with history and search). If the server does not do this then there is no way to continue paging.

This example shows the third page of a search result:

<Bundle xmlns="http://hl7.org/fhir">
  <!-- snip metadata -->
  <!-- This Search url starts with base search, and adds the effective
    parameters, and additional parameters for search state. All searches
    SHALL return this value.

	  In this case, the search continuation method is that the server
    maintains a state, with page references into the stateful list.
	-->
  <link>
    <relation value="self">
    <url value="http://example.org/Patient?name=peter&stateid=23&page=3"/>
  </link>
  <!-- 4 links for navigation in the search. All of these are optional, but recommended -->

  <link>
    <relation value="first"/>
    <url value="http://example.org/Patient?name=peter&stateid=23&page=1"/>
  </link>
  <link>
    <relation value="previous"/>
    <url value="http://example.org/Patient?name=peter&stateid=23&page=2"/>
  </link>
  <link>
    <relation value="next"/>
    <url value="http://example.org/Patient?name=peter&stateid=23&page=4"/>
  </link>
  <link>
    <relation value="last"/>
    <url value="http://example.org/Patient?name=peter&stateid=23&page=26"/>
  </link>

  <!-- then the search results... -->
</Bundle>

The links are opaque to the client, have no dictated structure, and only the server understands them. The client must use the server supplied links in order to traverse the pages. A server MAY add additional state tracking parameters to the links, as shown in the example above, though the server need not use a stateful paging method as shown in this example - it is at the discretion of the server how to best ensure that the continuation retains integrity in the context of ongoing changes to the resources. An alternative approach is to use version specific references to the records on the boundaries, but this is subject to continuity failures when records are updated.

A server MAY inform the client of the total number of resources returned by the interaction for which the results are paged using the Bundle.total.

Note that for search, where _include can be used to return additional related resources, the total number of resources in the feed may exceed the number indicated in totalResults.

In the case of a search, the initial request may be made via a POST, but the follow up page requests will be made via GET requests. However servers SHOULD allow for a client to convert the follow up requests to be made via a POST.

Support for HEAD

Anywhere that a GET request can be used, a HEAD request is also allowed. HEAD requests are treated as specified in HTTP: same response as a GET, but with no body.

Servers that do not support HEAD MUST respond in accordance with the HTTP specification, for example using a 405 ("method not allowed") or a 501 ("not implemented").

Custom Headers

This specification defines or recommends some custom headers that implementers can use to assist with deployment/debugging purposes:

X-Request-IdA unique id to for the request/response assigned by either client or server. Request: assigned by the client. Response: assigned by the server
X-Correlation-IdA client assigned request id echoed back in the response
X-Forwarded-ForIdentifies the originating IP address of a client to an intermediary
X-Forwarded-HostIdentifies the original host requested by the client in the Host HTTP request header
X-IntermediaryStamped by an active intermediary that changes the request or the response to alter it's content (see below)

The request id in X-Request-Id is purely to help connect between requests and logs/audit trails. The client can assign an id to the request, and send that in the X-Request-Id header. The server can either use that id or assign it's own, which it returns as the X-Request-Id header in the response. When the server assigned id is different to the client assigned id, the server SHOULD also return the X-Correlation-Id header with the client's original id in it.

The HTTP protocol may be routed through an HTTP proxy (e.g. as squid). Such proxies are transparent to the applications, though implementers should be alert to the effects of caching, particularly including the risk of receiving stale content. See the HTTP specification for further detail

Interface engines may also be placed between the consumer and the provider. These differ from proxies because they actively alter the content and/or destination of the HTTP exchange and are not bound by the rules that apply to HTTP proxies. Such agents are allowed, but SHALL mark the request with an X-Intermediary header to assist with debugging/troubleshooting. Any agent that modifies an HTTP request or response content other than under the rules for HTTP proxies SHALL add a stamp to the HTTP headers like this:

  X-Intermediary : [identity - usually a FQDN]

End point systems SHALL NOT use this header for any purpose. Its aim is to assist with system troubleshooting.

Summary

These tables present a summary of the interactions described here. Note that all requests may include an optional Accept header to indicate the format used for the response (this is even true for DELETE since an OperationOutcome may be returned).

Interaction PathRequest
Verb Content-Type Body Prefer Conditional
read /[type]/[id] GET N/A N/A N/A O: ETag, If-Modified-Since, If-None-Match
vread /[type]/[id]/_history/[vid] GET N/A N/A N/A N/A
update /[type]/[id] PUT R Resource O O: If-Match
patch /[type]/[id] PATCH R (may be a patch type) Patch O O: If-Match
delete /[type]/[id] DELETE N/A N/A N/A N/A
create /[type] POST R Resource O O: If-None-Exist
search /[type]? GET N/A N/A N/A N/A
/[type]/_search? POST application/x-www-form-urlencoded form data N/A N/A
search-all ? GET N/A N/A N/A N/A
capabilities /metadata GET N/A N/A N/A N/A
transaction / POST R Bundle O N/A
history /[type]/[id]/_history GET N/A N/A N/A N/A
history-type /[type]/_history GET N/A N/A N/A N/A
history-all /_history GET N/A N/A N/A N/A
(operation) /$[name], /[type]/$[name] or /[type]/[id]/$[name] POST R ParametersN/A N/A
GET N/A N/A N/A N/A
POST application/x-www-form-urlencoded form data N/A N/A

Notes:

InteractionResponse
Content-Type Body Location Versioning Status Codes
read R R: Resource N/A R: ETag, Last-Modified 200, 404, 410
vread R R: Resource N/A R: ETag, Last-Modified 200, 404
update R if body O: Resource (Prefer) N/A R: ETag, Last-Modified 200, 201, 400, 404, 405, 409, 412, 422
patch R if body O: Resource (Prefer) N/A R: ETag, Last-Modified 200, 201, 400, 404, 405, 409, 412, 422
delete R if bodyO: OperationOutcome N/A N/A 200, 202, 204, 404, 405, 409, 412
create R if body O : Resource (Prefer) R R: ETag, Last-Modified 201, 400, 404, 405, 422
search R R: Bundle N/A N/A 200, 401?
search-all R R: Bundle N/A N/A 200, 401?
capabilities R R: CapabilityStatementN/A N/A 200, 404
transaction R R: Bundle N/A N/A 200, 400, 404, 405, 409, 412, 422
history R R: Bundle N/A N/A 200
history-type R R: Bundle N/A N/A 200
history-all R R: Bundle N/A N/A 200
(operation) R R: Parameters/ResourceN/A N/A 200

Note: this table lists the status codes described here, but other status codes are possible as described by the HTTP specification. Additional codes that are likely are server errors and various codes associated with authentication protocols. The security page notes several security related issues that may impact which codes to return.


icd.html

Using ICD-[X] Codes with FHIR

Maturity Level: 2Standards Status:Trial Use

ICD is a family of code systems maintained by WHO, with many countries publishing their own variants.

There are two principal revisions of ICD in use - ICD-10 and ICD-9 (note that while US usage has recently updated to ICD-10, there is still a lot of legacy data coded in ICD-9). Though these can be referred to as different versions of ICD, they are entirely distinct sets of codes, with significant differences in organization and coding rules. Plus, if period ('.') characters are disregarded (as occurs in some systems), a few of the codes are overlapping between ICD-9 and ICD-10. Given these considerations, ICD-9 and ICD-10 are represented as entirely separate code systems. The next revision, ICD-11, is scheduled for release in 2017.

Summary

ICD-10 ICD-9
Source WHO or see below (CDC)
System http://hl7.org/fhir/sid/icd-10 and
http://hl7.org/fhir/sid/icd-10-[x] (see below)
http://hl7.org/fhir/sid/icd-9-cm
OID 2.16.840.1.113883.6.3 2.16.840.1.113883.6.42
Version The versioning convention and frequency may vary between the various ICD revisions and variants. WHO publishes a new version of ICD-10 annually in October (with minor updates annually, and major updates, if required, every 3 years - the versions are identified as 'YYYY', e.g. '2016'). The national variants (which in some cases are used multi-nationally) are also typically published on an annual basis (refer to the documentation for a particular variant for details).
Code Either an ICD-10 or ICD-9 code, or a dual (multiple) coding expression - see below. ICD codes SHALL be represented with the period included, e.g. 123.4
Display There are no specific conventions required or described for obtaining the complete display string for use for each code.
Inactive ICD-9 and ICD-10 do not have codes that are identified as inactive (although in some cases previously included codes may have been removed or changed in meaning in subsequent versions).
Hierarchy The tabular representations are organized with headings and multiple levels of codes (typically based on the numbers of digits contained in each code), but an explicit hierarchy is not defined.
Filter Properties None are described yet.

ICD-10 variants

Variants (other variants exist which are not listed here):

Germany http://fhir.de/CodeSystem/dimdi/icd-10-gm see HL7 Germany page
Netherlands http://hl7.org/fhir/sid/icd-10-nl 2.16.840.1.113883.6.3.2
United States http://hl7.org/fhir/sid/icd-10-cm 2.16.840.1.113883.6.90

Multiple Coding

Dual Coding (“dagger and asterisk” system)

For dual ("two code", “dagger and asterisk”) coding see volume 2 ICD-10 Manual), section 3.1.3 Two codes for certain conditions. In cases where two codes are required, the primary recommendation for representing this coding in FHIR (in Coding.code) is to simply use the two ICD-10 codes separated by a space, e.g. "J21.8 B95.6", as the code value (string). This is a simple form of post-coordination syntax. Alternatively, another possible syntax that may be used (which may be desirable or required in some situations) is to include the characters of the dagger (represented as † or +) for the primary code and the asterisk (*) for the secondary code as part of the post-coordinated code value, e.g. "J21.8+ B95.6*". In either case, it is recommended that the primary (+) code for the underlying generalized disease is listed first, followed by the secondary (*) code for the specific manifestation in a particular organ or site.

Dual coding in ICD-10 is used for the following (and potentially other) reasons:

Dual Coding Example: "Staph aureus bronchiolitis" is coded using ICD-10 codes J21.8 "Acute bronchiolitis due to other specified organisms" and B95.6 "Staphylococcus aureus as the cause of diseases classified to other chapters" as:

  <coding>
    <system value="http://hl7.org/fhir/sid/icd-10"/>
    <code value="J21.8 B95.6"/>
  </coding>
or, with the + and * characters included:
  <coding>
    <system value="http://hl7.org/fhir/sid/icd-10"/>
    <code value="J21.8+ B95.6*"/>
  </coding>

Additional Characters

Some jurisdictions (e.g. Germany) have additional coding requirements that go beyond the dual coding “dagger and asterisk” coding approach (syntax). In ICD-10-GM used in Germany the ! character is used to indicate a secondary diagnosis.

Primary diagnosis

Secondary diagnosis

The recommended syntax for representing these combinations of codes in FHIR (in Coding.code) is to include the additional (+*!) characters when they are present and to separate the code groups with a space, as:

  <coding>
    <system value="http://fhir.de/CodeSystem/dimdi/icd-10-gm"/>
    <version value="2017"/>
    <code value="S62.32 Z33!"/>
  </coding>

Three or More Codes

The coding also may require three or sometimes more codes for a complete representation of the intended meaning. A further German coding example (from the Deutsche Kodierrichtlinien manual) includes an additional secondary diagnosis and a monitoring code.

Additional secondary diagnosis and monitoring codes

A proper interpretation of this extended example is: "A patient is admitted to hospital due to a fracture of the metacarpal shaft. Since she is six weeks pregnant, the pregnancy and the monitoring of the pregnancy are coded as secondary diagnoses." The recommended FHIR representation is:

  <coding>
    <system value="http://fhir.de/CodeSystem/dimdi/icd-10-gm"/>
    <version value="2017"/>
    <code value="S62.32 Z33! O09.1! Z34"/>
  </coding>

Other jurisdictions may have similar needs for multiple coding but with different specific coding requirements. In those cases local coding manuals and authorities should be consulted to determine the recommended or expected syntax to use in a FHIR Coding instance.

Copyright/License Issues

ICD-10 is ©Copyright World Health Organization (WHO). WHO licenses its published material widely, in order to encourage maximum use and dissemination. See Licensing WHO classifications for details. The ICD variants have their own separate copyright and licensing (refer to the documentation for the particular variant for details).

ICD-X Filter Properties

No need for filters identified yet.

Implicit Value Sets

No need for implicit value sets identified yet.


identifier-registry.html

Known Identifier Systems

Maturity Level: 3Standards Status:Trial Use

The following names (URIs) may be used in the system element of the Identifier data type. If a URI is defined here, it SHALL be used in preference to any other identifying mechanism. If an identifier system is not listed here, the correct URI may be determined by working through the following list, in order:

See also the list of known coding systems that can be used in the system element of the Coding data type. Additional identifier systems may be registered on the HL7 FHIR registry at http://hl7.org/fhir/registry.

This list of URIs is incomplete and subject to change. Some values may be dropped and others will likely be added in the coming months as HL7 institutes formal processes around URIs in vocabulary.

The URI column indicates the correct value to use in the Identifier.system. The OID is provided for compatibility with HL7 v2/CDA based systems. Note that any URL in http://example.org is reserved for testing and documentation purposes.

identifier URI OID (for non-FHIR systems) Type Comment
URIs (W3C): when the identifier is a URI urn:ietf:rfc:3986 2.16.840.1.113883.4.873 As defined by RFC 3986 (with many schemes defined in many RFCs). For OIDs and UUIDs, use the URN form (urn:oid: (note: lowercase) and urn:uuid:

implsupport-module.html

Work Group Standards Status:Informative

Implementation Support Module

Introduction

This section provides information which will be useful for FHIR implementers, including information about available libraries, tools, and other similar resources, as well as where to seek help.

Index

In addition to the content below, a number of implementation resources can be found on the Downloads Page.

This module also contains some specific documentation that relates to issues commonly encountered by developers:

Security and Privacy

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

Common Use Cases

For Client Developers and Testers: Reference Servers

The following reference servers have been created by the FHIR team and made available to help implementers test their code. While the reference servers are not considered to be a normative part of the FHIR specification, the maintainers make every effort to ensure that they are fully compliant.

Note that there are a large number of servers available for testing that are not listed here. A full list is available on the HL7 Confluence system here.

Server NameMaintainerLink
HealthintersectionsGrahame Grievehttp://fhir3.healthintersections.com.au/
SparkFurore Informaticahttp://spark.furore.com/
HAPIUniversity Health Network / James Agnewhttp://fhirtest.uhn.ca/
sqlonfhirTelstra Health / Brian Postlethwaitehttp://sqlonfhir-stu3.azurewebsites.net/fhir

For Developers: Reference Implementations (Libraries)

The following reference implementations are made available under an open-source license. These libraries may be used by developers to quickly add FHIR capabilities to their applications.

LanguageLibraryLinkLicense
.NET / C#FHIR .NET APIhttps://github.com/ewoutkramer/fhir-net-apiBSD-3
JavaHAPI FHIRhttp://hapifhir.ioApache 2.0
SwiftSwift FHIRhttps://github.com/smart-on-fhir/Swift-FHIRApache 2.0
JavaScriptfhir.jshttps://github.com/smart-on-fhir/fhir.jsMIT
PythonClient Pyhttps://github.com/smart-on-fhir/client-pyApache 2.0
PascalFHIR Pascalhttp://hl7.org/fhir/downloads.htmlBSD-3

For Profilers

A number of tools are available to profilers wishing to create profiles for use in their implementations. A current list of tools can be found here on HL7 Confluence. (See the conformance module for information on profiling.)

For Testers

A number of tools are available to solution testers who want to test FHIR implementations for conformance to the FHIR specification. A current list of such tools can be found here.

Getting Help

The following are a few ways that implementers can seek help as they work with FHIR:

Developmental Roadmap

The reference servers and reference implementations generally try to keep up to date with recent changes to the FHIR specification. Each server may have multiple endpoints which are held to a specific version of the specification, but generally there will also be endpoints available for testing which conform to a very recent build.

Efforts are now underway to create a curated collection of quality test data which can be used by FHIR implementers to help test their applications. This collection will be made available when it is ready.


index.html

Welcome to FHIR®

FHIR is a standard for health care data exchange, published by HL7®. Note: The continuous build is getting ready for the first normative publication (R4).

First time here?
See the executive summary, the developer's introduction, clinical introduction, or architect's introduction, and then the FHIR overview / roadmap & Timelines. See also the open license (and don't miss the full Table of Contents and the Community Credits or you can search this specification).

External Links:

Implementation Guides

Specifications based on the FHIR standard

FHIR Foundation

Enabling health interoperability through FHIR

Translations

Note that translations are not always up to date

Note: This specification requires a browser that is SVG compatible (Microsoft Internet Explorer 10+, Firefox 3.0+, Chrome, or Safari), and uses the browser's session storage to remember which tabs are active.


integrated-examples.html

Integrated Examples

Maturity Level: N/AStandards Status:Informative

These integrated examples are the result of choosing several real world healthcare records from a Dutch healthcare institution and representing them using FHIR resources. They are published here for several reasons:

Patient case 1

The 69 year old Pieter van den Heuvel is diagnosed with several serious diseases over the last few years. In the spring and summer of 2011, Pieter had complaints of fatigue, dyspnea and even fainting. After visiting his physician, Pieter was referred to the cardiologist for further examination. At the hospital a malfunction of the heart valve was diagnosed and eventually replaced. Pieter recovered well in the next 2 months, but probably needs a life time prescription on blood pressure reducing medication. In the summer of 2012, Pieter again visited his physician for a chest injury after he fell from the stairs. By coincidence, the doctor noticed a suspicious stain on the X-thorax and performed some additional tests on Pieter. After the results, Pieter was diagnosed with early stage non-small cell lung cancer. Fortunately, the tumor didn't spread to other parts of the body. Tumor type and location made it possible to perform a partial lobectomy in the right lung. After his recovery, Pieter was submitted to a high risk control group for yearly screening.

In 2013, Pieter was charged with an increasing neck swelling, a stiff neck and difficulty swallowing. Because of breathing problems, Pieter was urgently admitted to the hospital. An upper respiratory infection caused a retropharyngeal abscess in the back of the throat. Surgery was needed to remove the abscess. The surgeons recommended a tracheotomy during the surgery, so there was less change of complications during the abscess removal. A tracheotomy was intubated before the surgery. After the removal of the retropharyngeal abscess, the tracheotomy was extubated as the swelling was reduced and normal breathing became reinstated.

Patient demographic information

Patient name: Pieter van den Heuvel
Patient number: 0108173
Date of birth: 17-11-1944
Gender: Male

Patient contact information

Address: van Egmondkade 23
Zip code: 1024 RJ
City: Amsterdam
Phone: +31648352638
email: p.heuvel@gmail.com

Intakes
intake date surgery date practitioner specializm diagnose procedure care plan surgery code SNOMED CT code related encounter
26-6-2011 27-6-2011 P. Voigt CTC (Cardio-thoracale Chirurgie) Heart valve disorder Heart valve replacement CP2903 1000263502 64915003 v1451
6-7-2012 7-7-2012 M.I.M. Versteegh CTC (Cardio-thoracale Chirurgie) NSCLC - Non-small cell lung cancer partial lobectomy CP2934 1000263813 173171007 v3251
22-3-2013 22-3-2013 A.P.M. Langeveld ENT Retropharyngeal abscess Trachea-tracheotomy CP2938 1000050465 48387007 v6751
24-3-2013 24-3-2013 E.M.J.M. van den broek ENT Retropharyngeal abscess retropharyngeal abscess CP3953 1000049161 172960003 v6751
27-3-2013 27-3-2013 R.J.P. Briet ENT Retropharyngeal abscess Trachea-extubatie CP1283 1000050159 309812005 v6751

Device
device hopital/home dose admission route start date presciber SNOMED CT code
Feeding tube hopital N.A. tube 10-4-2013 R.A. van den Berk 61420007

Lab results
diagnostic blood report
date substance value status
2013-04-02 glucose 6,3 mmol/l abnormal
2013-04-02 base excess 12,6 mmol/l abnormal
2013-04-02 carbon dioxide 6,2 mm[Hg] abnormal
2013-04-02 erytrocyten 18,7 g/dl abnormal
2013-04-02 Hemoglobin 7,5 g/dl abnormal

Anamnese

date: 8-6-2012 Bronchoscopy; several biopsy specimens were taken from pathological mucosa, right main bronchus specimen sent for pathologic analysis. Bronchoscopy because of atelectasis right. X-thorax; increase in atelectasis and pleural liquid. Bronchoscopy;
-fluids drained from right main bronchus
-pathologic mucous membrane right bronchus, easily bleeding
-left bronchial system open date: 18-3-2013 Antiobiotic policy with retropharyngeal abscess with prolapse to the mediatinum. No surgical possibility to fully drain the mediatinum.

Physical investigation

date: 18-3-2013 Neck; swelling and redness pretracheal extending to chest. No fluctuation, however induration is present. Swelling back pharynx, also present in postcricoid area. Light stridor sound when breathing. Overall condition is good. Scoop; little supraglottic swelling, vocal chords not judgable.

Additional research

CT thorax: no mediastinal/retropharyngal coloring of the fluid collections. Diffuse edema retro/parapharyngeal and mediastinitis. Preoperative culture shows; S pyogenes, sensitivity for penicillin and E. cloacae, sensitivity for vancomycin.

Policy

Stop vancomycin prescription. Continue penicillin and start vancomycin supplementation. Total treatment time is approximately 6 weeks. In consultation with the IC/anesthesia; intubation. Analyze lower respiratory tract.

Conclusion

Extubation on OR. Normal voice, no stridor. However, hypoxic at low respiratory tract obstruction with 84% O2 and rapid breathing.

Patient case 2

Patient name: Roel Bor
Patient number: 123456789
Date of birth: 1960-03-13
Gender: Male

Patient contact information

Address: Bos en Lommerplein 280
Zip code: 1055 RW
City: Amsterdam
Phone: +31612345678
Roel Bor is in his mid-fifties, works for an IT-company and has two healthy children and a wife. His uncle unfortunately was less healthy and died of cancer. At the end of 2012, Roel was also diagnosed with a tumor in the Erasmus Medical Center. His tumor is located in the head-neck area. The standard treatment for that is TPF-chemotherapy. The tumor is not fully curable due to its position, but it was optimally minimized with the therapy in the AUMC. Two severe complications followed the treatment, namely bacterial sepsis (streptococcus aureus) and renal failure. Both were stabilized within a short period through medication (see care plan). Roel thereafter had his ups and downs with the last known condition of a severe fever, for which he received among other treatment (paracetamol). On a side-note and as a final statement: the patient suffers from house dust allergy.

Intakes
practitioner organization careplan start date substance condition other participant procedure encounter ID surgery code SNOMED CT code
A. Bronsig Artis University Medical Center CP3928 2013-03-11 potassium fever Carla Espinosa 20130404 100028475 64915003
A. Bronsig Artis University Medical Center CP7364 malignant tumor chemotherapy 20130128 100028475 363346000
A. Bronsig Artis University Medical Center CP8766 2013-03-11 Bacterial sepsis Luigi Maas observation 20130311 100028475 363346000

Diagnoses
practitioner date encounter reason condition medication medication prescription procedure diagnostic report issued by
A. Bronsig 28-1-2013 20130128 chemotherapy malignant tumor chemotherapy BUMC
A. Bronsig 4-3-2013 20130404 fever fever
A. Bronsig 11-3-2013 20130311 sepsis Bacterial sepsis AUMC
A. Bronsig 11-3-2013 20130311 renal Renal insufficiency AUMC

Observations
practitioner date observation value status SNOMED CT code
Luigi Maas 11-3-2013 Blood culture for bacteria Gram-positive bacteria positive 8745002
A. Bronsig 4-4-2013 temperature taken 39 degrees Celsius1 high 89003005
A. Bronsig 4-4-2013 Serum bicarbonate measurement 28mmol/L normal 271239003
Luigi Maas 4-4-2013 Serum creatinine raised 122 umol/L high 166717003
Luigi Maas 4-4-2013 Epidermal Growth Factor Receptor Negative for EGF receptor expression (Non-small cell lung cancer) negative 427038005