Maturity Level: 1 | Standards Status:Trial Use |
Table of Contents
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.
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.
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.
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:
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:
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.
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.
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.
We provide a detailed example to show how sequence resource can be used to represent record of observed sequence by different method.
The diagram above describes 4 optional ways provided in the MolecularSequence resource to encode sequencing data. Here are the corresponding examples
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.
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.
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)
We provide an example of an Observation-genetics instance which records a variant detected in the patient. (we call this example A)
An example of an Observation instance which records knowledge-based clinical interpretations for the variant represented in A.
An example of an Observation instance which records PCR validation test for the variant in A.
We provide the following examples to reveal how PGx data can be harmonized within the FHIR specification. Detailed discussion will be put here.
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. |
An example of a genetic test report for a patient with FamilyHistory.
An example of a comprehensive bone marrow report.
A complex extension is added on top of the ServiceRequest resource. Here is the structure of the extension:
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.
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.
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:
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).
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>
Example of a HLA genotyping report
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.
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.
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
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.
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:
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:
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
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”.
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
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 /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 ”
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
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
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.
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
Search for results from nephrotic syndrome panel
Get /DiagnosticReport& _profile=http://hl7.org/fhir/StructureDefinition/diagnosticreport-genetic& code=N0336& patient=123
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
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
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
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
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.
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:
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 |
Maturity Level: N/A | Standards 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 |
Maturity Level: 0 | Standards 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.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.
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.
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.
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.
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).
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
- a FHIRPath statement selecting which of the subnodes is to be included[field]
- the name of a sub-property with a specified value that must be matched for the field to be included_offset
- specify the offset to start at for a repeating element (see below)_count
- specify how many to elements to return from a repeating listFHIRPath:
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.
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:
optional
: true | false. (default is false). If the server cannot resolve the reference (e.g. resource does not exist, or user security rights or choices do not permit resource to be seen), and optional is not true, the server returns an error instead of the graph output{ id subject { reference resource { ...on Patient { birthDate } ...on Group { name } } } code {coding {system code} } }
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.
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:
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.
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).
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.
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
@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"] }
@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"] }
@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" }
@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:
@singleton
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 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?
FHIR Infrastructure Work Group | Maturity Level: N/A | Standards Status: Informative |
This page will be the FHIR Glossary, but it has not, as yet, been created.
Looking for volunteers to take this on...
FHIR Infrastructure Work Group | Maturity Level: N/A | Standards 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):
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
1.8.0 |
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 |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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:
Technical Changes:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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:
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
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
1.0.2 |
Technical Correction 1, Oct 24 2015 A series of technical corrections to the specification following extensive review:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
1.0.1 |
DSTU 2, Sept 23 2015 Changes of significance during the QA process:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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
New Data Types Changed Data Types
New Resources
Removed Resources
Renamed Resources
Changes Inside Resources
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
0.4.0 |
Draft For Comment, January 2015 Ballot Breaking Changes (full list):
New Resources:
New Implementation Guides (see
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
0.3.0 |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
0.2.1 |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
0.2.0 |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
0.1.0 |
|
Note: a useful tool for displaying the differences between pages is the W3C HTML Diff engine.
Maturity Level: Normative | Standards 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 | |
read | Read the current state of the resource |
vread | Read the state of a specific version of the resource |
update | Update an existing resource by its id (or create it if it is new) |
patch | Update an existing resource by posting a set of changes to it |
delete | Delete a resource |
history | Retrieve the change history for a particular resource |
Type Level Interactions | |
create | Create a new resource with a server assigned id |
search | Search the resource type based on some filter criteria |
history | Retrieve the change history for a particular resource type |
Whole System Interactions | |
capabilities | Get a capability statement for the system |
batch/transaction | Update, create or delete a set of resources in a single interaction |
history | Retrieve the change history for all resources |
search | Search 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.
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.
The interactions on this page are defined like this:
VERB [base]/[type]/[id] {?_format=[mime-type]}
base
: The Service Base URLmime-type
: The Mime Typetype
: The name of a resource type (e.g. "Patient")id
: The Logical Id of a resourcevid
: The Version Id of a resourcecompartment
: The name of a compartmentparameters
: URL parameters as defined for the particular interaction{}
is optionalImplementations 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.
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:
?
) is ignoredhttp:
and https:
SHALL NOT be used to refer to different underlying objects
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.
Each resource has an associated set of resource metadata elements. These map to the HTTP request and response using the following fields:
Metadata Item | Where 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"
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.
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.
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.
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.
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.
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:
application/fhir+xml
application/fhir+json
application/fhir+turtle
(only the Turtle format is supported)Servers SHALL support server-driven content negotiation as described in section 12 of the HTTP specification.
Implementation Notes:
application/x-www-form-urlencoded
(Specification) is also accepted for posting search
requests.application/xml+fhir
and application/json+fhir
to application/fhir+xml
and application/fhir+json
.
Servers MAY also support the older mime types, and are encouraged to do so to smooth the transition process.
406 Not Acceptable
is the appropriate response when the Accept
header requests a format that the server
does not support, and 415 Unsupported Media Type
when the client posts a format that is not supported
to the server.
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.
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.
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.
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:
meta.version
is not supported (server) or used (client)meta.version
is supported (server) or used (client)meta.version
is supported, and version aware updates are used - Version ID must be correct for updates (server) or will be specified (If-match header) for updates (client)
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.
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.
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.
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.
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.
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):
400
Bad Request - resource could not be parsed or failed basic FHIR validation rules (or multiple matches were found for conditional criteria)401
Not Authorized - authorization is required for the interaction that was attempted404
Not Found - resource type not supported, or not a FHIR end-point405
Method Not allowed - the resource did not exist prior to the update, and the server does not allow client defined ids409
/412
- version conflict management - see below422
Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rulesAny 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.
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:
400
Bad Request error indicating the client id specification was a problem preferably with an OperationOutcome412
Precondition Failed error indicating the client's criteria were not selective enough preferably with an OperationOutcome
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.
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).
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:
application/json-patch+json
application/xml-patch+xml
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:
412
Precondition Failed error indicating the client's criteria were not selective enoughThe 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:
generated
, the server could reject the PATCH operation
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.
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.
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:
delete
on the matching resource412
Precondition Failed error indicating the client's criteria were not selective enough.
A server indicates whether it can delete multiple resources in its Capability Statement (.rest.resource.conditionalDelete)
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.
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):
400
Bad Request - resource could not be parsed or failed basic FHIR validation rules404
Not Found - resource type not supported, or not a FHIR end-point422
Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules. This should be accompanied by an OperationOutcome resource providing additional detailIn 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.
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:
200
OK412
Precondition Failed error indicating the client's criteria were not selective enough
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.
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¶m2=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 forPOST
so that invoking a search byGET
orPOST
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):
400
Bad Request - search could not be processed or failed basic FHIR validation rules401
Not Authorized - authorization is required for the interaction that was attempted404
Not Found - resource type not supported, or not a FHIR end-pointTo 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.
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 |
normative | As above, but only the normative portions of the Capability Statement |
terminology | A 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 interaction | returns a capability statement describing the server's current operational functionality |
CapabilityStatement end-point | manages 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.
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.
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:
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.
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:
DELETE
interactionsPOST
interactionsPUT
or PATCH
interactionsGET
or HEAD
interactionsIf 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:
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.
A server may choose to accept bundle types other than batch
or transaction
when POST
ed 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.
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 : integer | The 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 : instant | Only 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 : reference | Only 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.
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:
read
interaction for any resource it accepts update
interactions onread
s the latest version of the resourceupdate
interaction, and is able to handle a 409
or 412
response (usually by trying again)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.
Both client and server systems SHOULD clearly document how transaction integrity is handled, in the documentation in the CapabilityStatement.
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.
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").
This specification defines or recommends some custom headers that implementers can use to assist with deployment/debugging purposes:
X-Request-Id | A 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-Id | A client assigned request id echoed back in the response |
X-Forwarded-For | Identifies the originating IP address of a client to an intermediary |
X-Forwarded-Host | Identifies the original host requested by the client in the Host HTTP request header |
X-Intermediary | Stamped 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.
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 | Path | Request | ||||
---|---|---|---|---|---|---|
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 |
| 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 | Parameters | N/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:
Interaction | Response | |||||
---|---|---|---|---|---|---|
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 body | O: 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: CapabilityStatement | N/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/Resource | N/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.
Maturity Level: 2 | Standards 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.
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. |
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 |
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>
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>
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.
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).
No need for filters identified yet.
No need for implicit value sets identified yet.
Maturity Level: 3 | Standards 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: |
Work Group Standards Status:Informative |
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.
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:
For more general considerations, see the Security and Privacy module.
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 Name | Maintainer | Link |
---|---|---|
Healthintersections | Grahame Grieve | http://fhir3.healthintersections.com.au/ |
Spark | Furore Informatica | http://spark.furore.com/ |
HAPI | University Health Network / James Agnew | http://fhirtest.uhn.ca/ |
sqlonfhir | Telstra Health / Brian Postlethwaite | http://sqlonfhir-stu3.azurewebsites.net/fhir |
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.
Language | Library | Link | License |
---|---|---|---|
.NET / C# | FHIR .NET API | https://github.com/ewoutkramer/fhir-net-api | BSD-3 |
Java | HAPI FHIR | http://hapifhir.io | Apache 2.0 |
Swift | Swift FHIR | https://github.com/smart-on-fhir/Swift-FHIR | Apache 2.0 |
JavaScript | fhir.js | https://github.com/smart-on-fhir/fhir.js | MIT |
Python | Client Py | https://github.com/smart-on-fhir/client-py | Apache 2.0 |
Pascal | FHIR Pascal | http://hl7.org/fhir/downloads.html | BSD-3 |
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.)
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.
The following are a few ways that implementers can seek help as they work with FHIR:
hl7_fhir
)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.
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 |
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.
Maturity Level: N/A | Standards 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:
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 name: Pieter van den Heuvel Patient number: 0108173 Date of birth: 17-11-1944 Gender: Male
Address: van Egmondkade 23 Zip code: 1024 RJ City: Amsterdam Phone: +31648352638 email: p.heuvel@gmail.com
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 | 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 |
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 |
Patient name: Roel Bor Patient number: 123456789 Date of birth: 1960-03-13 Gender: Male
Address: Bos en Lommerplein 280 Zip code: 1055 RW City: Amsterdam Phone: +31612345678Roel 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.
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 |
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 |
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 |