1.0: Welcome to FHIR®

Fast Healthcare Interoperability Resources (FHIR™) defines a set of 'resources' to represent health and healthcare administration-related information. These resources express granular clinical and administrative concepts that can be electronically exchanged in order to quickly and effectively solve system interoperability problems in healthcare and related processes. The resources cover the basic elements of healthcare - patients, admissions, diagnostic reports, medications and problem lists - with their typical data elements and also support a range of richer and more complex clinical models. The simple direct definitions of the resources are based on thorough requirements gathering, formal analysis and extensive cross-mapping to other relevant standards.

Search FHIR

1.0.1: Disclaimer and Warning of Use

FHIR Resource definitions developed by HL7 are derived from the considerable collective experience of the HL7 membership and wide community feedback from the development and application of a spectrum of health care interoperability solutions. However, Resource definitions are generalized to support multiple contexts of use. It is the responsibility of the persons or organizations using these Resources to ensure their use is fit for the particular purpose in which they are used, including validation for clinical and operational use.

1.0.2: Notes on Draft Standard for Trial Use (DSTU) status

FHIR is being balloted as a Draft Standard for Trial Use. A complete description of the rules for DSTU can be found in HL7's Governance and Operations Manual (http://www.hl7.org/documentcenter/public/membership/HL7_Governance_and_Operations_Manual.pdf) . However, the essential points for implementers are covered below:

The purpose of this phase in the approval process is to gain real-world implementation experience based on a vetted, approved version of the specification prior to locking any particular aspect of the specification "in stone". This specification makes a number of statements about what HL7 will and will not do in future versions of this specification. These statements generally concern expectations around forward and backward compatibility and how the specification will evolve. However, these statements only hold once the specification is approved as a "normative" standard - the approval process that will occur subsequent to DSTU. Between different DSTU versions and between the DSTU and final approved normative version of the specification and its resources, these rules around compatibility and other issues will not be enforced. Elements may be renamed, moved, dropped or otherwise changed. Extensions may be promoted to core elements and core elements may be demoted to extensions. Wire syntax and invocation sequences may be changed. Other breaking changes may occur.

Major changes are not expected, however the risk does exist. If they occur, such changes will not be undertaken without good supporting rationale. However, long term implementability and usefulness of the specification will receive greater weight when evaluating change than impact on existing DSTU implementations. DSTU implementers should therefore provide flexibility in their architecture that will allow them to more easily accommodate changes to the specification. They should also consider how their implementations might peacefully coexist with implementations of future DSTU and normative versions that may not be fully compatible.

1.0.3: FHIR License

FHIR plain English license:

• FHIR is © and ® HL7. The right to maintain FHIR remains vested in HL7
• You can redistribute FHIR
• You can create derivative specifications or implementation-related products and services
• Derivative Specifications cannot redefine what conformance to FHIR means
• You can't claim that HL7 or any of its members endorses your derived [thing] because it uses content from this specification
• Neither HL7 nor any of the contributors to this specification accept any liability for your use of FHIR

Note: Why not use a standard open source license? We'd like to use Creative Commons (http://creativecommons.org/) or a license listed here (http://opensource.org/licenses/alphabetical) , but none of them actually deliver on the plain English intent above in important ways. We aspire to meet these requirements from the Open Source Initiative (http://opensource.org/osr-intro) , though patents are a problem (http://xml.coverpages.org/patents.html) .

While we resolve the questions around the long term license, the following license, adapted from the OMG (http://www.omg.org) (thanks for allowing this), applies:

Subject to all of the terms and conditions below, HL7 hereby grants you a fully-paid up, non-exclusive, non-transferable, perpetual, worldwide license (without the right to sublicense) to use this specification to create and distribute software and special purpose specifications that are based upon this specification and to use, copy and distribute this specification as provided under the United States Copyright Act; provided that:

1. both the copyright notice identified above and this permission notice appear on any copies of this specification;
2. the use of the specifications is for informational purposes and will not be resold or transferred for commercial purposes;
3. no modifications are made to this specification.

This limited permission automatically terminates without notice if you breach any of these terms or conditions. Upon termination, you will destroy immediately any copies of the specifications in your possession or control.

GENERAL USE RESTRICTIONS

Any unauthorized use of this specification may violate copyright laws, trademark laws, and communications regulations and statutes. This document contains information which is protected by copyright. All Rights Reserved. No part of this work covered by copyright herein may be reproduced or used in any form or by any means--graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems--without permission of the copyright owner.

DISCLAIMER OF WARRANTY

WHILE THIS PUBLICATION IS BELIEVED TO BE ACCURATE, IT IS PROVIDED "AS IS" AND MAY CONTAIN ERRORS OR MISPRINTS. HL7 MAKES NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS PUBLICATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OF TITLE OR OWNERSHIP, IMPLIED WARRANTY OF MERCHANTABILITY OR WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE OR USE. IN NO EVENT SHALL HL7 BE LIABLE FOR ERRORS CONTAINED HEREIN OR FOR DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, RELIANCE OR COVER DAMAGES, INCLUDING LOSS OF PROFITS, REVENUE, DATA OR USE, INCURRED BY ANY USER OR ANY THIRD PARTY IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS MATERIAL, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

The entire risk as to the quality and performance of software developed using this specification is borne by you. This disclaimer of warranty constitutes an essential part of the license granted to you to use this specification.

CONFORMANCE

HL7 is and shall at all times be the sole entity that may authorize developers, suppliers and sellers of computer software or specifications to use certification marks, trademarks or other special designations to indicate compliance with FHIR. Software developed under the terms of this license may claim compliance or conformance with FHIR if and only if the software compliance is of a nature fully matching the applicable conformance points as stated in the FHIR specification. Software developed only partially matching the applicable compliance points may claim only that the software was based on FHIR, but may not claim compliance or conformance with this specification. In the event that testing suites or processes are implemented or approved by HL7, Inc., software developed using this specification may claim compliance or conformance with the FHIR specification only if the software satisfactorily completes the testing suites.

1.0.4: Credits

FHIR is a specification produced by the HL7 Community. Many individuals contribute to the FHIR specification. Of particular note:

• The Editorial team is Grahame Grieve, Ewout Kramer, Lloyd Mckenzie
• The Govenance board (http://wiki.hl7.org/index.php?title=FHIR_Governance_Board) is Ron Parker, Woody Beeler, Ewout Kramer, John Quinn and Grahame Grieve
• The Managment board (http://wiki.hl7.org/index.php?title=FHIR_Management_Group) is Lorraine Constable, Jean Duteau, Hugh Glover, David Hay, John Moehrke, Brian Pech, Lloyd McKenzie, Ron Parker and John Quinn
• The following organizations have helped by attending Connectathons: Health Intersections (http://www.healthintersections.com.au) , Furore (http://furore.com) , Orion Healthcare (http://www.orionhealth.com) , GE Healthcare (http://ge.com) , Mohawk College (http://www.mohawkcollege.ca/) , Thrasys (http://www.thrasys.com/) , HealthFire, Interfaceware, Gordon Point Informatics, NProgram, and Blue Wave

1.0.5: Outstanding Work Items

These are recognized outstanding tasks that are yet to be completed. There are many tasks still to be done that are not listed here.

• Improve summary material for non-technical users, particularly a clinically-orientated benefits summary
• Should a resource identify which profile(s) it conforms to? (why?) (related discussion: rules of handling and version dependency)
• What consistent life cycle patterns do we need for resources?
• How to do digital signatures in json? For servers that store json/bson?
• How do we define the Zed resource (or the resource with no name)
• Minor technical issues:
  • issue with json lists and datatype choices
  • de-anonymize div element?
  • Fix problem with schematron paths capturing resources and datatypes used in extensions (by looking for valuexxx)?
  • improve path display for schematrons
  • Decide what our policy is on including formatting in Excel columns (e.g. italics in formal constraints)
  • remove profile bindings from bindings summary (i.e. EntityNamePartQualifier)
  • Many presentation improvements for presenting profiles

Additional open issues can be found throughout the text of the specification and on the FHIR active discussions (http://wiki.hl7.org/index.php?title=Category:Active_FHIR_Discussion) wiki page.

1.0.6: Version History

Archived Versions of FHIR

These archives only keep the more significant past versions of FHIR, and only the book form, and are provided for purposes of supporting html diff tools. A full archive history of everything is available through the HL7 gForge archives.

• Version 0.08, Connectathon 2013 May Atlanta. (Diff with current)
• Version 0.06, Second Draft for Comment. (Diff with current)
• Version 0.05, Version for first Draft for Comment ballot. (Diff with current)
• Version 0.01, First Archived Version (During Vancouver WGM), May 14, 2012. (Diff with current)

1.1: Overview

Fast Healthcare Interoperability Resources (FHIR) defines a set of resources for use in exchanging information about the healthcare process. Resources are:

• Atomic - they are the smallest defined unit of operation and a transaction scope of their own
• Connected - resources refer to other resources to allow for clean modular reuse of information
• Independent - the content of a resource can be processed without having to retrieve referenced resources
• Simple - each resource definition is easy to understand, and to implement without needing specialized tooling or infrastructure (though that can be used if desired)
• RESTful - resources are able to be used in a RESTful exchange context
• Flexible - resources can also be used in non-RESTful contexts, such as messaging or SOA architectures and can be moved in and out of RESTful paradigms as convenient
• Extensible - resources can be extended to allow for local requirements without impacting on interoperability
• Webcentric - where possible and appropriate, open internet standards are used for data representation
• Free for use - the FHIR specification itself is open - anyone can implement FHIR or derive related specifications without any IP restrictions

In addition to the basic resources, FHIR defines a lightweight implementation framework that supports the use of these resources in RESTful environments, classic message exchanges, human-centric clinical documents and enterprise SOA architectures. Each of these approaches provides its own benefits - FHIR provides the underpinning enablement that makes the choosing one of these painless and enables enterprises to choose their own paradigm without forsaking interoperability with other paradigms.

Though the resources are simple and easy to understand, they are backed by a thorough, global requirements gathering and formal modeling process that ensures that the content of the resources is stable and reliable. The resource contents are mapped to solid underlying ontologies and models using computable languages (including RDF) so that the definitions and contents of the resources can be leveraged by computational analysis and conversion processes.

FHIR also provides an underlying conformance framework and tooling that allows different implementation contexts and enterprises to describe their context and use of resources in formal computable ways and to empower computed interoperability that leverages both the conformance and definitional frameworks.

The combination of the resources and the 3 supporting layers (implementation frameworks, definitional thoroughness, and conformance tooling) frees healthcare data so that it can easily flow to where it needs to be (hospital production systems, mobile clinical systems, cloud based data stores, national health repositories, research databases, etc.) without having to pass through format and semantic inter-conversion hurdles along the way.

Compared to the all the other approaches, FHIR... [-- Obligatory: insert your FHIR FIRE related joke here --].

1.1.1: Roadmap

This specification is structured into 3 parts: the introduction, the implementation section and the resource definitions.

1.1.1.1: Introduction

The introduction provides foundational material that is required to understand and use resources:

• Introduction: Overall introduction, useful links and the FHIR license
• This roadmap
• Resource Definitions: An explanation of the general content and identification of resources
• Resource Formats: An explanation of the general format and representation of resources
• Data Types: Common re-usable patterns encountered throughout healthcare data and used in the resources
• Using Codes: Explains how the use of codes (code systems, terminologies, classifications, ontologies) is managed in FHIR
• Extensibility: Describes the extension section of the resource and specifies the rules that apply to its use

1.1.1.2: Implementation

The implementation section explains how resources are used in various contexts:

• Implementation: General requirements for using resources and various useful things including schema packs and reference implementations
• REST (HTTP): Defines a lightweight HTTP based paradigm for using resources
• Messaging (§2.3): A simple request/response message based transactional framework (equivalent to HL7 v2)
• Documents (§2.4): Clinical documents contain attested content that are both human readable and computer processable and can be exchanged and signed as single bundles (equivalent to CDA)
• Security (§2.6): A brief discussion of security considerations associated with using FHIR

1.1.1.3: Resources

The resources section enumerates the resources:

• Resources: An index of the defined resources in categories
• The resources in alphabetical order

For each resource, the following pages are provided:

• Content: Provides context for the resource and defines its content with a simple XML format and some additional description. Formal definitions such as W3C schema and others are also provided. Also describes events and search criteria associated with the resource
• Examples: Provides one or more examples that show how the resource is used
• Formal Definitions: A table of the full formal definitions for each element in the resource along with mappings to other standards and ontologies
• Design Notes: Explanations of some of the less obvious aspects of the resource and explanation of why the resource is structured in a particular way. Not all resources have design notes and implementers do not need to read them
• Profiles: A list of profiles of the resource that are provided as part of the standard. Profiles may be provided to illustrate some aspect of the use of a resource or because certain particular uses of a resource are sufficiently common to warrant a standard profile

1.1.2: Community

The FHIR community meets inside the wider HL7 community (http://hl7.org) and draws on its extensive human resources, institutional memory, previous standards and corporate support. HL7 itself owns FHIR and makes it freely available and the community relies on HL7 provided infrastructure.

The primary resources used by the FHIR community are the HL7 wiki (http://wiki.hl7.org/index.php?title=FHIR) , and the FHIR email list (http://wiki.hl7.org/index.php?title=FHIR_email_list_subscription_instructions) . In addition, the community holds regular face to face meetings as part of the HL7 Working Group meetings (http://www.hl7.org/events/workgroupmeetings.cfm?ref=nav) . The formal governance arrangements that manage FHIR development are documented (where? - todo)

Note that each page contains a direct link to its matching wiki page where input from the wider community is managed. Community input is very welcome - please consider making comments.

1.1.3: HL7 EHR Functional Model

The HL7 EHR System Functional Model provides a reference list of functions that may be present in an Electronic Health Record System. While FHIR is an implementation focused on exchange of information in healthcare, this often happens in the context of an EHR. This table briefly describes one way that FHIR can be used to meet the requirements described in the EHR-FM and is provided to help readers of the FHIR specification understand how FHIR can be used. There are many other equally valid ways to implement the EHR-FM and to make use of FHIR.

The EHR functional model describes several modes for interaction between systems. Each of these can be implemented in several different ways using FHIR

The combination of a properly secured and managed FHIR server, along with enforced use of the SecurityEvent (§3.39) and Provenance (§3.37) resources ensures that the core record management functions defined in the EHR-FM are met:

• Lifespan/Lifecycle tracking, including capturing source, origination and authorship information, along with tracking of views and exchanges
• Attestation for accuracy and completeness, along with digital signature
• A full version history with content retention
• Retention and persistence

Additional functionality not defined (yet?) in FHIR is required to ensure non-repudation, access control, and consent tracking.

1.2: Resource Definitions

A resource is an entity that:

• Has a known identity by which it can be addressed
• identifies itself as one of the resource types defined in this specification
• contains a set of structured data items as described by the resource definition
• contains a human readable XHTML representation of the content of the resource
• may change over time

Resources have multiple representations. A resource is valid if it meets that above rules, and is represented in either XML or JSON according to the rules defined in this specification. Other representations are allowed, but are not described by this specification.

This specification defines a series of different resource types that can be used to exchange and/or store data in order to solve a wide range of healthcare related problems, both clinical and administrative. In addition, this specification defines several different ways of exchanging the resources.

1.2.1: Contents of a Resource

All resources have the following aspects:

• A base set of defined data elements
• Extensions (optional) - additional data elements added by implementations (see "Extensibility")
• A human readable narrative description of the resource (see "Narrative")
• Contained resources - additional resources that are part of the identification and transaction space of this resource (see below (§1.2.6.2))
• Metadata - important information about the resource that is not part of the content model of the resource
• Tags - labels affixed to the resources that may be used to define additional operation behaviour such as security, workflow, etc

The contents of the base resource from which all other resources derive are:

<[Name] xmlns="http://hl7.org/fhir">
 <extension><!-- 0..*  Extension   See Extensions  --></extension>
 <language value="[code]"/><!-- 0..1 Human language of the content (BCP-47) -->
 <text><!-- 1..1 Narrative Text summary of resource, for human interpretation --></text>
 <contained><!-- 0..*  Resource   Contained Resources  --></contained>
 <!-- Defined Data Elements for Resource -->
</[Name]>

These elements must always appear in this order. These basic elements shared by all resources come first in order to support consistent definitions for schema and UML derived code.

The optional language element specifies the base language of the resource using the codes defined in BCP 47 (http://tools.ietf.org/html/bcp47) . Note that not all the content of the resource has to be in the language. If a language is specified, it should also be specified on the Narrative Text.

The language element is provided to support indexing and accessibility (e.g. text-to-speech use the language tag). The html language tag in the narrative applies is used when processing the narrative. The language tag on the resource is provided for use to specify the language of alternate presentations generated from the data in the resource

1.2.2: Resource Metadata

The metadata properties are key aspects of the resource and how it behaves. For implementation reasons, these are represented outside the resource:

In any environment where the resources are used, the technical details of how these metadata elements are represented will need to be resolved. For further details, see Implementation Details, which also contains a discussion of how resource identity is maintained.

Resource ids are case sensitive. Ids are always opaque, and systems need not and should not attempt to determine their internal structure. However the id is represented, it must always be represented in the same way in resource references and URLs. Ids can be up to 36 characters long, and contain any combination of ASCII letters, numerals, "-" and ".".

1.2.2.1: Tags

In addition to the basic contents of Resources, and their metadata, each resource can be labelled with one or more "Tags". These tags can be used to associate additional operational information with the Resources, including defining security labels used in access control policies, workflow management, and other uses. Tags are attached to resources, and and exchanged with the resource. Tags are never used to keep information that needs to be understood when interpreting the content of a resource; their function is limited to finding and controlling access to the resource.

Each tag has two properties:

The Uri may be a reference to a healthcare vocbulary, including ones defined in this specification, such as the basic security label set (§2.6.7), or vocabularies such as those defined by HL7 (v2 and v3/CDA), Loinc, or Snomed-CT. Alternatively, the URI may be one defined by the implementation in the local context. Literal references that refer directly to a description of the tag (typically just an HTML page) are preferred over symbolic references but this is not required.

If the end user application provides functionality to the user that allows the user to affix arbitrary text tags to the resource for their own purpose, the application can automatically construct a Uri by appending the mime encoding of the Label to the base URL "http://hl7.org/fhir/tags/text/". When applications processing resources see this base URL, they can automatically know that this is a pure text label with no formal meaning.

1.2.3: Resource Bundles

One common operation performed with resources is to gather a collection of resources into a single instance. In FHIR this is referred to as "bundling" the resources together. The resource bundle is not just a list of references to resources, but includes their whole content. These resource bundles are useful for a variety of different reasons, including:

• Returning a set of resources that meet some criteria as part of a server operation
• Returning a set of versions of resources as part of the history operation on a server
• Storing a collection of resources
• Exchanging a set of resources as part of a message transaction
• Grouping a self-contained set of resources to act as an exchangeable and persistable group with clinical integrity (i.e. a clinical document)

Conceptually, a bundle has an identifier (url) and a date updated, and a list of resources. For each resource in the list, the bundle has the resource and also it's metadata as listed above. Each entry in the bundle retains it's original identifier. This means that applications reading the bundle should always look for a resource by it's identity (after converting relative URLs absolute URL) in the bundle first before trying to access it by it's URL.

1.2.4: Conformance

The contents of the resource and the formats used to represent it must conform to the rules described in this specification. Because of it's general nature and wide applicability, the rules made in this specification are generally loose compared to the rules suitable for particular use cases. This specification provides a conformance layer that implementers and national/regional programs can use to provide a computable statement about how the resources and their exchange paradigms are used to solve particular use cases. This conformance layer is delivered through use of the Conformance (§3.5) and Profile (§3.36) resources.

The specification also provides a number of technical resources that can assist with enforcing conformance to this base specification:

• Schema & Schematron
• Reference Platforms
• TODO: RDF/OWL, etc

Note that none of these are able to check complete conformance to this specification.

The data elements defined resources and data types have 4 properties that are directly related to conformance: Cardinality, Is-Modifier, Must-Support, and Cardinality. These interact to place conformance requirements on implementations.

1.2.5: Cardinality

The cardinality of an element is to upper and limit of the number of elements present in the actual resource. When present, elements cannot be empty - they must have either a value attribute, child elements, or extensions. This specification only defines the following cardinalities: 0..1, 0..*, 1..1, and 1..*. Profiles that describe specific use cases may use other cardinalities within the limits defined by the resources.

In this specification, very few elements have a minimum cardinality of 1. Resources are used in many contexts, often quite removed from their primary use case, where information is sometimes very incomplete. For this reason, the only elements that have a minimum cardinality of 1 are those where they are necessary to basic understanding of the element that contains them. The minimum cardinalities should not be taken as a guide to which elements are expected to be present in any particular use of the resource.

1.2.5.1: Is-modifier

Is-Modifier is a boolean property that is assigned when an element is defined, either as part of the base resource contents in this specification, or when profiles declare extensions. An element is labelled "Is-Modifier = true" if the value it contains may change the interpretation of other elements or the resource as a whole. Typical examples of elements that are labelled "Is-Modifier" are elements such as "status", "active", or "certainty". The value of Is-Modifier cannot be changed when element usage is described in a Resource Profile (§3.36). When an element is labelled as Is-Modifier, the documentation must be clear about why it is a modifier, and/or which elements the element may modify.

Generally, elements labelled "Is-Modifier = true" also have a minimum cardinality of 1, to introduce certainty in their handling. If the value of such an element is not explicit in the instance, or known by the context, the resource cannot be safely understood. Irrespective of the minimum cardinality, implementations producing resources SHALL ensure that appropriate values for mustUnderstand elements are provided. Is-Modifier elements SHALL be represented in the narrative summary of the resource.

Implementations processing resources SHALL understand the impact of the element when they process the resource. Implementations are not required to "support" the element in any meaningful way - they amy achieve this by rejecting instances that contain values outside those they support (for instance, an application may refuse to accept observations with a reliability != "ok"). Alternatively, implementations may be able to be sure, due to their implementation environment, that such values will never occur. However applications SHOULD always check the value irrespective of this.

Servers and background processes that move resources around are not "processing the data of the resource", and these applications are not required to check for unknown extensions. Any process that copies data out of a resource for use in another context (display to a human, decision support, exchange in another format that doesn't support extensions) is processing the data.

1.2.5.2: Must-Support

Labelling an element Must-Support means that implementations that produce or consume resources must provide "support" for the element in some meaningful way. Exactly what this means is impossible to describe or clarify as part of the FHIR specification.

For this reason, the specification itself never labels any elements as must-support. This is done in Resource Profiles (§3.36), where the profile labels an element as mustSupport=true. When a profile does this, it must also make clear exactly what kind of "support" is required, as this can mean many things.

Note that an element that has the property IsModifier is not necessarily a "key" element (e.g. one of the important elements to make use of the resource), nor is it automatically mustSupport - however both of these things are more likely to be true for IsModifier elements than for other elements.

1.2.5.3: Cardinality

All elements defined in FHIR have a cardinality as part of their definition - a minimum number of required appearances, and a maximum number allowed. This number specifies the number of times the element may appear in the instance. In the specification, the minimum number is always 0 or 1, and the maximum number is always 1 or *, meaning no limit. Profiles may use any whole number for both minimum and maximum cardinality, as long as minimum <= maximum.

For elements that have cardinality > 1, the order in which they appear may have meaning. Unless the element definition (either in this specification or the extension) defines a meaning to the order explicitly, the meaning of the order is not defined, and implementations are allowed to reorder the elements. Note that you cannot define a meaning for the order of the elements in a profile. When there is not definition of the meaning of the order, implementations that need to choose a single element from a list of elements for some use must do so based on the semantics of the content of the elements that repeats. Profiles and Implementation guides may often make rules about this selection process.

1.2.6: References between resources

The defined elements in a resource includes many references to other resources. The resources combine to build a web of information about healthcare.

References are always defined in one particular direction - from one resource (source) to another (target). The corresponding reverse relationship from the target to the source exists in a logical sense, but is not represented explicitly in the resource. Navigating these reverse relationships requires some external infrastructure to track the relationship between resources.

Because resources are processed independently, relationships are not considered to be transitive. For example, if a Problem (§3.34) resource references a particular Patient (§3.31) as it's subject, and it links to a Procedure (§3.35) resource as it's cause, there is no automatic rule or implication that the procedure has the same patient as it's subject. Instead, the subject of the procedure must be established directly in the procedure itself. Another way to state this is that the context of the subject is not "inherited" and it does not "conduct" along the relationship to procedure. The only exception to this in the case of contained resources (see below). Note that in practice, the relationships do need to describe a logical and coherent record.

In a resource, references are represented with a type, a reference, and a text description. The key property of the reference is the reference - resources are identified and address by their URL. The actual reference looks like this (see "XML Format" (§1.3.1.1) for details of the way resource contents are described):

<[name] xmlns="http://hl7.org/fhir">
 <type value="[code]"/><!-- 0..1 Resource Type -->
 <reference value="[string]"/><!-- 0..1 Relative, internal or absolute URL reference -->
 <display value="[string]"/><!-- 0..1 Text alternative for the resource -->
</[name]>

1.2.6.1: Terminology Bindings

Notes:

• The type must specify the resource type, whether or not the type of the resource reference is fixed for the element in the resource definition
• The reference element contains a url that is either an absolute URL, or a relative URL that is relative to the Service Base URL, or an internal fragment reference (see below)
• Using absolute URLs provides a stable scalable approach suitable for a cloud/web context, while using relative/logical references provides a flexible approach suitable for use when trading across closed eco-system boundaries. (see implementation issues for further discussion (§2.6.6))
• Absolute URLs do not need to point to a FHIR RESTful server, though this is the preferred approach. If the tail of the url conforms to the structure "/[type]/@[id]" or "/[type]/@[id]/history/@[id]" then it should be assumed that the reference is to a FHIR RESTful server. Whether or not the reference is to a FHIR RESTful server, the reference must point to a Resource as defined by this specification
• URLs are always considered to be case-sensitive and lowercase is preferred
• The display is generally not the same content as the Resource.text of the referenced resource. The purpose is to identify what's being referenced, not to more fully describe it

  <context>
    <type value="Patient" />
    <reference value="patient/@034AB16" />
  </context>

  <profile>
    <type value="Profile" />
    <reference value="http://fhir.hl7.org/svc/profile/@c8973a22-2b5b-4e76-9c66-00639c99e61b" />
  </profile>

  <custodian>
    <type value="Organization" />
    <reference value="organization/@123" />
    <display value="HL7, Inc" />
  </custodian>

1.2.6.2: Contained Resources

In some circumstances, the content referred to in the resource reference does not have an independent existence apart from the resource that contains it - it cannot be identified independently, and nor can it have it's own independent transaction scope. Typically, such circumstances arise where the resource is being assembled by a secondary user of the source data, such as a middleware engine. If the data available when the resource is constructed does not include record keys or absolute identification information, then a properly identified resource cannot be assembled, and even if an arbitrary identification was associated with it, the resource could never be the subject of a transaction outside the context of the resource that refers to it.

In these circumstances, the resource is placed directly in line in the reference. This should never be done when the content can be identified properly, as once identification is lost, it is extremely difficult (and context dependent) to restore it again.

     
 <Document xmlns="http://hl7.org/fhir">
  <extension>...</extension>
  <text>...</text>
  <contained>
    <Organization id="org1">
      <!-- whatever information is available -->
    </Organization>
  </contained>
  <information>
    <!-- other attributes -->
    <custodian>
      <type value="Organization" />
      <reference value="#org1" />
    </custodian>
    <!-- other attributes -->
  <information>
 </Document>

 
{ "Document" : {
  "extension" : { ... },
  "text" : { .. },
  "contained: [
    {"Organization" : {
      "_id" : "org1",
      .. whatever information is available ...
	}}
  ]
  "information: {
    ... other attributes ...
    "custodian" : {
      "type" : { "value" : "Organization" },
      "url" : { "value" : "#org1" }
	}
    ... other attributes ...
  }
}}

The type and url are always required, even though somewhat redundant in this case, to ensure that a single approach to resolving resource references can be used - simply be resolving the URL, and accessing accordingly.

Some notes about use and interpretation of contained resources:

• Contained resources share the same internal id resolution space as the parent resource
• Contained resources do not contain additional contained resources
• Resources that are contained inline also "inherit" context from their parent resource. For instance, if the parent resource contains a "subject", and the contained resource also has a a subject element defined, but does not specify any subject, a processing application may infer that the subject is the same. Note, however, that such inferences are specific to a particular circumstance. There is no rule, for instance, that the meaning of the "subject" element is the same in both parent and contained resources
• Contained resources do not need to contain any narrative

1.2.7: Inter-version Compatibility

The following rules will apply once the specification becomes a full normative specification. These rules ensure that implementations may process the content of the resources safely while exchanging data between applications using different versions of FHIR. However during the period of trial use of the specification, HL7 may make changes outside the limitations described here in response to discovered issues in the specification. Applications may wish to use resource tags (§1.2.2.1) to help manage this during the period of trial use.

There is no explicit version marker in the resource content. Once normative, subsequent versions of this specification may introduce new elements and/or content at any point in the resource contents, but the path and meaning of existing data elements will not be changed. Any value set or code list may be revised to include additional cods

Each binding to a value set or code system indicates whether the value list automatically grows as new codes are defined, whether the list may be extended in future versions of the specification, or whether the list cannot be changed at all in future versions.

The conformance layer (Conformance (§3.5) and Profile (§3.36)) have mandatory properties declaring the FHIR specification version, and these may be used to determine which version of FHIR an implementation is using.

In a typical scenario, mixed versions may need to exist, so applications SHOULD ignore elements that they do not recognize unless they are extensions with a mustUnderstand element with value="true". However, in a healthcare context, many application vendors are unwilling to consider this approach because of concerns about clinical risk or technical limitations in their software (i.e. schema based processing). Applications are not required to ignore unknown elements, but must declare whether they will do so in their conformance statements using the acceptUnknown element.

Additional discussion on interversioning issues can be found here: http://wiki.hl7.org/index.php?title=FHIR_interversion_compatibility.

1.3: Resource Formats

This page documents how the content of the resources are described, and how they are represented in XML and JSON.

1.3.1: Resource Definition

The resources are described in two different ways: a UML diagram that summarises the content, and an pseudo-XML syntax that provides a visual sense of what the end resource instances will look like in XML. Note that although the description of the resources is based on their XML representation, other representations such as JSON are equally valid.

1.3.1.1: XML

The XML syntax uses the following notation:

 <name xmlns="http://hl7.org/fhir" (attrA="value")> 
   <nameA><!-- 1..1 type description of content  --><nameA>
   <nameB[x]><!-- 0..1 type1|type1 description  --></nameB>
   <nameC> <!--  1..* -->
     <nameD ><!-- 1..1 type>Relevant records  --></nameD>
   </nameC>
 <name>

Notes:

• To build a valid XML instance of a resource, simply replace the contents of the elements and attributes with valid content as described by the cardinality, type rules and content description found in the comment in each element
• Note that the only properties that are represented as attributes are those defined in underlying specifications such as xml:lang and Atom (see below) (§1.3.8.1), which is used as the XML representation for bundles
• Any elements that have a primitive type (§1.4.1) will have a value attribute to contain the actual value of the element
• Elements are assigned a cardinality that specifies how many times the element may or must appear. If the cardinality is shown in Pink then there is an additional condition that impacts on the allowed cardinality. This is available as a mouse-over text, or in the formal definitions
• The elements are assigned one or more types. All of the types are defined in the data types except for "Resource" and "Narrative" that are documented below. The type names are hyperlinked
• When a logical element can have more than one type, it's name takes the form nnn[x]. The "nnn" part of the name is constant, and the [x] is replaced with the name of the type that is actually used. The types that are allowed are listed with a "|" used to separate them
• Each element name in the pseudo-syntax is also a hyperlink to the formal definition of the element in the data dictionary that underlies the exchange formats.
• If the element name is underlined, then applications are required to support (§1.2.5.2) and/or understand it
• The character set for a resource is always Unicode, encoded in UTF-8. Specifying the character encoding in the XML is optional but recommended.
• FHIR elements are always in the namespace http://hl7.org/fhir. This is usually specified as the default namespace on the root element. The only other namespaces that occur in FHIR resources are where some external content model is explicitly introduced into the resource content model. For example, XHTML is found in every resource - see below
• Any of the XML elements may have an id attribute to serve as the target of an internal reference. The id attribute is not shown in this format
• FHIR elements are never empty. If an element is present in the resource, it must have either a value attribute, child elements as defined for its type, an id attribute that is the link target of narrative (§1.3.2), or 1 or more extensions
• Attributes can never be empty. Either they are absent, or they are present with at least one character of non-whitespace content
• The xml:lang attribute may appear on the root element, where it specifies the base language of the resource. It may also appear on attachments (§1.4.3) and in the XHTML content, but nowhere else
• The formal MIME-type for FHIR resources represented in XML is application/fhir+xml
• In addition to this descriptive syntax, other definitional forms are available, including W3C schema and Schematron

When represented as XML, resources may be validated by schema and schemas are provided, but operational systems are not required to do so (though the XML must always be valid against this specification and the schema and Schematron). In addition to the simple XML description, W3C Schema, UML models, and other definitional models are provided that may be a useful aid for system implementation.

1.3.1.2: UML

The UML diagrams represent the same content as a series of classes that represent XML elements. Elements are labeled with an "R" for resource, or a "D" for a data type. Classes without a label are normal classes that are just part of the content of a resource or a data type.

Where an element can have a choice of data types, these are represented in the choice using the same syntax as the xml syntax. Due to way UML works, the actual order of the elements cannot be determined from the diagram, nor is it visible whether a proprerty is an element or an attribute.

These UML diagrams are intended to communicate the contents of the resource to a human. An alternate set of diagrams that is more suited to code generation is available as part of the eCore reference platform (§2.6.8.1).

1.3.2: Narrative

Every resource SHALL include a human readable narrative that contains a summary of the resource, and may be used to represent the content of the resource to a human. The narrative need not encode all the structured data, but is required to contain sufficient detail to make it "clinically safe" for a human to just read the narrative. Resource definitions may define what content should be represented in the narrative to ensure clinical safety.

The narrative for a resource is allowed to contain additional information that is not in the structured data, including human-edited content. Such additional information must be in the scope of the definition of the resource. In small, closed trading partner environments, there may be no need for a narrative text. In such cases, implementations are allowed to populate the narrative with text equivalent to "[ResourceName] - No human readable text provided for this resource" in an appropriate language. Implementers should note that small, closed trading partner environments are very likely to open up during the lifetime of the resources they define.

The narrative is an xhtml fragment that also includes images if appropriate:

<[name] xmlns="http://hl7.org/fhir">
 <status value="[code]"/><!-- 1..1 generated | extensions | additional -->
 <div xmlns="http://www.w3.org/1999/xhtml"< <!-- Limited xhtml content< --> </div>
 <blob>  <!-- 0..* Binary content referenced in xhtml -->
  <mimeType value="[code]"/><!-- 1..1 Mime type of binary attachment (http://www.rfc-editor.org/bcp/bcp13.txt.htm)  -->
  <content value="[base64Binary]"/><!-- 1..1 base64 data for attachment -->
 </blob>
</[name]>

1.3.2.1: Terminology Bindings

The contents of the div element are an XHTML fragment containing only the basic html formatting elements described in chapters 7-11 (except section 4 of chapter 9) and 15 of the HTML 4.0 standard, <a> elements (either name or href), images and internally contained style attributes. The XHTML content must not contain a head, a body element, external stylesheet references, scripts, forms, base/link/xlink, frames, iframes, and objects. The div element must have some non-whitespace content.

  <narrative>
    <div xmlns="http://www.w3.org/1999/xhtml">This is a simple 
          example with only plain text</div>
  </narrative>
   
   <narrative>
   <div xmlns="http://www.w3.org/1999/xhtml">
     <p>
       This is an <i>example</i> with some <b>xhtml</b> formatting.
     </p>
   </div>
  </narrative>

The inner portion of the div content is often used for the innerHTML property in a browser. In order to simplify processing, the narrative SHALL be encoded so that the character content between the first ">" and the last "<" characters is the content of the <div> element.

Note that the XHTML is contained in general XML, and so there is no support for HTML entities like &nbsp; or &copy; etc. Unicode characters should be used instead. Note that &#160; substitutes for &nbsp;.

The narrative content should be in the language of the resource (Known Broken Link - needs to be resolved), but there is no reason to expect that HTML type tooling would understand the resource language element. For this reason, a lang attribute on the <div> should also be used (and see the note in the HTML 5 specification about use of language (http://www.w3.org/html/wg/drafts/html/master/dom.html#the-lang-and-xml:lang-attributes) ).

The image source references may be a local reference within the resource:

  <img src="#a5"/>

This is an internal reference to an id attribute on an element in the same resource, either in the binary attachments on the text element directly, or an element of type "Attachment (§1.4.3)".

  <narrative>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>
        <img src="#a1"/>.
      </p>
    </div>
    <blob id="a1">
      <mimeType value="image/png" />
      <content value="MEKH....SD/Z" />
    </blob>
  </narrative>

Since the presence of images that are not part of the resource is not guaranteed, images that are an essential part of the narrative should always be embedded like this.

1.3.2.2: Styling the XHTML

The XHTML fragment in the narrative may be styled using CSS in the normal fashion, using a mix of classes, ids and in-line style elements. Specific CSS stylesheets will be applied to the XHTML when it is extracted from the resource to be displayed to a human to create the presentation desired in the context of use. Authors may fix the following styling aspects of the content:

• bold, italic, underline, strikethrough
• font color, family, and size
• background color, text alignment
• whitespace interpretation
• ordered list number format (since it may be referred to in text)

These style properties are specified in-line using the style attribute. If an equivalent html element exists, such as "i", or "pre", it may be used instead, but note that some of these elements are deprecated in HTML 4 and must not be used in Narrative XHTML (including "u", and "font").

Rendering systems are required to respect any of these rendering styles when they are specified in the XHTML, though appropriate interpretation is allowed (e.g. a low-contrast display for dark room contexts or a high-contrast display for the visually impaired may adjust colors accordingly).

Authors are allowed to specify additional styles and style properties as specified in the CSS specification, but these are extensions to this specification and renderers are not required to honor them. Note, however, the additional rules around styling that apply in the context of documents (§2.4.6.1).

Note: styles in resources can make use of the styles defined in the standard FHIR stylesheet, which lives here: http://hl7.org/implement/standards/fhir/fhir.css. Since this stylesheet is not referred to directly, rendering systems may take their own copy if they wish. Authoring systems should not depend on these styles being supported in order to render clinical content correctly without trading partner agreement.

1.3.3: Internal References

There are 4 cases where elements inside a resource reference each other:

• Inside a CodeableConcept data type to identify the primary encoding (§1.4.5)
• An <img src=""/> reference in the narrative, referring to an image found in the resource
• Between elements in the narrative and structured data elements
• Between a ResourceReference and an contained resource (§1.2.6.2)

These references are done using an id/idref based approach, where a source element indicates that it has the same content as the target element. The target element has an attribute "id" which must have a unique value within the resource with regard to any other id attributes. The "id" attribute is not in any namespace. The source element reference must refer to an attribute in the same resource (or, for a CodeableConcept, inside the same datatype).

  <example>
    <target id="a1">
      <child>...</child>
    </target>
    <-- other stuff -->
    <source idref="a1">
  </example>

In a single resource, this works like xml:id/idref, but there is an important difference: the uniqueness and resolution scope of these id references is within the resource that contains them. If multiple resources are combined into a single piece of XML, such as an atom feed (§1.3.8.1), duplicate values may occur between resources. This must be managed by applications reading the resources.

Note that all references between the xhtml elements and the data elements must be understood to establish a "derived from" relationship, where the derived content (whether text or data) refers to the source content. Note that this means some references may be forward references (references to elements defined later in the instance).

1.3.4: Representing Resources in JSON

Though the representation of FHIR resources is described in XML, FHIR also defines a JSON representation of the resources. The JSON format for the resources follows the standard XML format very closely to make interconversion easy, and so that XPath queries can easily be mapped to query the JSON structures. The formal mime type for this format is application/fhir+json.

Clients are free to choose whether to implement in XML or JSON. Servers must support XML, and can choose to support JSON. Note that systems must declare which format(s) they support. Also, the reference implementations (§2.6.8.1) include bi-direction conversion functionality between the two formats.

The JSON representation is described relative to the XML representation:

• The names for the JSON object members are the same as the names of the elements and attributes in XML, including for elements that may repeat
• In the data types, the primitive type (§1.4.1) integer is represented using a native JSON int, while boolean is represented using JSON's "true" and "false" values. Other primitive types such as string, decimal, etc. are represented as a JSON string, using the same serialization as the XML form (including instant, which is represented as plain text, not in one of the proposed JSON custom date formats)
• Just as in XML, JSON property attributes never have empty values; omit a value if it is empty

There are differences too:

• There are no namespaces in the JSON representation
• Order is not significant in the JSON representation
• JSON does not have a notion of attributes versus elements, so attributes (xml:id, value) are treated as JSON object members (see below for more details)
• JSON has a notation for arrays, which are used to represent repeating elements. Note that this is the case, even if they do not repeat in the actual instance
• The XHTML <div> element in the Narrative datatype is represented as a single escaped string of XHTML. This is to avoid problems in JSON with mixed content etc. The XHTML most still conform to the rules described above

These differences - particularly the repeating element one, which cannot be avoided - mean that generic XML --> JSON converters are not able to perform correctly. The reference platforms (§2.6.8.1) provide XML <--> JSON conversion functionality that accommodates these FHIR-specific characteristics.

1.3.5: JSON representation of primitive elements

FHIR elements with primitive values are represented as a JSON object of the same name with a the value attribute of the element in a "value" property. Except for integer and boolean, native JSON types are not used and values are rendered as strings, to guarantee equivalence of the serialized representation between XML and JSON.

 <date value="1972-11-30"/>
 <deceased value="false" />
 <count value="23" />

is represented in JSON as

 "date" : { value: "1972-11-30" }
 "deceased" : { value: false }
 "count" : { value: 23 }

All XML elements can have an 'id' attribute, which is represented in JSON as a property of name "_id":

 <dob id="314159" value="1972-11-30" />

is represented in JSON as:

 "dob": { 
   "_id": "314159", 
   "value": "1972-11-30" 
 }

1.3.6: Repeating elements

Repeating elements are rendered within a JSON array with the name of the element, so a repeating <dob> element in XML

 <dob value="2011-11-30" />
 <dob id="314159" value="1972-11-30" />

is represented in JSON like so:

"dob": [
	{ "value": "2011-11-30" },
	{ "_id": "314159", "value": "1972-11-30" }
  ]

1.3.7: JSON representation of Resources, Elements, and Data types

Resources, elements, and datatypes (types that contain named elements of other types) are represented using a JSON object, containing a member for each element in the datatype. Composites can have id attributes, which are converted to JSON members values, in the same manner as described for primitives. It comes before all other members. For example:

<Person>
  <name>
    <use value="official" />  
    <given value="Karen" />
    <family id="n1" value="Van" />
  </name>
  <text>
    <status value="generated" />
    <div xmlns="http://www.w3.org/1999/xhtml">...</div>
  </text>
</Person>

is represented in JSON as:

{
  "Person" : {
    "name" : [{
      "use" : { "value" : "official" },
      "given" : [{
         "value" : "Karen" 
        }],
      "family" : [{
         "_id" : "n1",
         "value" : "van"
        }]
     }],
    "text" : {
      "status" : { "value" : "generated" },
      "div" : "<div xmlns='http://www.w3.org/1999/xhtml'>...</div>"
    }
}

Things to note here are:

• Both given and family are repeating XML elements, so they are serialised as an Array whether or not they repeat in this instance
• Because the primitive element 'id' is in a resource, it is serialized as a JSON object
• In the family part of 'name', the '_id' is added as the first member
• The XHTML content in the 'div' element which is in the Narrative element 'text' is represented as an escaped string in the value property in JSON. The xhtml's root element needs to be a <div> in the xhtml namespace

1.3.8: Bundles

A bundle is a collection of resources in a single document (§1.2.3).

1.3.8.1: Atom Bundle Representation

In XML bundles are represented using an Atom format (http://tools.ietf.org/html/rfc4287), following this template:

<feed xmlns="http://www.w3.org/2005/Atom">
  <title><!-- 1..1 string Text statement of purpose --></title>
  <updated><!-- 1..1 instant When the bundle was built --></updated>
  <id><!-- 1..1 uri Unique uri for this bundle --></id>
  <os:totalResults xmlns:os="http://a9.com/-/spec/opensearch/1.1/"><!-- 0..1 integer 
              Paging: the total number of results --></os:totalResults>
  <link rel="self" href="[building application url (Service base on REST)]"><!-- 0..1 -->
  <link rel="first" href="[paging: url for first page of result]"><!-- 0..1 -->
  <link rel="previous" href="[paging: url for previous page of result]"><!-- 0..1 -->
  <link rel="next" href="[paging: url for next page of result]"><!-- 0..1 -->
  <link rel="last" href="[paging: url for last page of result]"><!-- 0..1 -->
  <author><!-- 0..1 Who created resource? -->
      <name><!-- 1..1 string Name of Human or Device that authored the resource --></name>
      <uri><!-- 0..1 uri Link to the resource for the author --></uri>
  </author>
  <entry><!-- Zero+ -->
    <title><!-- 1..1 string Text summary of resource --></title>
    <link rel="self" href="Version Specific reference to Resource"><!-- 0..1 --></link>
    <id><!-- 1..1 uri Logical Id (uri) for this resource --></id>
    <updated><!-- 1..1 instant Last Updated for resource --></updated>
    <published><!-- 0..1 instant Time resource copied into the feed --></published>
    <author><!-- 0..1 Who created resource? -->
      <name><!-- 1..1 string Name of Human or Device that authored the resource --></name>
      <uri><!-- 0..1 uri Link to the resource for the author --></uri>
    </author>      
    <!-- Tags affixed to the resource (0..*):   --> 
    <category term="[Tag Uri]" label="[Tag Label]" scheme="http://hl7.org/fhir/tag"> 
    <content type="text/xml"><!-- 1..1 -->
      <[ResourceName] xmlns="http://hl7.org/fhir">
        <!-- Content for the resource -->
      </[ResourceName]>
    </content>
    <summary type="xhtml"><!-- 0..1 -->
      <div xmlns="http://www.w3.org/1999/xhtml"><!-- Narrative from resource --></div>
    </summary>
  </entry>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <!-- 0..1 Enveloped Digital Signature (see Atom section 5.1) -->
  </Signature>
</feed>

Notes

• Logically, a bundle is a set of resources that are prepared to send somewhere for consumption - a "feed". There is no implication that the feed is a standing arrangement (though this is not precluded)
• The order of elements does not matter in an atom feed (but not entries: the order of the entries is important). The order of elements in the atom namespace as documented above does not need to be followed
• The title for the feed and the entry are arbitrary human readable content and not to be used for any automated processing. Applications may populate these in any useful way
• Every bundle must have a unique id and that id must be a valid absolute uri. UUIDs are recommended (urn:uuid:...)
• The entry element carries the three pieces of resource metadata (§1.2.2): Id (.id), Version Id (.link), Last Updated (.updated)
• Each entry also carries all the Tags affixed to the resource in the category element. The category element can be used in other ways too
• The entry.id must be an absolute url, the tail element of which is the logical id of the resource. The id is a version independent reference
• The entry.link to self is a version specific reference to the resource.
• When used in a RESTful implementation, the entry.link and entry.id are the URLs of the resource on the system; the version specific link can be used as the basis synchronizing pub/sub systems using the atom bundle with the updates operation (§2.1.15). In other contexts, the values should be literal references to a server if one is available
• Note that the atom specification requires an author for each entry, but if an author is provided in the base feed element, an author is not needed on each entry
• The author of a resource is not explicit in the FHIR resource model; instead it is delegated to the infrastructure. The name is the name of a human author or a device. The uri is a link to the author (possibly a Practitioner resource)
• xml:base elements SHOULD NOT be used and implementations do not need to support it
• The entire bundle can be signed with a single Enveloped Digital Signature as described in the Atom specification (section 5.1)
• The mime type for an bundle when represented in XML is application/atom+xml
• The feed.link element with relationship "self" is assigned no particular meaning the FHIR specification, except in the case of a search operation, but may be used to provide a reference to the source of the feed
• The feed.link elements with relationship "first", "last", "previous" and "next" are used to implement paging in the RESTful interface and allow a client to browse through a multi-page result. See search/query (§2.2)

Bundling versions - deletion

When returning a set of resources or versions of a resource, an entry might indicate that the entry has been deleted. Deleted resources are represented in an atom feed as defined by rfc6721.txt (http://www.rfc-editor.org/rfc/rfc6721.txt) :

<feed xmlns="http://www.w3.org/2005/Atom">
  ... feed elements and other entries ...
  <at:deleted-entry xmlns:at="http://purl.org/atompub/tombstones/1.0"
      ref="[Logical Id for deleted resource]" when="instant [when deleted]">
    <link rel="self" href="[Version Specific reference to Resource]"><!-- 0..1 --></link>
  </at:deleted-entry>
  ... other entries ...

A deleted resource returns a 410 error if it is accessed through the RESTful interface.

Resolving references to Resources

Readers of the resources bundles should always look through the resources in the atom feed when a resource reference is encountered. The resource reference may have the resource type and a relative url, which is the id of the target, like this:

  <institution>
    <type value="Organization" />
    <reference value="organization/@23" />
  </institution>

A reader trying to find the resource this institution element identifies should always look through the entries in the atom feed prior to looking anywhere else for the institution. If the feed.id for the resource that contains the link above is http://example.org/, then the absolute URL is http://example.org/organization/@23. If that organization is in the feed, it would look like this:

   .. feed ..
  <entry>
    .. 
    <id>http://example.org/organization/@23<id>
    .. 

    <content type="text/xml">
      <Organization xmlns="http://hl7.org/fhir">
         <!-- Content for the resource -->
      </Organization>
    </content>
  ... feed ...

It would also be possible to locate the resource by an absolute url. In this case, the id element contains a direct reference to the location of the resource:

  <institution>
    <type value="Organization" />
    <reference value="http://example.org/organization/@23" />
  </institution>

If there is no resource in the atom feed with an appropriate URL, then the application may try accessing the provided URL directly or use some other implementation-specific method for resolving how to find the resource.

1.3.9: Implementation Notes

• Atom Feeds may be signed following the rules described in the Atom specification. One consequence of signing the document is that URLs, Identifiers and internal references are frozen and cannot be changed. This might be a desired feature, but it may also cripple interoperability between closed eco-systems where re-identification (§2.6.6) frequently occurs. For this reason, it is recommended that only Document Bundles are signed and then only when all the related resources are found in the bundle.
• FHIR resources make use of id attributes as targets for internal references with resources. These id attributes are unique and resolved within the context of a single resource. When resources are combined into a bundle, different resources may contain duplicate id attributes. Thus it is important to limit the scope of resolution of an id attribute to the resource in which the id attribute is declared.

1.3.9.1: JSON Bundle Representation

In JSON bundles are represented using a JSON format that is tailored to the specific needs for bundles. Each element in the Xml feed definition has a JSON corresponding JSON object member with the same name. Here is an example feed returning search results for a person query:

{
  "feed" : {
    "title" : "Search result",
    "updated" : "2012-09-20T12:04:45.6787909+00:00",
    "id" : "urn:uuid:50ea3e5e-b6a7-4f55-956c-caef491bbc08",
    "link" : [{
      "rel" : "self",
	  "href" : "http://ip-0a7a5abe:16287/fhir/person?format=json"
    }],
    "category" : [{
      "term" : "[Tag Uri]",
      "label" : "[Tag Label]",
      "scheme" : "http://hl7.org/fhir/tag"
    }],
    "totalResults" : 12,
    "entry" : [{
      "title" : "Resource of type Person, with id = 1 and version = 1",
      "link" : [{
        "rel" : "self",
        "href" : "http://fhir.furore.com/fhir/person/@1/history/@1"
      }],
      "id" : "http://fhir.furore.com/fhir/person/@1",
      "updated" : "2012-05-29T23:45:32+00:00",
      "published" : "2012-09-20T12:04:47.3012429+00:00",
      "author" : [{
        "name" : "Grahame Grieve / HL7 publishing committee"
      }],
      "category" : [{
        "term" : "[Tag Uri]",
        "label" : "[Tag Label]",
        "scheme" : "http://hl7.org/fhir/tag"
      }],
      "content" : {
        "Person" : { ...person content in JSON... }
      },
      "summary" : "<div xmlns=\"http://www.w3.org/1999/xhtml\">(text summary)</div>",
    },
    ... other entries ....
    ]
  }
}

Note that property names for elements that can repeat are not pluralized for consistency of overall approach. The mime type for a json bundle is also application/fhir+json.

Bundling versions - deletion

When returning a set of versions for a resource, a version might indicate a deletion. While the XML format follows RFC 6721 (http://www.rfc-editor.org/rfc/rfc6721.txt) , the JSON format needs to use an entry item to retain the logical order of entries:

   .. feed ..
   "entry" : [
    ... other entries ....,    
    {
      "deleted" : "2012-05-29T23:45:32+00:00",
      "id" : "http://fhir.furore.com/fhir/person/@1",
      "link" : [{
          "rel" : "self",
          "href" : "http://fhir.furore.com/fhir/person/@1/history/@1"
        }],
    }, ... other entries ....
  ]
  ... feed ...

The entry is known to be deleted because a date of deletion is given. An id must be provided, and a link may be provided.

Binary Resources

There are situations where it is useful or required to handle pure binary content as resources. Typically, this is when the binary content is referred to from other FHIR Resources. The resource can contain any content, whether text, image, pdf, zip archive, etc. These resources are served in their native form on the rest interface (§2.1.17), but can also be represented in XML or JSON, such as when including these resources in a bundle (used when it is convenient to include these in the feed directly rather than leaving them by reference).

When binary resources is represented as XML, it is represented as base64 encoded content along with a content-type, which is the mime-type as it would be specified in HTTP:

 <Binary xmlns="http://hl7.org/fhir" contentType="[mime type]">
   [Base64 Content]
 </Binary>

In JSON, the representation would look like this:

  "Binary" : {
    "contentType" : "[mime type]",
    "content" : "[base64 of data]"
  }

Binary resources can also be embedded as contained resources (§1.2.6.2). If there's a desire to capture metadata about a binary object, an appropriate resource type must be used such as DocumentReference (§3.13) or Picture (§3.32).

1.3.10: XML Schema and Schematron

This specification provides schema definitions for all of the content models described here. The base schema is called "fhir-base.xsd" and defines all of the datatypes and also the base infrastructure types described on this page. In addition, there is a schema for each resource and a common schema fhir-all.xsd that includes all the resource schemas. A customized atom schema fhir-atom.xsd is provided for validating bundles (§1.3.8.1).

In addition to the w3c schema files, this specification also provides Schematron files that enforce the various constraints defined for the datatypes and resources. These are packaged as files for each resource as well as a combined fhir-atom.sch file that incorporates the rules for all resources.

XML that is exchanged must be valid against the w3c schema and Schematron, nor is being valid against the schema and Schematron sufficient to be a conformant instance. (This specification makes several rules that cannot be checked by either mechanism.) Exchanged content must not specify the schema or even the schema instance namespace in the resource itself.

1.4: Data Types

The FHIR specification defines a set of types that are used for the resource elements. There are two categories of data type: simple / primitive types, imported from XML schema, and complex types, which are re-usable clusters of elements

The data types are available as a W3C Schema.

1.4.1: Primitive Types

The following table summarizes the primitive types and their simple restrictions that are used in throughout this specification. These types are those defined in the W3C Schema (1.0) specification part 2 (http://www.w3.org/TR/xmlschema-2/) , with additional constraints marked in bold.

These types are represented as XML Elements with the value of the type in the text of the element. The name of the element is defined where the type is used. The XML elements may have an id attribute. In JSON, the data type is represented by an object with two properties: "_id" for the id attribute, and "value" for the value of the type.

  <date value="1951-06-04" />

  <date id="a1" value="1951-06-04" />

  date : {
    value : "1951-06-04"
  }

  date : {
    _id : "a1",
    value : "1951-06-04"
  }

1.4.2: Complex Types

These types are represented as XML Elements with child elements with the name of the defined elements of the type. The name of the element is defined where the type is used. Any of the XML elements may have an id attribute. In JSON, the data type is represented by an object with properties named the same as the the XML elements. The JSON representation is almost exactly the same, so only the first example has an additional JSON representation.

Complex data types may be "profiled". A profile (§3.36) makes a set of rules about which elements must have values, and what the possible values are.

1.4.3: Attachment

This type is for containing or referencing attachments - additional data content defined in other formats. The most common use of this type is to include images or reports in some report format such as PDF. However it can be used for any data that has a mime type.

<[name] xmlns="http://hl7.org/fhir">
 <contentType value="[code]"/><!-- 1..1 Mime type of the content, with charset etc. (http://www.rfc-editor.org/bcp/bcp13.txt.htm)  -->
 <language value="[code]"/><!-- 0..1 Human language of the content (BCP-47) (http://tools.ietf.org/html/bcp47.htm)  -->
 <data value="[base64Binary]"/><!-- 0..1 Data inline, base64ed -->
 <url value="[uri]"/><!-- 0..1 Uri where the data can be found -->
 <size value="[integer]"/><!-- 0..1 Number of bytes of content (if url provided) -->
 <hash value="[base64Binary]"/><!-- 0..1 Hash of the data (sha-1, base64ed ) -->
 <title value="[string]"/><!-- 0..1 Label to display in place of the data -->
</[name]>

1.4.3.1: Terminology Bindings

The contentType element must always be populated. It can include charset information and other mime type extensions as appropriate. If there is no character set in the contentType then the correct course of action is undefined, though some media types may define a default character set and/or the correct character set may be able to be determined by inspection of the content.

The actual content of the Attachment can be conveyed directly using the data element or a url reference can be provided. If both are provided, the reference must point to the same content as found in the data. The reference can never be reused to point to some different data (i.e. the reference is version specific). The url reference must point to a location that resolves to actual data; some uris such as cid: meet this requirement.

The hash is included so that applications can verify that the contents that a url have not changed.

In many cases where Attachment is used, the cardinality is >1;. A valid use of repeats is to convey the same content in different mime types and languages. Guidance on the meaning of repeating elements MUST be provided in the definition of the repeating resource element or extension that references this type. The language element describes the language of the attachment using the codes defined in BCP 47 (http://tools.ietf.org/html/bcp47) .

  <document>
    <contentType value="application/pdf" />
    <language value="en" />
    <data value="/9j/4...KAP//Z" /> <!-- covers many lines -->
    <title value="Definition of Procedure" />
  </document>

  document : {
    contentType :  { value : "application/pdf" },
    languge : { value : "en" },
    data :  { value : "/9j/4...KAP//Z"},
    title :  { value : "Definition of Procedure" }
  }

  <image>
    <contentType value="application/dicom" />
    <reference value="http://10.1.2.3:1000/wado?requestType=WADO&amp;wado_details..." />
    <hash value="EQH/..AgME" />
  </image>

1.4.4: Coding

A "coding" is a representation of a defined concept using a symbol from a defined "code system" - which may be an enumeration, a list of codes, a full terminology such as SNOMED-CT or LOINC or a formal ontology.

<[name] xmlns="http://hl7.org/fhir">
 <system value="[uri]"/><!-- 0..1 Identity of the terminology system -->
 <code value="[code]"/><!-- 0..1 Symbol in syntax defined by the system -->
 <display value="[string]"/><!-- 0..1 Representation defined by the system -->
</[name]>

The system is a URI that references the enumeration, terminology or ontology that defines the code. The URI may be an OID (urn:oid:) or a UUID (urn:uuid:), a specially defined URI from the named systems list (Known Broken Link - needs to be resolved), a url that references a definition of the system or any other URI that uniquely identifies the definitions. OIDs and UUIDs may be registered in the HL7 OID registry (http://hl7.org/oid) and should be if the content is shared or exchanged across institutional boundaries.

If present, the code must be a syntactically correct symbol as defined by the system. In some code systems such as SNOMED-CT, the code may be an expression composed of other codes. Note that codes are case sensitive unless specified otherwise by the code system. The display is a text representation of the code defined by the system and can be used to display the meaning of the code by an application that is not aware of the system.

In some cases, the system may not be known - only the code is known. In this case, no useful processing of the code may be performed unless the system can be safely inferred by the context. This practice should be avoided where possible in order to future-proof implementations, as information sharing in a wider context is very likely to arise eventually, and codes cannot be used in the absence of a known system.

If the system is present, and there is no code, then this is understood to mean that there is no suitable code in the system in which to represent the code.

If two Codings have the same the system and code then they have the same meaning. Note that if a code system redefines the meaning of codes across different releases, then the different releases must have different values for system. If either the system or the code differs, then how they are related can only be determined by consulting the definitions of the system(s) and any mappings available.

The correct value to use in the system for a given code-system can be determined by:

• the Named Systems List (Known Broken Link - needs to be resolved) section
• the HL7 OID Registry (http://www.hl7.org/oid/index.cfm?ref=common)
• the documentation associated with the code system
• consulting the owner of the code system
• asking on the HL7 vocabulary mailing list

  <code>
    <system value="http://hl7.org/fhir/sid/icd-10" />
    <code value="G44.1" />
  </code>

  <problem>
    <system value="http://snomed.info" />
    <code value="128045006:{363698007=56459004}" />
  </problem>

1.4.4.1: Choosing Coding vs. CodeableConcept

A Coding is a simple direct reference to a code in a code system. In practice, such a simple reference is very difficult to use - if a system is using text when the correct codes can't be found, or if two different systems are using different terminologies or a different mix of codes and text, the Coding type doesn't provide enough information to make this work. Since such situations are quite a common case, the type CodeableConcept is defined, which allows for multiple Coding elements and/or a text representation. The CodeableConcept is used in resources in preference to the simpler Coding except for a few special cases. Coding is defined separately mainly for use in profiles, where the context of an explicit use case means that the profile can define a better structure than the general case CodeableConcept.

1.4.5: CodeableConcept

A CodeableConcept represents a represents a field that is usually defined by formal reference to one or more terminologies or ontologies, but may also be defined by the provision of text. This is a common pattern in healthcare data.

<[name] xmlns="http://hl7.org/fhir">
 <coding><!-- 0..* Coding Code defined by a terminology system --></coding>
 <text value="[string]"/><!-- 0..1 Plain text representation of the concept -->
 <primary value="[idref]"/><!-- 0..1 Which code was chosen directly by the user -->
</[name]>

Each "coding" is a representation of the concept using a symbol from a defined "code system" - which may be an enumeration, a list of codes, a full terminology such as SNOMED-CT or LOINC, or a formal ontology. The concept may be coded multiple times in different code systems (or even multiple times in the same code systems, where multiple forms are possible, such as with SNOMED-CT). The different codings may have slightly different granularity due to the differences in the definitions of the underlying codes. The ordering of Codings within a CodeableConcept is undefined.

Whether or not coding elements are present, the text representation of the concept as entered or chosen by the user which most closely represents the intended meaning of the user or concept. Very often the text is the same as a display of one of the codings. One of the codings may be flagged as the primary - the code that the user actually chose directly. If present, the value of the primary element is an xml:id (§1.3.3) that must match an id attribute on one of the codings.

  <concept>
    <coding>
      <system value="http://hl7.org/fhir/sid/icd-10" />
      <code value="R51" />
    </coding>
    <coding id="a1">
      <system value="http://snomed.info" />
      <code value="25064002" />
      <display value="Headache" />
    </coding>
    <text value="general headache" />
    <primary value="a1" />
  </concept>

  <unit>
    <coding>
      <system value="urn:oid:2.16.840.1.113883.19.5.2" />
      <code value="tab" />
      <display value="Tablet" />
    </coding>
    <coding>
      <system value="http://unitsofmeasure.org" />
    </coding>
  </unit>

  <diagnosis>
    <coding>
      <system value="http://snomed.info" />
      <code value="128045006:{363698007=56459004}" />
    </coding>
    <text value="Cellulitis of the foot" />
  </diagnosis>

1.4.6: Choice

A code taken from a short list of codes that are not defined in a formal code system. Choice is generally used for things like pain scales, questionnaires or formally defined assessment indexes. The possible codes may be ordered with some arbitrarily defined scale. Note: Choice is not an appropriate data type to use when the possible codes are defined as a value set from a formal code system or otherwise stored on a terminology server.

<[name] xmlns="http://hl7.org/fhir">
 <code value="[code]"/><!-- 0..1 Selected code -->
 <option>  <!-- 1..* List of possible code values -->
  <code value="[code]"/><!-- 1..1 Possible code -->
  <display value="[string]"/><!-- 0..1 Display for the code -->
 </option>
 <isOrdered value="[boolean]"/><!-- 0..1 If order of the values has meaning -->
</[name]>

The code is the selected value. A list of possible options for code must be provided; at least a code must be provided for each value. The selected code must be found in the list of possible codes.

If isOrdered is true, then the values have an inherent meaningful order and the list of values must be provided in the correct orderr in the instance.

  <value>
    <code value="+" />
    <option>
      <code value="neg" />
    </option>
    <option>
      <code value="trace" />
    </option>
    <option>
      <code value="+" />
    </option>
    <option>
      <code value="++" />
    </option>
    <option>
      <code value="+++" />
    </option>
    <isOrdered value="true" />
  </value>

1.4.7: Quantity

A measured amount (or an amount that can potentially be measured).

<[name] xmlns="http://hl7.org/fhir">
 <value value="[decimal]"/><!-- 0..1 Numerical value (with implicit precision) -->
 <comparator value="[code]"/><!-- 0..1 Relationship of stated value to actual value -->
 <units value="[string]"/><!-- 0..1 Unit representation -->
 <system value="[uri]"/><!-- 0..1 System that defines coded unit form -->
 <code value="[code]"/><!-- 0..1 Coded form of the unit -->
</[name]>

1.4.7.1: Terminology Bindings

The value contains the numerical value of the quantity, including an implicit precision. If no comparator is specified, the value is a point value (i.e. '='). The comparator element can never be ignored.

The units element contains a displayable unit that defines what is measured. The units may additionally be coded in some formal way using the code and the system (see Coding (§1.4.4) for further information about how to use the system element).

If the units are able to be coded in UCUM and a code is provided, it SHOULD be a UCUM code. If a UCUM unit is provided in the code then a canonical value can be generated for purposes of comparison between quantities. Note that the units element will often contain text that is actually a valid UCUM unit, but it cannot be assumed that it does.

1.4.7.2: Defined Variations on Quantity

These are used as types in resource content models, but they are really just a Quantity with some rules:

  <time>
    <value value="25" />
    <units value="sec" />
    <system value="http://unitsofmeasure.org" />
    <code value="s" />
  </time>

  <result>
    <value value="40000" />
    <comparator value="&gt;" />
    <units value="mcg/L" />
    <system value="http://unitsofmeasure.org" />
    <code value="ug" />
  </result>

  <dose>
    <value value="3" />
    <units value="capsules" />
    <system value="http://snomed.info" />
    <code value="385049006" />
  </dose>

  <cost>
    <value value="25.45" />
    <units value="US$" />
    <system value="urn:std:iso:4217" />
    <code value="USD" />
  </cost>

1.4.8: Range

A set of ordered Quantity values defined by a low and high limit.

A Range specifies a set of possible values; usually, one value from the range applies (e.g. "give the patient between 2 and 4 tablets"). Ranges are typically used in instructions.

<[name] xmlns="http://hl7.org/fhir">
 <low><!-- 0..1 Quantity Low limit --></low>
 <high><!-- 0..1 Quantity High limit --></high>
</[name]>

The units and code/system elements of the low or high elements must match. If the low or high elements are missing, the meaning is that the low or high boundaries are not known and therefore neither is the range.

The range flag on the low or high elements cannot be present. Note that the Range type should not be used to represent out of range measurements: A quantity type with the comparator element should be used instead.

The low and the high values are inclusive, and are assumed to have arbitrarily high precision. E.g. the range 1.5 to 2.5 includes 1.50, and 2.50 but not 1.49 or 2.51.

  <estimate>
   <low>
     <value value="1.6" />
     <units value="m" />
   </low>
   <high>
     <value value="1.9" />
     <units value="m" />
   </high>
  </estimate>

1.4.9: Ratio

A ratio of two Quantity values - a numerator and a denominator.

<[name] xmlns="http://hl7.org/fhir">
 <numerator><!-- 0..1 Quantity The numerator --></numerator>
 <denominator><!-- 0..1 Quantity The denominator --></denominator>
</[name]>

Common factors in the numerator and denominator are not automatically cancelled out. The Ratio data type is used for titers (e.g., "1:128") and other quantities produced by laboratories that truly represent ratios. Ratios are not simply "structured numerics" - for example blood pressure measurements (e.g. "120/60") are not ratios. In addition, ratios are used where common factors in the numerator and denominator do not cancel out. The most common example of this is where the ratio represents a unit cost, and the numerator is a currency (e.g. 50/$10).

  <result>
   <numerator>
     <value value="1" />
   </numerator>
   <denominator>
     <value value="128" />
   </denominator>
  </result>

  <charge>
   <numerator>
     <value value="103.50" />
     <units value="US$" />
     <code value="USD" />
     <system value="urn:std:iso:4217" />
   </numerator>
   <denominator>
     <value value="1" />
     <units value="day" />
     <code value="day" />
     <system value="http://unitsofmeasure.org" />
   </denominator>
  </charge>

1.4.10: Period

A time period defined by a start and end time.

A period specifies a range of times. The context of use will specify whether the entire range applies (e.g. "the patient was an inpatient of the hospital for this time range") or one value from the period applies (e.g. "give to the patient between 2 and 4 pm").

<[name] xmlns="http://hl7.org/fhir">
 <start value="[dateTime]"/><!-- 0..1 The start of the period -->
 <end value="[dateTime]"/><!-- 0..1 The end of the period, if not ongoing -->
</[name]>

If the start element is missing, the start of the period is not known. If the end element is missing, it means that the period is ongoing.

The end value includes any matching date/time. For example, the period 2011-05-23 to 2011-05-27 includes all the times of 23rd May through to the end of the 27th May.

  <coverage>
   <start value="2011-05-23" />
   <end value="2011-05-27" />
  </coverage>

1.4.11: Array

A series of measurements taken by a device, with upper and lower limits. There may be more than one dimension in the data.

An Array provides a concise way to handle the data produced by devices that sample a physical particular state at a high frequency. A typical use for this is for the output of an ECG device.

<[name] xmlns="http://hl7.org/fhir">
 <origin><!-- 0..1 Quantity Zero value and units --></origin>
 <period value="[decimal]"/><!-- 0..1 Number of milliseconds between samples -->
 <factor value="[decimal]"/><!-- 0..1 Multiply data by this before adding to origin -->
 <lowerLimit value="[decimal]"/><!-- 0..1 Lower limit of detection -->
 <upperLimit value="[decimal]"/><!-- 0..1 Upper limit of detection -->
 <dimensions value="[integer]"/><!-- 0..1 Number of sample points at each time point -->
 <data value="[string]"/><!-- 0..1 Decimal values with spaces, or "E" | "U" | "L" -->
</[name]>

The digits are a set of decimal values separated by a single space (Unicode character u20). In addition to decimal values, the special values "E" (error), "L" (below detection limit) and "U" (above detection limit) can also be used. If there is more than one dimension, the different dimensions are interlaced - all the data points for a particular time are represented together.

None of the elements in an Array are mandatory because the Array is frequently used with devices where one usage carries just the data element, and a matching usage specifies the values of the other elements (see Device Log (§3.9) and Device Capabilities (§3.8)). At least one element must always be populated. The data is not interpretable without at least origin, period, and dimensions. When carried in an Observation (§3.26), these 3 elements and data must be populated for the Array to be properly populated. The default value for factor is 1.

 <array>
  <origin>
   <value value="0"/>
   <units value="μV"/>
   <system value="http://unitsofmeasure.org"/>
   <code value="uV"/>   
  </origin>
  <period value="2"/>
  <scale value="2.5"/>
  <dimensions value="1"/>
  <data value="-4 -13 -18 -18 -18 -17 -16 -16 -16 -16 -16 -17 -18 -18 -18 ...."/>
 </array>

1.4.12: Identifier

An identifier intended for use external to the FHIR protocol. As an external identifier, they may be changed or retired due to human or system process and errors.

<[name] xmlns="http://hl7.org/fhir">
 <use value="[code]"/><!-- 0..1 The use of this identifier -->
 <label value="[string]"/><!-- 0..1 Description of identifier -->
 <system value="[uri]"/><!-- 0..1 The namespace for the identifier -->
 <key value="[string]"/><!-- 0..1 The value that is unique -->
 <period><!-- 0..1 Period Time period when id was valid for use --></period>
 <assigner><!-- 0..1 Resource(Organization) Organisation that issued id (may be just text) --></assigner>
</[name]>

1.4.12.1: Terminology Bindings

The system referred to by means of a URI defines how the identifier is defined (i.e. how the key value is made unique). It might be a specific application or a recognized standard/specification for a set or identifiers or a way of making identifiers unique. The key must be unique within the defined system and have a consistent meaning wherever it appears. Both system and key values are always case sensitive.

FHIR defines some useful URIs directly (Known Broken Link - needs to be resolved). OIDs (urn:oid:) and UUIDs (urn:uuid:) may be registered in the HL7 OID registry (http://hl7.org/oid) and should be if the content is shared or exchanged across institutional boundaries. If the identifier itself is naturally globally unique (i.e. an OID, a UUID, or a URI with no trailing local part), then the system must be "urn:ietf:rfc:3986", and the URI would be in the key.

In some cases, the system may not be known - only the key is known (e.g. a simple device that scans a barcode), or the system is known implicitly (simple exchange in a limited context, often driven by barcode readers). In this case, no useful matching may be performed using the key unless the system can be safely inferred by the context. This practice should be avoided where possible in order to future-proof implementations, as information sharing in a wider context is very likely to arise eventually.

The assigner is used to indicate what registry/state/facility/etc assigned the identifier.

  <identifier>
    <use value="official" />
    <system value="urn:oid:2.16.840.1.113883.16.4.3.2.5" />
    <key value="123" />
  </identifier>

  <identifier>
    <use value="official" />
    <system value="http://www.acmehosp.com/patients" />
    <key value="44552" />
    <period>
      <start value="2003-05-03" />
    </period>
  </identifier>

  <identifier>
   <system value="urn:ietf:rfc:3986" />
   <key value="http://pas-server/xxx/patient/@443556" />
  </identifier>

  <identifier>
    <use value="temp" />
    <system value="urn:ietf:rfc:3986" />
    <key value="urn:uuid:a76d9bbf-f293-4fb7-ad4c-2851cac77162" />
  </identifier>

  <identifier>
    <use value="usual" />
    <label value="SSN" />
    <system value="http://hl7.org/fhir/sid/us-ssn" />
    <key value="000111111" />
  </identifier>

  <identifier>
    <use value="usual" />
    <label value="MRN" />
    <system value="urn:oid:0.1.2.3.4.5.6.7" />
    <key value="2356" />
    <period>
      <start value="2009-07-05" />
    </period>
  </identifier>

1.4.13: HumanName

A name of a human with text, parts and usage information.

Names may be changed or repudiated. People may have different names in different contexts. Names may be divided into parts of different type that have variable significance depending on context, though the division into parts does not always matter. With personal names, the different parts may or may not be imbued with some implicit meaning; various cultures associate different importance with the name parts and the degree to which systems must care about name parts around the world varies widely.

<[name] xmlns="http://hl7.org/fhir">
 <use value="[code]"/><!-- 0..1 The use of this name -->
 <text value="[string]"/><!-- 0..1 Text representation of the full name -->
 <family value="[string]"/><!-- 0..* Family name (often called 'Surname') -->
 <given value="[string]"/><!-- 0..* Given names (not always 'first'). Includes middle names -->
 <prefix value="[string]"/><!-- 0..* Parts that come before the name -->
 <suffix value="[string]"/><!-- 0..* Parts that come after the name -->
 <period><!-- 0..1 Period Time period when name was/is in use --></period>
</[name]>

1.4.13.1: Terminology Bindings

The text element specifies the entire name as it should be represented. This may be provided instead of or as well as specific parts. Applications updating a name must ensure either that the text and the parts are in agreement, or that only one of the two is present.

Note that the order of the parts within a given part type has significance and must be observed. The appropriate order between family name and given names depends on culture and context of use.

  <name>
    <use value="usual" />
    <family value="Chalmers" />
    <given value="Peter" />
    <given value="James" />
  </name>

1.4.14: Address

A postal address. There are a variety of postal address formats defined around the world. Postal addresses are often also used to record a location that can be visited to find a patient or person.

<[name] xmlns="http://hl7.org/fhir">
 <use value="[code]"/><!-- 0..1 The use of this address -->
 <text value="[string]"/><!-- 0..1 Text representation of the address -->
 <line value="[string]"/><!-- 0..* Line of an address -->
 <city value="[string]"/><!-- 0..1 Name of city, town etc. -->
 <state value="[string]"/><!-- 0..1 Sub-unit of country (abreviations ok) -->
 <zip value="[string]"/><!-- 0..1 Post code for area -->
 <country value="[string]"/><!-- 0..1 Country (can be ISO 3166 3 letter code) -->
 <period><!-- 0..1 Period Time period when address was/is in use --></period>
</[name]>

1.4.14.1: Terminology Bindings

The text element specifies the entire address as it should be represented. This may be provided instead of or as well as the specific parts. Applications updating an address must ensure either that the text and the parts are in agreement, or that only one of the two is present.

  <address>
   <use value="work" />
   <text value="1050 W Wishard Blvd
RG 
         5th floor
Indianapolis, IN 46240" />
   <line value="1050 W Wishard Blvd" />
   <line value="RG 5th floor" />
   <city value="Indianapolis" />
   <state value="IN" />
   <zip value="46240" />
  </address>

1.4.15: Contact

All kinds of technology-mediated contact details for a person or organisation, including telephone, email, etc.

<[name] xmlns="http://hl7.org/fhir">
 <system value="[code]"/><!-- 0..1 What kind of contact this is -->
 <value value="[string]"/><!-- 0..1 The actual contact details -->
 <use value="[code]"/><!-- 0..1 How to use this address -->
 <period><!-- 0..1 Period Time period when the contact was/is in use --></period>
</[name]>

1.4.15.1: Terminology Bindings

If capturing a phone, fax or similar contact, the value should be a properly formatted telephone number according to ITU-T E.123 (http://www.itu.int/rec/T-REC-E.123-200102-I/e) . However, this is frequently not possible due to legacy data and/or recording methods.

  <telecom>
   <system value="phone" />
   <value value="+15556755745" />
   <use value="home" />
  </telecom>

1.4.16: Schedule

A schedule that specifies an event that may occur multiple times. Schedules are not used for recording when things did happen, but when they are expected or requested to occur. A schedule can be either a list of events - periods on which the event occurs, or a single event with repeating criteria, or just repeating criteria with no actual event.

Note: a possible enhancement to this is to have the repeat content repeat with each event. This is richer and more complex - is the added functionality useful?

<[name] xmlns="http://hl7.org/fhir">
 <event><!-- 0..* Period When the event occurs --></event>
 <repeat>  <!-- 0..1 Only if there is none or one event -->
  <frequency value="[integer]"/><!-- 0..1 Event occurs frequency times per duration -->
  <when value="[code]"/><!-- 0..1 Event occurs duration from common life event -->
  <duration value="[decimal]"/><!-- 1..1 Repeating or event-related duration -->
  <units value="[code]"/><!-- 1..1 The units of time for the duration -->
  <count value="[integer]"/><!-- 0..1 Number of times to repeat -->
  <end value="[dateTime]"/><!-- 0..1 When to stop repeats -->
 </repeat>
</[name]>

1.4.16.1: Terminology Bindings

If events are specified, at least a low must be specified for each event. If no high is specified, the event is assumed to last a limited but unknown time as clinically relevant.

If the schedule has repeating criteria, the repeat can occur a given number of times per the specified duration or in relation to some real world event. Also, if the event repeats, a time to end the schedule can be specified, either by specifying a count number of times it can occur or a date at which to end the schedule. If no end condition is specified, the Schedule will terminate on some criteria that are expressed elsewhere.

  <schedule>
    <event>
      <start value="2012-01-07T09:00" />
      <end value="2012-01-07T13:00" />
    </event>
    <event>
      <start value="2012-01-14T09:00" />
      <end value="2012-01-14T13:00" />
    </event>
    <event>
      <start value="2012-01-22T11:00" />
      <end value="2012-01-22T15:00" />
    </event>
  </schedule>

  <schedule>
   <repeat>
     <frequency value="2" />
     <duration value="1" />
     <units value="d" />
   </repeat>
  </schedule>

  <schedule>
    <event>
      <start value="2011-12-23" />
    </event>
    <repeat>
      <when value="ACM" />
      <duration value="30" />
      <units value="min" />
      <end value="2012-01-02" />
    </repeat>
  </schedule>

1.4.17: Other Types

The following types are defined as part of the data types, but are documented elsewhere in the specification:

• Resource (§1.2.2) - The conceptual base class for all resources
• ResourceReference - for references from one resource to another
• Extension - used to convey additional data in a resource
• Narrative - Conveys a human readable representation of the content of a resource

1.5: Terminologies: Using Codes

Many elements in the FHIR resources are assigned a type of code, Coding (§1.4.4) or CodeableConcept (§1.4.5). These elements contain codes that are associated with defined meanings defined by frameworks of varying sophistication and size. In some simple cases, the set of codes is a enumeration, a short list defined specifically for the element. In other cases, the list of codes is taken from a large and complex terminology or ontology such as SNOMED-CT or OBO.

All these elements of type code, Coding (§1.4.4) or CodeableConcept (§1.4.5) are given a "binding name" that defines the set of possible codes that can be used in the element in question.

1.5.1: code

For simple elements with type code, the element is either bound to a code list - a list of defined codes, or the binding references some external standard that defines the set of valid codes that can be used (typical examples of references are Mime Types (http://www.rfc-editor.org/bcp/bcp13.txt) , Language Codes (http://tools.ietf.org/html/bcp47) , UCUM (http://unitsofmeasure.org) , etc).

The value of a element of type code SHALL be one of the codes defined by the code list or reference.

No other codes can be used in an instance. If the binding is a code list, the list of codes may be extended in subsequent releases of the specification. Profiles may state rules on which codes may be used in particular contexts, but cannot define new or additional codes for these elements.

1.5.2: CodeableConcept / Coding

For elements with type CodeableConcept (§1.4.5) or Coding (§1.4.4), the binding refers to a Value Set (§3.42) that defines a list of concepts along with the code/system pairs that refer to them. The binding to the value set may be labelled as just an example.

If the binding is not an example binding, then the code/system pair in the instance SHOULD refer to one of the concepts that is a member of the value set.

Bindings to value sets provided as part of the specification are always specific to the version of the value set published with the specification. The value set may be sealed by defining a simple list of enumerated codes, or it may include codes by their properties, in which case the list of valid concepts may grow or change over time.

Profiles can redefine the binding and are able to be much more precise about exactly which codes can be used for these elements (see Binding Control (Known Broken Link - needs to be resolved) for more detail).

1.5.3: Reference Tables

The following reference tables are provided to help implementers:

• Systems List (Known Broken Link - needs to be resolved): Some known system identifiers suitable for use in the system element of CodeableConcept, Coding, and Identifier elements
• Bindings List (§5.1.1): a full list of the binding names defined for all FHIR resources
• Code Lists (§5.2.1): Code lists defined as part of this specification
• Value Sets (Known Broken Link - needs to be resolved): Value sets defined as part of this specification
• v2 Tables list (Known Broken Link - needs to be resolved): A list of v2 tables that can be used in resources
• v3 code systems list (Known Broken Link - needs to be resolved): A list of v3 code systems that can be used in resources

1.6: Extensibility

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

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

Note that, unlike in many other specifications, there can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core simplicity for everyone.

In order to make the use of extensions safe and manageable, there is a strict governance applied to the definition and use of extensions. Though any implementer is allowed to define an extension, there is a set of requirements that must be met as part of the definition of the extension.

1.6.1: Extensibility Element

Every element in a resource includes an optional "extension" element that may be present any number of times in the element. The extension element appears as the first child, prior to any other defined child elements. This is the content model of the extension as it appears in each resource:

<[name] xmlns="http://hl7.org/fhir">
 <url value="[uri]"/><!-- 1..1 identifies the meaning of the extension -->
 <isModifier value="[boolean]"/><!-- 0..1 If extension modifies other elements/extensions -->
 <value[x]><!-- 0..1 Value of extension --></value[x]>
 <extension><!-- 0..* Extension Nested values for extension --></extension>
</[name]>

Notes:

• The url is a mandatory field, and identifies an extension definition in a resource profile (§3.36) that defines the content and meaning of the extension.
• isModifier is used to indicate that this value influences the interpretation, meaning or understanding of other elements. It's use is further discussed below
• The actual content of the extension consists of either a single value in the value[x] element, or a nested list of other extensions, each with their own defining url and content
• An extension must have either a value (i.e. a value[x] element) or child extensions. The value element must have content, and/or an id attribute that is the target of a reference from the Narrative
• When an extension is the target of an internal reference, the reference is always to the value of the extension. An extension is only allowed to tbe target of an reference when it has no value[x]

The value[x] element has the [x] replaced with the name of one of the defined types, and the contents as defined for that type, or another extension. The value type may be one of the following:

• integer
• decimal
• dateTime
• date
• instant
• string
• uri
• boolean
• code - if the extension definition provides a binding to a suitable set of codes
• base64Binary
• Coding (§1.4.4)
• CodeableConcept (§1.4.5)
• Attachment (§1.4.3)
• Identifier (§1.4.12)
• Quantity (§1.4.7)
• Choice (§1.4.6)
• Range (§1.4.8)
• Period (§1.4.10)
• Ratio (§1.4.9)
• HumanName (§1.4.13)
• Address (§1.4.14)
• Contact (§1.4.15)
• Schedule (§1.4.16)
• Resource - a reference to another resource

Nested extensions are used where the original definition of the extension defines complex content (i.e. multiple parts of the extension, not a simple data type). If the value of the extension themselves need extending, this is in the content of the value[x] element.

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

<Patient>
  <extension>
    <url value="http://acme.org/fhir/profiles/@main#trial-status" />
    <extension>
      <url value="http://acme.org/fhir/profiles/@main#trial-status-code" />	  
      <valueCode value="unsure" />	  
    </extension>
    <extension>
      <url value="http://acme.org/fhir/profiles/@main#trial-status-date" />	  
      <valueDate value="2009-03-14" />	  
    </extension>
    <extension>
      <url value="http://acme.org/fhir/profiles/@main#trial-status-who" />	  
      <valueResourceReference>	  
        <type value="Practitioner" />	  
        <reference value="../Practitioner/@example" />	  	    
      </valueResourceReference>	  
    </extension>
  </extension>
  <!-- other data for patient -->
</Patient>

1.6.2: isModifier

As well as providing additional information, extensions may be used to modify the meaning of other existing elements or even to negate their meanings. As an example, an implementation may wish to add a "certainty" extension to the AllergyIntolerance to indicate that some allergies are only suspected. If the extension had a value of "highly doubtful", then it would change the understanding of the allergy/intolerance, and implementations should not ignore this. Modifying the meaning of other elements makes these particular extensions unsafe to ignore, and so this must be explicitly labelled in the instance.

If the application processing the content of a resource does not recognize an extension that is labeled "IsModifier", and the data from element it extends is processed by the application, the application SHALL either refuse to process the data, or carry a warning concerning the data along with any action or output that results from processing the data.

<name>
  <extension>
    <url value="http://hl7.org/fhir/profile/@iso-21090#name-use" />
    <isModifier value="true" />
    <valueCode value="DN" />
  </extension>
  <text value="Arinyoo"/>
</name>

Servers and background processes that move resources around are not "processing the data of the resource", and these applications are not required to check for unknown extensions. Any process that copies data out of a resource for use in another context (display to a human, decision support, exchange in another format that doesn't support extensions) is processing the data.

Note that it must always be safe to show the narrative to humans; any extension that is labeled as "IsModifier" must be represented in the narrative. Applications are required to ignore extensions that they do not recognize if their "isModifier" element is missing or set to false.

1.6.3: Defining Extensions

Extensions may be defined by any project or jurisdiction, up to and including international standards organizations such as HL7 itself, and are published as part of a Resource Profile (§3.36). Extensions are always defined against some particular context - the type of element that they may be used to extend. The following are possible contexts for an extension:

In addition, an extension definition might apply additional constraints with regards to particular element values of the target that make its use appropriate. Extensions SHALL only be used on a target for which they are defined.

Each extension is defined using the following fields:

Notes:

• Mappings are not required to be computable (i.e. executable logic). Mappings to other specifications can also be provided.

Whenever resources containing extensions are exchanged, the definitions of the extensions must be available to all the parties that share the resources. Each extension contains a URI that references the source of the definitions as a Resource Profile. The source SHOULD be a literal reference, such as an http: url that refers to an end-point that responds with the contents of the definitions - preferably a FHIR RESTful server supporting the Resources Profile, or a logical reference (e.g. using a urn:) - for instance, to a national published standard.

1.6.4: Control of extensions

As well as defining the base element structure for resources, HL7 also publishes extensions. HL7 publishes data definitions as extensions rather than as part of the base resource structure in order to keep the base resource structure simple and concise, and to allow implementers not to engage with an entire world's worth of functionality up front. Note that HL7 extensions are never flagged as must-understand - if HL7 publishes resource content that must be understood, it will be part of the resource content itself, since everyone has to understand the extension anyway.

Before extensions can be used in instances, they must be published. HL7 maintains two extension registries, and users are encouraged to register their extensions there. But this is not required; all that is required is that the extension is published in a context that is available for users of the extension. So, for example, if a particular extension is used exchanged within a single institution, the definition of the extension can be placed on the institution's intranet. However since, by their nature, resources tend to travel well, it's always better to use the HL7 extension registries.

HL7 provides two extension registries. The first is for HL7 approved extensions. These have been approved by an appropriate part of the HL7 community following a review process, and have formal standing. The other registry is provided as a service to the community, and anyone can register an extension on it.

HL7 profiles defining extensions may be balloted alongside resource content as part of the FHIR specification or may be published as part of separate specifications. When HL7 publishes extensions as part of the FHIR specification, these extensions SHALL be used for this data whenever the data is represented in instances. Applications SHOULD use other HL7-defined extensions published to represent equivalent data in the interest of maximum interoperability. If referencing a profile that defines extensions, implementations declaring conformance with the profile SHALL use the profile-defined and imported extensions when conveying equivalent data elements.

To minimize complexity for implementers, HL7 will not elevate content defined in an HL7-approved extension to be content defined in a core resource in future versions of the resource.

In some cases, an HL7 work group or other body may publish a profile whose sole purpose is to define extensions expected to be needed by implementers in a particular context. E.g. extensions needed to map a particular set of v2 segments or a v3 model.

Implementations are encouraged to share their extensions with HL7 and register them with the HL7 extension registry. The domain committees will work to elevate the extensions into HL7 published extensions or, if adopted by a broad enough portion of the implementer community, the into the base resource structure itself.

To avoid interoperability issues, extensions SHALL NOT change their definition once published. (Small clarifications to descriptions that do not affect interoperability are permitted.) Rather than modifying an existing extension, a new extension should be introduced. Revisions to an extension may extend the set of contexts in which the extension apply but may not remove or constrain any context previously listed

2.6: Implementation Details

While the FHIR Resources are designed with a simple RESTful HTTP-based implementation in mind, it is not necessary to use this implementation framework. This specification also defines a straight messaging based implementation framework (§2.3) for FHIR resources and a document-based framework (§2.4).

2.6.5: Service Orientated use of Resources

Alternatively, it is not necessary to use any of these approaches. Resources can be exchanged or persisted using any technical means that is appropriate to the context at hand. A common use of FHIR resources or bundles (§1.2.3) is as parameters of service interfaces. FHIR itself does not define any particular service interface. Instead, other standards and implementations define their own service interfaces and architecture that use FHIR resources and optionally build extra features on top of the base repository-mediated exchange that the FHIR RESTful specification provides. As long as the resources that are used are conformant with this specification and the rules for authoring and reading applications are followed, then the implementation can claim conformance to "FHIR Resources". Such implementations will need to resolve several issues:

• Resource identity (the "id" metadata property) must be maintained. Resources all have an identity, which is how other resources refer to them, and these references need to be able to be resolved. However resources are exchanged, their identity - which is not included inside the resource - needs to be included with the resource
• Resource references need to be resolvable. There are a variety of solutions to this, from ensuring that the all the relevant resources are bundled together or that all relevant resources are passed as parameters in a service call, through to having a resource repository in the background that provides access to all referenced resources.
• The Resource metadata (§1.2.2) items "Version Id" and "Last Modified Date" are provided for use in resolving resource versioning and concurrency issues, both from a technical and human perspective. Most contexts of use will require at least one if not both of these attributes for some uses, and the implementation framework will need to resolve how and when they are exchanged.
• The conformance statement (§3.5) allows authoring and reading applications to describe their rules concerning the use and contents of a resource. The implementation will need to describe how this conformance statement or some other equivalent fits into the exchange/persistence context.
• How transactional information such as data enterer, author(s), responsible party, consent and approvals is treated

The resolution to these issues should be documented and published with the service specification.

2.6.6: Managing Resource Identity

Each resource has a known identity. The identity is not stored inside the resource, but must be tracked by systems handling resources. For RESTful systems, the resource identity is the same as the URL by which it is found. When a resource is packaged in a bundle (§1.2.3), the id is included along with the resource. Real-world use of FHIR resources creates the need to manage resource identification.

Resources are used in a variety of circumstances. Generally, these can be categorized into 3 different scenarios:

1. Closed Trading System: the resources are only ever exchanged between fixed systems in a tightly controlled community, such as a hospital. There is only one master server for each resource type, and resources are managed by that server. In this context, the logical id of a resource is sufficient to fully identify the resource
2. World-wide RESTful system: there are many peer servers, each managing a set of resources of different types. In order to identify resources, a full URL reference to the origin server is required
3. Partially closed, inter-linked systems: a mixture of both - trading communities that are tightly managed, but have managed interactions with other closed trading systems, or with the world-wide RESTful system, or both. In fact, this combination appears to be the most likely scenario for current real-world healthcare business solutions

These combinations are why either relative (logical) or absolute references are allowed, and why a logical id is always required, in order to enable seamless exchange amongst partially closed trading systems.

2.6.6.1: Copying Resources and re-identification

When resources are exchanged between systems, they may need to be re-identified (i.e. assigned a new resource). When a resource is re-identified, nothing in the resource changes, but any references that point to the resource need to be updated. Whether re-identification is required or not depends on the context, as does how resource references are updated.

The normal case is that a client/receiving system accepts the server/sender's identification of a resource at face value, whether it is a relative or absolute reference. When the client/receiver wants to follow resource references, they are done using the server id (typically either by http calls or locating them in a bundle (§1.2.3)). In such cases, there is no need for re-identification.

Another scenario is for a client to retrieve a resource from a server, and make its own local persistent copy. If the local resource has a life-cycle of its own (i.e. is it not just a cached resource), then it needs to have its own identity; i.e. the resource must be re-identified. The simplest case is that the client only is keeping local copies of resources from a single server. In these cases, the client can simply replace the root URL and keep the logical id of the resource the same. In fact, if the server is using relative references, then this change doesn't involve any actual changes to the resources, only a re-interpretation of the references.

In some cases, however, the client may deal with multiple servers. In this case, the logical id of the resource is not guaranteed to be unique (unless all resources have a UUID for the logical id, which is allowed but not required). When the client cannot be sure that the resource identities are unique, it will have to re-identify the resources. In practice this means that the client needs to keep an identity translation table, and update references to the resources it has copied locally when other resources are received.

The case of a gateway system that migrates resources from one eco-system to another is very similar. In some limited cases, it can leave the logical id of the resources unchanged as resources are copied from one closed system to another. However in more complicated cases, it will have to modify the resource references as resources pass across the gateway.

2.6.7: Workflow with resources

There are many ways to implement any particular workflow and there are many ways to use resources to build working systems:

• A RESTful paradigm where resources are exchanged separately using http transactions directly as defined in this specification. Implementations can use both push and pull or a mix of the two
• The resources can be exchanged in messages or some other SOA implementation where the resources form the contents/parameters that are exchanged
• The resources can be "bundled" into documents that are self-contained and complete collections of linked resources and then these documents can be exchanged and/or persisted
• The resources can be embedded in HTML pages or other web content such as content feeds

2.6.8: Implementation Support

This section contains links to content that assist implementers make FHIR work in production:

• All schemas as a .zip (includes support schemas, resource schemas, modular & combined schemas, and Schematrons
• Single combined feed with resource profiles. The resource profiles may be useful as a starting point for authoring profiles on the resources or with conformance statements
• All resource examples as a zip file (JSON equivalent examples)

TODO: add RDF & OWL renditions, eCore definitions, ADL versions, anything anyone else asks for

2.6.8.1: Reference Implementations

These reference implementations are provided for implementer interest and assistance. They may be used in production instances, though HL7 and its contributors accept no liability for this use. All these implementations are provided under a standard OSI approved BSD license (BSD-3-Clause).

These reference implementations are limited to code for representing the resource contents in their native form and parsing & serializing them as XML and JSON. In addition, some of the implementations provide support for building, using and reasoning with resource definitions. Full blown open source implementations for FHIR, some of which use these reference implementations, are listed on the HL7 wiki (http://wiki.hl7.org/index.php?title=Open_Source_FHIR_implementations) .

It is not necessary to use these particular implementations in order to be conformant. Any other approach may be used, including code generated from the schemas.

• Delphi: Resource Definitions and XML & JSON parsers. D5+. TODO: remove dependencies on unpublished code.
• Java: Resource Definitions + parser (+ more todo). The java reference implementation depends on XmlPull (http://www.xmlpull.org/), the Java JSON library (http://json.org) and the Apache Commons Codec library (http://commons.apache.org/codec/).
• C#: Resource definitions (+ more todo)
• ECore: Formal Object Definitions in OCLinECore text format - under development

2.6.8.2: Icons

Any (conformant?) FHIR Implementation is allowed to use the FHIR icon in association with the FHIR implementation. The FHIR icon is available in various sizes:

2.1: RESTful HTTP Details

In addition to the set of base resources, FHIR also provides a simple RESTful implementation using HTTP (http://www.w3.org/Protocols/rfc2616/rfc2616.html) . 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".

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 (§2.6).

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

The following logical interactions are defined:

2.1.1: Service Root URL

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

http(s)://server[/path]

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

http://server/path/patient

All the logical operations are defined relative to this service root URL. Note that this means that given the address of any one FHIR resource on a system, the correct address for all the other resources may be determined. However since application URLs may change and because in some uses of FHIR within internal eco-systems, local configuration may dictate that the provider of a resource is different to that claimed by any particular provider or consumer, applications may need to replace Service Root URLs.

Note: All URLs (and ids that form part of the URL) defined by this specification are case sensitive.

Note that a server may use a path of the form http://server/...[id]... where the id is some variable portion that identifies a particular instantiation of the FHIR API. Typically, the variable id identifies a patient, and the underlying information is completely compartmented by the patient id. In this case, the FHIR API presents a patient centric view of the record, where authentication/authorization is explicitly granted to the id contained in the URL.

2.1.2: Resource Metadata and Versioning

Each resource has an associated set of resource metadata elements (§1.2.2). These map to the http request and response using the following fields:

2.1.3: Security

See HTTP Security (§2.6.1).

2.1.4: HTTP Status Codes

This specification makes rules about the use of specific HTTP status codes in particular circumstances where the status codes must 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 Issue Report resource (§3.27) that can be used to convey specific detailed processible error information. For a few combinations of operations and specific return codes, an Issue Report is required to be returned as the content of the response. The Issue Report may be returned with any HTTP 4xx or 5xx response, but is not required - many of these errors may be generated by generic server frameworks underlying a FHIR server.

2.1.5: Content Types and encodings

The formal MIME-type for FHIR resources is application/fhir+xml (still to be registered) and SHOULD be use by clients and servers. Servers must support server-driven content negotiation as described in section 12 (http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html#sec12) of the HTTP specification, but in order to support various implementation limitations, may choose to support the (?_format=) parameter to specify alternative response formats by their MIME-types. For the _format parameter, the values "xml", "text/xml" and "application/fhir+xml" must be interpreted to mean the normative XML format defined by FHIR and "json", "application/json" and "application/fhir+json" must be interpreted to mean the informative JSON format.

FHIR uses UTF-8 for all request and response bodies. Since the HTTP specification (section 3.7.1) defines a default character encoding of ISO-8859-1, requests and responses MUST explicitly set the character encoding to UTF-8 using the 'charset' parameter of the MIME-type in the Content-Type header. Requests MAY also specify this charset parameter in the Accept header and/or use the Accept-Charset header.

2.1.6: read

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

  GET [service-url]/[resourcetype]/{@id} (?_format=mimeType) 

This returns a single instance with the content specified for the resource type. This url may be accessed by a browser. The logical id is preceded by a "@" to make parsing the url easier. The possible values for the id itself are described in the id type. Servers are required to return a content-location header with the response which is the full version specific url (see vread below) 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.

2.1.7: vread

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

  GET [service-url]/[resourcetype]/{@id}/history/{@vid} (?_format=mimeType)

This returns a single instance with the content specified for the resource type for that version of the resource.

The version id is an opaque identifier that conforms to the same format requirements as a resource id. The id may have been found by performing a history operation (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 are 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, it should return a 405 Method Not Allowed error.

2.1.8: update

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

  PUT [service-url]/[resourcetype]/{@id} (?_format=mimeType)

If the operation is successful, the server must return either a 200 OK if the resource was updated, or a 201 Created if the resource was created, along with a copy of the newly updated resource (which might not be the same as that submitted) with the response, along with a Last-Modified header, and a Location and Content-Location header that refers to the specific version created by the updated operation.

Servers are permitted to reject update operations because of integrity concerns or business rules implemented on the server, and return HTTP status codes accordingly (usually 422).

In particular, servers may choose to implement version-aware updates, where the only updates that are accepted quote the current version of the resource. In this case, the client must submit the currently correct version specific URL in the Content-Location in the PUT request. If the value is missing, the server SHALL return a 412 Preconditions failed response. Clients SHOULD submit a proper Content-Location header and SHALL correctly understand a 409 response as an update conflict.

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 basic FHIR validation rules
• 404 Not Found - resource type not supported, or not a FHIR end point
• 405 Method Not allowed - the resource did not exist prior to the update, and the serer does not allow client defined ids
• 409/412 - version conflict management - see above
• 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules. This should be accompanied by an Issue (§3.27) resource providing additional detail

2.1.9: delete

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

  DELETE [service-url]/[resourcetype]/{@id} 

A delete operation means that non-version specific reads (§2.1.6) of a resource return a 410 error and that the resource is no longer found through search operations. Upon successful deletion the server should return 204 (No Content). If the server refuses to delete resources of that type on principle, then it should return the status code 405 method not allowed. If the server refuses to delete a resource because of reasons specific to that resource, such as referential integrity, it should return the status code 409 Conflict. If the resource cannot be deleted because it does not exist on the server, the server must return 404 (Not found). Performing this operation on a resource that is already deleted has no effect, and should return 204. Resources may be undeleted by PUTting an update to them subsequent to the deletion.

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

2.1.10: create

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

  POST [service-url]/[resourcetype] (?_format=mimeType)

The server returns a 201 Created, along with a copy of the newly created resource (which might not be the same as that submitted) with the acknowledgement, along with a version-aware Location header which contains the new location and id of the created resource:

  Location: [service-url]/[resourcetype]/{@new-id}/history/{@new-vid}

When the payload data is incorrect and cannot be used to create a new resource, the server returns a 400 Bad Request.

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 basic FHIR validation rules
• 404 Not Found - resource type not supported, or not a FHIR end point
• 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules. This should be accompanied by an Issue (§3.27) resource providing additional detail

2.1.11: search

This interaction searches a resource type based on some filter criteria. The interaction is performed by two different HTTP Get operation as shown:

  GET [service-url]/[resourcetype]/search(?parameters) (&_format=mimeType)
  GET [service-url]/[resourcetype]/(?parameters) (&_format=mimeType)

Because of the way that some user agents treat POST requests, POST submissions are also allowed with exactly the same semantics as a GET operation. Search operations take a series of parameters that are a series of name'='value pairs encoded in the URL (or as an x-multi-part-form submission for a POST). (See W3C HTML forms (http://www.w3.org/TR/REC-html40/interact/forms.html#form-content-type) ). The search is processed as specified for the Query handling mechanism (§2.2).

The return content is an Bundle (§1.2.3) containing the results of the search as a list of resources in a defined order. Searches SHOULD use paging as described below (§2.1.18).

2.1.12: validate

The validate interaction checks whether the attached content would be acceptable as an update to an existing resource. The validation operation may be the first part of a light two- phase commit process. The interaction is performed by an HTTP POST operation as shown:

  POST [service-url]/[resourcetype]/validate/{@id}

The content is first checked against the general specification and against the conformance profile that applies to the application. How much additional checking over the normal create and update operations is performed is at the discretion of the server. Then the resource is considered as a proposed update and additional instance specific rules such as referential integrity and update logic (including version control) are applied as well. The return content has one of the following values:

• 400 Bad Request - resource could not be parsed or had some basic FHIR validation error
• 200 OK - resource passed all validation rules
• 422 Unprocessable Entity - the resource was valid, but it violates applicable FHIR profiles or server business rules

Unless the result is 200 OK, the response must include an Issue Report (§3.27) that lists the issues found on validation.

The validation operation has complex semantics and rules; see the full discussion of the operation in the OMG hData REST specification (§2.1.20) for further details.

2.1.13: conformance

The conformance interaction retrieves the application's conformance statement that defines how it supports resources. The interaction is performed by an HTTP OPTIONS or a GET operation as shown:

  GET [service-url]/metadata (?_format=mimeType)
  OPTIONS [service-url] (?_format=mimeType)

Applications SHALL return a Conformance Resource (§3.5) that specifies which resource types and operations are supported for the GET operation, and SHOULD do so for the OPTIONS oporation. If a 404 Unknown is returned from the GET, FHIR is not supported on the nominated service url. The GET operation is defined because not all client libraries are able to perform an OPTIONS operation. Additional parameters that are required to be returned with the OPTIONS command are defined in the OMG hData RESTful Transport (§2.1.20) specification.

Note that Servers may choose what content to return when they receive a GET operation on the Service Root URL. Generally some page that guides human manual interaction with the server would be appropriate.

A server may also choose to provide the standard set of operations on the Conformance Resource (§3.5), which means that it stores and manages a set of conformance statements. These managed conformance statements should not be confused with the server's own conformance statement, which is what is returned from these methods.

2.1.14: transaction

The transaction interaction submits a set of resources to be updated, created or deleted on the server. This interaction allows multiple resources to be updated/created in a single transaction. Multiple different types of resources may be submitted, including a mix of new and existing resources. The interaction is performed by an HTTP POST operation as shown:

  POST [service-url] (?_format=mimeType)

The content of the post submission is a resource bundle. The resources in the bundle are each processed separately as if they were an individual create (§2.1.10), update (§2.1.8) or delete (§2.1.9) as described below, along with the normal processing for each (such as tracking tags, verification and version aware updates). Servers SHALL either accept all resources and return a 200 OK, along with a response bundle, 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 the processing the transaction SHALL not depend on the order of the resources in the transaction. Note that this means that a resource can only appear in a transaction once, and since bundles may have the same resource more than once or other order dependencies (e.g. update lists), some kinds of bundles may not be able to be used in a transaction.

When a bundle is submitted in a transaction operation, all the resources have an identity specified in the bundle. If the identity of the resource matches an existing or possible resource location on the server, the server should treat this entry as an update operation (§2.1.8) (i.e. PUT to the given resource). If the identity is not one that the server recognises as a resource location it can use, the server should treat the operation as a create operation (§2.1.10) (i.e. POST to the given resource type URL), and create a new identity for the submitted resource. For clarity, when the client intends a resource to have a transient identity that the server must replace, it should use a cid: url on the resource. Note that the client must provide an identity in the bundle entry.id, but may also provide a version specific identity the atom "self" link, and may refer to this for version specific references. Deleted resources are those marked clearly using the method described for XML or JSON.

A transaction may include references from one resource to another in the bundle, which may include circular references where resources refer to each other. If the server assigns a new identity to any resource in the bundle, it SHALL also update any references to that resource in the same bundle as they are processed. References to resources that are not part of the bundle are left untouched. If a resource in the bundle carries a version-specific id (using its self-link), any version-specific references to it must also be updated. Servers SHALL be replace all matching links in the bundle, whether they are found in the resource ids, resource references, url elements, or <a href="" & <img src="" in the narrative.

Note that this allows clients to assign temporary (version-specific) ids to new resources and refer to them from within the bundle while the server will update these temporary ids after their creation. This is especially useful in RESTful scenario's where one would otherwise need multiple operations, possibly leading to loss of referential integrity (e.g. when storing a Provenance resource and its corresponding target resource), or, on document repositories, a document index entry and it's accompanying document.

In order to allow the client to know how newly created resources are now identified for future reference, the server must return a bundle containing the results of processing the resources in the same order that they were submitted.

The application constructing a bundle may not be sure whether a particular resource will already exist at the time that the transaction is executed; this is typically the case with reference resources such as patient and provider. In this case, the bundle should contain a candidate resource with a cid: identifier, and an additional search specifier using an Atom link:

 <link href="http://localhost/patient/search?[parameters]" rel="search"/>

A search link with a root of http://localhost means to search the local resource store for a match as specified in the parameters (which must conform to the servers capability for searching as specified in it's conformance statement). If the search returns no matches, the server process the resource normally. If the search returns one match, the server uses this matching resource instead, and ignores the submitted resource. If more than one resource is found, the transaction must be rejected.

If the server that is processing the transaction requires version aware updates, the client may need to reference what is the server's current version of the resource, which is now the client's previous version:

 <link href="[url]/patient/@34/history/@31" rel="predecessor-version"/>

The predecessor-version is treated as if it were the content-location header on an update operation.

2.1.15: history

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

  GET [service-url]/[resourcetype]/{@id}/history (?_format=mimeType)
  GET [service-url]/[resourcetype]/history (?_format=mimeType)
  GET [service-url]/history (?_format=mimeType)

The return content is a Bundle (§1.2.3) containing the specified version history, sorted with oldest versions last, and including deleted resources.

The history list can be restricted to a limited period by specifying a _since parameter which contains a full date time with timezone. Servers must ensure that if a client uses the feed.updated date from the last response they received as the value of the _since parameter, no versions will be missed. 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 SHALL use the method described in RFC 5005 (Feed Paging and Archiving) (https://tools.ietf.org/html/rfc5005) (also see above (§2.1.18)) for breaking the updates list into pages if appropriate.

The history operation is suitable for use with internet pub/sub systems based on rss/atom, including services such as Google Reader, allowing humans to easily subscribe to notifications of updates to a resource (this is usually appropriate for low volume high knowledge resources like profiles). In addition, the history operation can be used to set up a subscription from one system to another, so that resources are sychronised between them. Systems receiving such feeds and planning on enforcing resource integrity should note that transaction (§2.1.14) boundaries are not reflected in the history list.

Searches SHOULD use paging as described below (§2.1.18)

2.1.16: Tag Operations

Tags (§1.2.2.1) are attached to resources to define operational behaviour. When resources are exchanged directly use HTTP on the read, vread, create and update operations, the http header "Category" is used, following the method described for Web Categories (http://tools.ietf.org/html/draft-johnston-http-category-header-02) .

  Category: [Tag URI]; scheme="http://hl7.org/fhir/tag"; label="[Tag Uri]"

The label portion is optional. Note that label may come before scheme.

In the other operations, the resources are wrapped in bundles, where tags are represented in the entry.category element and servers populate these completely or process these as part of a transaction submission.

The following operations provide specific support for Tags:

GET [service-url]/tags

GET [service-url]/[type]/tags

GET [service-url]/[type]/@[id]/tags

POST service-url]/[type]/@[id]/tags

POST service-url]/[type]/@[id]/history/@[vid]/tags

DELETE service-url]/[type]/@[id]/tags

DELETE service-url]/[type]/@[id]/history/@[vid]/tags

The tags of an old version can still be changed. Note that changing the tags on a resource does not create a new version of the resource. A tag list is represented like this in XML and JSON:

<taglist xmlns="http://hl7.org/fhir">
    <!-- Tags in the list (0..*):   --> 
    <category term="[Tag Uri]" label="[Tag Label]" scheme="http://hl7.org/fhir/tag"> 
</taglist>

{
  "taglist" : {

    "category" : [{
        "term" : "[Tag Uri]",
        "label" : "[Tag Label]",
        "scheme" : "http://hl7.org/fhir/tag"
      }]
  }
}

2.1.17: Binary Support

FHIR servers can choose to offer support for purely binary resources at the end point [service-url]/binary. The binary end-point accepts any kind of content, such as images and other media, documents (CDA, PDF, Word etc), plain text, XML or anything else, and stores the content as is, along with the content type provided by the HTTP headers.

Binary resources function with the same operations as described above, except that there is no support for the search operation. The _format parameter has no meaning when used with binary resources: they are always represented using their original content type.

2.1.18: Paging

Servers SHOULD conform to the method described in RFC 5005 (Feed Paging and Archiving) (https://tools.ietf.org/html/rfc5005) for sending continuation links to the client when returning a bundle (e.g. with with history and search). If the server does not do this, there is no way to continue paging.

This example shows the third page of a search result:

<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Search Page 3</title>
  <!-- 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
	refernces into the stateful list.
	-->
  <link rel="self" href="http://example.org/patient/search?name=peter&stateid=23423443&page=3"/>

  <!-- 4 links for navigation in the search. All of these are optional, but recommended -->  
  <link rel="first" href="http://example.org/patient/search?name=peter&stateid=23423443&page=1"/>
  <link rel="previous" href="http://example.org/patient/search?name=peter&stateid=23423443&page=2"/>
  <link rel="next" href="http://example.org/patient/search?name=peter&stateid=23423443&page=4"/>
  <link rel="last" href="http://example.org/patient/search?name=peter&stateid=23423443&page=26"/>
  <updated>2003-12-13T18:30:02Z</updated>

  <!-- the rest of the search results... -->  
</feed>

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 operation using the totalResults element from the OpenSearch specification (http://www.opensearch.org/Specifications/OpenSearch/1.1) :

<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Search Page 3</title>
  <os:totalResults xmlns:os="http://a9.com/-/spec/opensearch/1.1/">1432</os:totalResults>
  
  <!-- the rest of the search results... -->  
</feed>

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.

2.1.19: Intermediaries

The HTTP protocol may be routed through an HTTP proxy such 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 (http://tools.ietf.org/html/rfc2616#page-74) 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 the rules that apply to HTTP proxies. Such agents are allowed, but must mark the http header to assist with troubleshooting.

Any agent that modifies an HTTP request or Response content other than under the rules for HTTP proxies must add a stamp to the HTTP headers like this:

  request-modified-[identity]: [purpose]
  response-modified-[identity]: [purpose]

The identity must be a single token defined by the administrator of the agent that will sufficiently identify the agent in the context of use. The header must specify the agent's purpose in modifying the content. End point systems must not use this header for any purpose. Its aim is to assist with system troubleshooting.

2.1.20: OMG hData RESTful Transport

This RESTful specification described here is based on the OMG Health RESTful specification (http://www.omg.org) (specific reference to be provided when this is published). In this regard, FHIR functions as a Record Format Profile as described in that specification. Note the following significant factors to be aware of:

• FHIR maps the hData sections to resource types, and hData documents to resource instances. There are no subsections, and client systems are not able to create new sections
• The FHIR resource id maps to the hData document name by prepending "@"
• Because clients cannot submit new sections (POST to service URL), POST to the service URL has been re-used for the transaction operation (§2.1.14) (difference under review)
• FHIR does not (yet) define a root document. When defined, it will contain information about what the FHIR server has done (as opposed to a conformance statement, which describes what it is capable of doing)
• Note that this specification does not repeat the rules in the hData RESTful Transport concerning the OPTIONS command on the service URL, but these rules (extra headers etc) still apply

2.1.21: Summary

These tables present a summary of the operations described here.

Note: N/A = not present, R = Required, O = optional.

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 a server errors and various codes associated with authentication protocols.

2.2: Resource Definition: Query

Status: A proposed resource

A description of a query with a set of parameters.

The resource name as it appears in a RESTful URL is /query/

2.2.1: Search / Query

One operation that is fundamental to the way FHIR works is to search (find existing resources by filter criteria) or query (more detailed questions based on existing data). Search/query operations can span complexity from a simple search based on indexed criteria, through to complex decision support based requests, and also direct queries that need to be handled by humans. This page documents the FHIR search framework, starting with the simple cases, and working into the increased complexity. Implementations need only implement the amount of complexity that they require.

In the simplest case, a search is executed by performing a GET operation in the RESTful framework:

 GET .../[resourcetype]/(?parameters)

Search/Query operations can also be initiated by other more complex and flexible methods described below.

In the RESTful search, the client requests that a search be performed using an HTTP call, and the parameters are a series of name=value pairs encoded in the URL or as an x-multi-part-form submission for a POST.

The server returns the results in the HTTP response. A HTTP status code of 403 signifies that the server refused to perform the query, while some other 4xx or 5xx code signifies an error.

2.2.2: Default Search Parameters

The search parameter _id which refers to the logical id of the resource.

 GET .../patient?_id=23

This search finds the resource with the given id (there can only be one resource for a given id)

In addition to this resource, each FHIR resource type defines a set of applicable search parameters with their names, types, and meanings. Mostly, the defined search parameters correspond to a single element in the resource, but this is not required, and some search parameters refer to the same type of element in multiple places, or refer to derived values.

Servers are not required to implement any of these search parameters (except for the _id parameter described above), and may define their own additional parameters if they wish.

2.2.2.1: Search Parameter Types

Each search parameter is defined a type that defines how the search parameter behaves. These are the defined parameter types:

The search parameters can also have "modifiers" appended to them that control their behaviour. The kind of modifiers that can be used depend on the type of parameter.

Modifiers

Parameters are defined per resource, and their names may additionally specify a modifier as a suffix, separated from the parameter name by a dot. Modifiers are:

• For all parameters: "missing". E.g. gender.missing=true (or false). Seaching for "gender-missing=true" will return all the resources that don't have any value for the gender parameter (which usually equates to not having the relevant element in the resource). Searching for "gender-missing=false" will return all the resources that have a value for the "gender" parameter.
• For dates: "before" and "after". E.g. birthdate.before=1972-11-30. See below for how date searches are interpreted.
• For string: "exact" (the match needs to be exact, no partial matches, case sensitive and accent-sensitive) and "partial" (the search may function on partial matches). TODO: left partial?
• For token: "text" (the match does a partial searches on the text portion of a CodeableConcept or the display portion of a Coding), "code" (a match on code and system of the coding/codeable concept).

integer

The prefixes >, >=, =<, and < may be used on the parameter value, and has the usual meaning. Note that '=" must be escaped in the value in a URL.

token

A token type is a parameter that searches on a code or identifier value where the value may have a URI that scopes it's meaning (from a Coding (§1.4.4) or an Identifier (§1.4.12) type, and also from a code where the URI is implicit).

If the parameter has no modifier, or the modifier 'text', the search parameter is a string, if the modifier is ‘code’ the parameter is a pair of fixed value strings, namespace and value, separated by a "!". Without modifier, the search will use the textual parameter to do a partial match on code, text or display. With modifier ‘text’ the search will do a partial match on text or display. With the ‘code’ modifier, the search will work as follows:

• name=namespace#code specifies matches on both the namespace and the code
• name=#code matches a code that has no specified namespace
• name=code matches all codes irrespective of the namespace

For token, you need (at least) to escape the ":" and possibly “#” (the fragment identifier) in the url of the code system.

date

A date parameter searches on a date/time or period. As is usual, while the concept is straight-forward, there are a number of subtleties involved in ensuring consistent behavior.

• The date parameter format is yyyy-mm-ddThh:nn:ss(TZ) (the standard XML format). Any degree of precision can be provided, but it must be populated from the left (e.g. can't specify a month without a year)
• Note that to use these values, you need to escape the “:” in the time part.
• All date parameters have an implicit -before and -after parameter. [date]=[value] searches for where the date is within the given date value. [date]-after=[value] searches for all resources where the specified date is after [value]. [date]-before=[value] searches for all resources where the specified date is before [value].
• The element the search refers to may be a date, a dateTime, a Period, or a Schedule. All of these time related types actually specify an interval of time, as does the search parameter itself.
  • For Period and Schedule, the interval of time is explicit, though the upper or lower bound may not be specified
  • For a date or a dateTime (and the search parameter), the interval is implicit. For example, the date 2013-01-10 specifies all the time from 00:00 on 10-Jan 2013 to immediately before 00:00 on 11-Jan 2013.
  • An instant (which is the same as a fully specified dateTime with milliseconds) is considered a fixed point in time with an interval smaller than the precision of the system, i.e. an interval with an effective width of 0.
• Date parameter searches are always matches based on the behaviour of intervals, as follows:
  • For [date]=[value], the requirement is that the search interval fully contains the time of the target. i.e. 2013-01-14 includes 2013-01-14T10:00 but not 2013-01-15T00:00
  • For [date]-before=[value], the requirement is that the interval of the time before [value] intersects (i.e. overlaps) with the interval of time in the relevant resource element. For instance, the resource time 2013-01-14 is included in the set of values that come before 2013-01-14T10:00, because it includes the part of 14-Jan 2013 before 10am
  • For [date]-after=[value], the requirement is that the interval of the time after [value] intersects (i.e. overlaps) with the interval of time in the relevant resource element. For instance, the resource time 2013-01-14 is included in the set of values that come after 2013-01-14T10:00, because it includes the part of 14-Jan 2013 after 10am
  If the bounds of the interval are not known (i.e. a range with no start, or a schedule like "every two days" with neither start or end), then the boundaries are implicitly considered above or below calculable time, and so these count as intersections. For instance, the period from 21-Jan 2013 onwards is included in matches for date-after=2013-03-14 because it may include times after 14-Mar 2013.
• Similarly, when the date parameter is not fully specified, matches against it are based on the behaviour of intervals, where:
  • Dates with just the year specified are equivalent to an interval that starts at the first instant of January 1st to the last instant of December 31st, eg. 2000 is equivalent to an interval of [2000-01-01T00:00, 2000-12-31T23:59]
  • Dates with the year and month are equivalent to an interval that starts at the first instant of the first day of the month and ends on the last instant of the last day of the month, eg. 2000-04 is equivalent to an interval of [2000-04-01T00:00, 2000-04-30T23:59]
• Where possible, the system should correct for timezones when performing queries. Dates do not have timezones, and timezones should not be considered. Where both search parameters and resource element date times do not have timezones, the servers local time zone should be assumed.
• Note that for a Schedule data type, the specified scheduling details are ignored and only the outer limits matter. For instance, a schedule that specifies every second day between 31-Jan 2013 and 24-Mar 2013 includes the 1-Feb 2013, even though that is on an odd day that is not specified by the period. This is to keep the server load processing queries reasonable.

reference

A reference parameter refers to references between resources, e.g. find all problems where the subject reference is a particular patient by the patient id.

The interpretation of a reference parameter is either:

• name=id the id of a resource (not including the @ the goes in the URL)
• name=type:id matches a specific target type. This is useful if the resource reference can refer to multiple different resource types.

In order to save a client from doing a series of search operations, reference parameters may be "chained" by appending them with modifiers which are search parameters defined for the target resource. This can be done recursively, following a logical path through a graph of related resources. For instance, given that the resource DiagnosticReport (§3.12) has a search parameter named subject, which is usually a reference to a Patient (§3.31) resource, and the Patient resource includes a parameter name which searches on patient name, then the search

 diagnosticreport/search?subject.name=peter

is a request to return all the lab reports that have a subject whose name includes "peter".

Advanced Search Note: Where a chained parameter searches a resource reference that may have more than one different type of resource as it's target, the parameter chain may end up referring to search parameters with the same name on more than one kind of resource at once. The parameter names defined in FHIR have consistent types wherever they are used. Implementers defining their own names need to be sure that they do not create unprocessible combinations.

2.2.2.2: Combining Search Parameters

The result of the search operation is the intersection of the resources that match the criteria specified by each individual search parameter. If a parameter repeats, such as /patient?language=FR&language=NL, then this matches a patient who speaks both languages. If, instead, the search is to find patients that speak either language, then this is a single parameter with multiple values, separated by a ',': /patient?language=FR,NL.

This allows for simple combinations of and/or values, but doesn't allow a search based on a pair of values, such as all observations with a sodium value >150 mmol/L (particularly as the end criteria of a chained search), or searching on Group.characteristic: you need find a combination of key/value, not an intersection of separate matches on key and value. Another example is spatial coordinates when doing geographical searches.

To allow these searches, a resource may also specify searches that take sequences of single values as an argument. The meaning of each component in such a sequence is documented in the definition of the parameter. These sequences are formed by joining the single values with a "$". Note that this sequence is a single value and itself can be composed into a set of values, so that, for example, multiple matching state-on-date parameters can be specified as state-on-date=new$2013-05-04,active$2013-05-05.

2.2.2.3: Selecting resources by Tag

Resources may have tags affixed to them. the _tag resource searches for a resource by URI. For example:

 problem/search?_tag=http://acme.org/fhir/tags/needs-review

This searches for all problem resources with the tag "http://acme.org/fhir/tags/needs-review". The _tag search parameter may have the modifiers .partial and .text, which mean to only match on the left side of the target tags, or to search the label part of the tag respectively.

2.2.3: Managing Returned Resources

2.2.3.1: Sorting

The client can indicate which order to return the results in using the parameter "_sort". This can be set to one of the search parameters. Where the search parameter returns multiple values, the lowest value will be used when ordering the returned records. Note that the actual sort value used is not returned explicitly by the server.

2.2.3.2: Page Count

In order to keep the load on clients, servers and the network minimized, the server may choose to return the results in a series of pages. The search result set contains the URLs that the client uses to request additional pages from the search set. For a simple RESTful search, the page links are contained in the returned bundle as links (§2.1.18).

Typically a server will it's own parameters to the links that it uses to manage the state of the query as pages are retrieved. These parameters do not need to be understood or processed by the client.

The parameter _count is defined as a hint to the server regarding how many resources should be returned in a single page. Servers SHALL not return more resources than requested (even if they don't support paging) but are allowed to return less than the client asked for. Note that it is at the discretion of the search engine how to handle ongoing updates to the resources while the search is proceeding.

2.2.3.3: Including other resources in result (_include)

Clients may request that the engine return additional resources related to the search results, in order to reduce the overall network query time. A typical case where this is useful is where the client is querying on some type of clinical resource, but for every such resource returned, the client will also need the subject (patient) resource that the clinical resource refers to. The client requests that the subject resources be included in the results set by providing one or more _include parameters.

Each _include parameter specifies a path to a url (usually a resource reference):

 GET .../medicationprescription/search?_include=MedicationDispense.prescription
    &_include=MedicationPrescription.prescriber&criteria...

For each returned resource, the server collects the elements described by the path, and any resources they point to that the server also holds are added to the results. This search returns all the Medication Prescription (§3.24) resources and their prescribing Practitioner (§3.33) Resources for the matching Medication Dispense (§3.23) resources.

Include paths are processed only in the context of a single resource - they can not include paths such as Resource.name1.name2 where name2 is a name in a resource pointed to by name1. Include paths may include wild cards, such as MedicationDispense.results.*, or even _include=*, though both servers and clients need to take care not to request or return too many resources when doing this.

For servers, recursive and wildcard _includes are demanding and may slow the search response time significantly. Servers are not obliged to honor requests to include additional resources in the search results.

External References

If the _include path matches an url that points to a resource that the server itself does not hold itself, the server may still elect to include the target of the uri reference in the returned results as a Binary resource. For example, the include path may point to an attachment which is by reference, like this:

 <content>
   <contentType>image/jpeg</contentType>
   <url>http://example.org/images/2343434/234234.jpg</url>
 </content>

The server can retrieve the target of this reference on behalf of the client, and add this to the results for the convenience of the client.

2.2.4: Server Conformance

In order to allow the client to be confident about what search parameters were used as a criteria by the server, the server SHALL return the parameters that were actually used to process the search. Applications processing search results SHALL check these returned values where necessary. For example, if the server did not support some of the filters specified in the search, a client might manually apply those filters to the retrieved result set, display a warning message to the user or take some other action.

In the case of a RESTful search, these parameters are encoded in the self link in the atom feed that is returned:

  <link rel="self" href="http://example.org/patient/search?name=peter"/>

In other respects, servers have considerable discretion with regards to supporting search:

• Servers can choose which parameters to support (other than _id above)
• Servers can choose when and where to implement parameter chaining, and when and where they support the _include parameter
• Servers are able to declare additional parameters in the profiles referenced from their conformance statements. Servers should define search parameters starting with a "-" character to ensure that the names they choose do not clash with future parameters defined by this specification
• Servers are not required to enforce case sensitivity on parameter names, though the names are case sensitive (and URLs are generally case-sensitive)
• Servers may choose how many results to return, though the client can use _count as above
• Servers can choose how to sort the return results, though they SHOULD honour the _sort parameter

2.2.5: Advanced Search/Query

The search framework described above is a useful framework for providing a simple search based on indexed criteria, but more sophistication is needed to handle precise queries, complex decision support based requests, and direct queries that have human resolution.

More advanced search/query operations are specified by the _query parameter:

   GET .../patient?_query=name&parameters...

The _query parameter names a custom search profile that describes a specific search/query operation. The named query may define additional parameters that are used with that particular named query, and will define their type and behavior on repetition and omission.

FHIR defines some named queries:

• Value Set Expansion (§3.42.4)

In addition, servers can define their own additional named queries to meet their own uses.

There can only ever be one _query parameter in a set of search parameters. Servers processing search requests must refuse to process a search request if they do not recognise the _query parameter value.

Some named queries may have side effects such as creating new clinical resources that may be persistent or transitory. The general search defined above always searches existing resources, and the only new resources that may be created are Security Event (§3.39) resources auditing the search.

2.2.6: Executing Search / Query

FHIR defines 3 different ways in which a search through a repository of resources can be initiated:

• Perform search (§2.1.11) operation on a RESTful interface (as described above)
• Send a query message, and receive a query response
• On a RESTful interface, create a query resource with an order, and wait for the order response (this allows asynchronous queries across a RESTful interface)

In all 3 cases, the basic operation is simple: given a set of parameters which are name/value pairs, perform a query against a repository of resources, and return the set of matching resources, possibly with some additional related resources. The second two search methods are implemented using the Query Resource.

2.2.7: Query Resource

The resource is used to perform queries using messaging-based exchanges, and to perform asynchronous searches using the RESTful interface.

2.2.8: Resource Content

See also the Examples (§4.43) and the Definitions (§5.45).

<Query xmlns="http://hl7.org/fhir">
 <id value="[uri]"/><!-- 1..1 Links query and it's response(s) -->
 <parameter>  <!-- 1..* Set of query parameters -->
  <name value="[string]"/><!-- 1..1 Name of parameter -->
  <value value="[string]"/><!-- 0..1 Value of parameter -->
 </parameter>
 <response>  <!-- 0..1 If this is a response to a query -->
  <id value="[uri]"/><!-- 1..1 Links response to source query -->
  <outcome value="[code]"/><!-- 1..1 Outcome of processing the query -->
  <total value="[integer]"/><!-- 0..1 Total number of matching records -->
  <parameter><!-- 1..* Content as for Query.parameter Parameters server used --></parameter>
  <first>  <!-- 0..1 To get first page -->
   <parameter><!-- 1..* Content as for Query.parameter Parameter list --></parameter>
  </first>
  <previous>  <!-- 0..1 To get previous page -->
   <parameter><!-- 1..* Content as for Query.parameter Parameter list --></parameter>
  </previous>
  <next>  <!-- 0..1 To get next page -->
   <parameter><!-- 1..* Content as for Query.parameter Parameter list --></parameter>
  </next>
  <last>  <!-- 0..1 To get last page -->
   <parameter><!-- 1..* Content as for Query.parameter Parameter list --></parameter>
  </last>
  <reference><!-- 0..* Resource(Any) Resources that are the results of the search --></reference>
 </response>
</Query>

Alternate definitions: Schema, RDF (to do), XMI (to do), Resource Profile

2.2.8.1: Terminology Bindings

Notes about the Query resource:

• The id is usually a UUID (urn:uuid:...). It's sole use is to match request and response logically
• The parameters defined for use with the query the resource are all those described above
• Parameter names are mandatory, and values are optional. Parameters with missing values are ignored when processing the query
• Parameter names do not need to be unique. The interpretation of multiple search parameters is as described above
• There SHALL be at least one parameter provided with a search - a search request without any request cannot be processed
• The search engine SHALL return the parameters used to process the search so the client knows what search was performed
• The links to first, previous, next and last pages in the query result set are provided at the discretion of the server. The client performs a new query using those parameters to retrieve the specified pages
• The references to the result set are usually version specific references
• In a RESTful search, with no query resource, there is no way to indicate that the search was limited

2.2.8.2: Messaging based Queries

In order to initiate a message-based query, a sender sends a message consisting of a Message (§2.3) resource, and a Query resource. The message resource routes the messasge to the correct destination, and the query contains the parameters of the search that is requested. See the examples (Known Broken Link - needs to be resolved) for an example query request message.

The receiver processes the message, and then returns a message with a message header, a query with a response details, and a set of resources that meet the query criteria. See the examples (Known Broken Link - needs to be resolved) for an example query response message.

If the sender wishes to retrieve additional pages from the original search, the sender constructs a new query with the parameters specified by the search processing system, and the cycle starts again.

2.2.8.3: Asynchronous Queries on a REST framework

The RESTful framework provides a simple convenient synchronous search based on request/response as described above. This works well as long it doesn't take very long to process a query. As the query processing time gets longer, the synchronous search starts to take too long to manage in this kind of framework. In particular, some queries may require human intervention to process correctly, or may even by direct humna-human queries. For these, some asynchronous approach is required. The messaging solution discussed above can be used asynchronously, but it's also possible to implement asynchronous queries in a RESTful environment. Here's how this would work:

1. The requester constructs a Query resource, and performs a create operation to the /query endpoint, and gets the id of the query resource on the server
2. The requester constructs an Order (§3.28) resource that contains details as appropriate, and which as the query resource as it's order detail, and creates that on the server
3. A responder picks up the existence of the order resource (either the server acting directly, or a client that is subscribed to the order feed on the server)
4. The responder retrieves the query, and then processes it, generating a new query resource that is the response, and then creates that on the server
5. The responder constructs an Order Response (§3.29) resource with a reference to the request from Step #2, a code of "complete", and a fulfillment that points to the query response from step #4
6. The requester sees the existence of the order response (e.g. by subscribing - watching the updates to Order Response on the server), and retrieves the query response
7. The requester retrieves the matching resources by iterating through the matching resources and retrieving them based on their reference.

This pattern is more complex than the other uses, so will be used less. There are several variations on this theme. For instance, the requester may choose to perform the first two operations as a transaction (§2.1.14), or the responder may choose to inform the requester that processing as commenced with an order response code of "accepted".

Note that it's also possible to expose service end points in a SOA fashion that use the query resource and/or definitions in other ways, though such usages are not described in FHIR.

2.2.9: Search/Query Result Currency

The results of a search/query operation are only guaranteed to be current at the moment the operation is executed. After the operation is executed, ongoing actions performed on the resources against which the query was executed will render the results increasingly stale. The significance of this depends on the nature of the search, and the kind of use that is being made of the results.

This is particularly relevant when the server is returning the results in a series of pages. It is at the discretion of the search engine how to handle ongoing updates to the resources while the search is proceeding.

Query result sets may include resources created by the processing of the search. Typically, these are the results of queries for decision support, value set expansion, etc, and represent the outcome of processing the query. In order to be usable in the scenarios above, these resources have a defined structure and have the same metadata as any other resource, including a known identity, but they have the same currency issues as the results from a query.

Applications handling the results of an operation that creates resources should use these resources with careful consideration of their currency. Though the resources may be retained for audit purposes, implementers must be careful not to reuse these as if they are current.

note: known issues relating to this page:

• The question of searching on a particular resource (as described by the RESTful interface). is this a parameter? Should the restful search operate at the system level as well?
• The overlap between query response and operation outcome in the case of errors in them messasging context

2.2.10: Searching the Searches

As a consequence of the general framework, it is possible to search on a set of stored queries, though there is no known particular use case for doing so.

2.2.11: Search Parameters

Search Parameters for RESTful searches. The standard parameters also apply. See Searching (§2.1.11) for more information.

(See Searching (§2.1.11)).

2.3: Resource Definition: Message

Status: Approved infrastructure resource. Draft for comment

A transmission requesting action on a bundle of one or more resources or a response to such a request.

This page describes how FHIR Resources can be used in a traditional messaging context, much like HL7 v2. Applications claiming conformance to this framework claim to be conformant to "FHIR messaging".

In FHIR messaging, a "request message" is sent from a source application to a destination application when an event happens. Events mostly correspond to things that happen in the real world. The request message consists of a bundle (§1.2.3) of resources, with the first resource in the bundle being this Message resource. The Message resource has a code - the message event - that identifies the nature of the request message and carries additional request metadata. The other resources in the bundle depend on the type of the request.

The events supported in FHIR, along with the resources that are included in them, are defined below.

The destination application processes the request and returns one or more response messages which are also a bundle (§1.2.3) of resources, with the first resource in the bundle being a Message (§2.3.4) resource with a response section that reports the outcome of processing the message and any additional response resources required.

2.3.1: Basic Messaging Assumptions

This specification assumes that content will be delivered from one application to another by some delivery mechanism, and then a response will be returned to the source application. The exact mechanism of transfer is irrelevant to this specification, but may include file transfer, http based transfer, MLLP (HL7 minimal lower layer protocol), MQ series messaging or anything else. The only requirement for the transfer layer is that requests are sent to a known location and responses are returned to the source of the request. This specification considers the source and destination applications as logical entities, and the mapping from logical source and destination to implementation specific addresses is outside the scope of this specification.

In principle, source applications are not required to wait for a response to a transaction before issuing a new transaction. However in many cases, the messages in a given stream are dependent on each other, and must be sent and processed in order. In addition, some transfer methods may require sequential delivery of messages.

This specification ignores the existence of interface engines and message transfer agents that exist between the source and destination. Either they are transparent to the message/transaction content and irrelevant to this specification, or they are actively involved in manipulating the message content. If these middleware agents are modifying the message content, then they become responsible for honoring the contract that applies (including applicable profiles) in both directions.

2.3.1.1: Message Identifiers

An incoming message contains two identifiers: the envelope id (feed (§1.3.8.1).id) and the message (§2.3).id. Each time a new message is created, it must be assigned an identifier that is unique within that message stream. Note that since message streams are often merged with other streams, it is recommended that the id should be globally unique. This can be achieved by using a UUID or an OID or appropriately chosen URI with a serially incrementing number. Each time a message is sent, the bundle identifier should be changed to a new identifier.

When a receiver receives and processes the message, it responds with a new message with a new id, wrapped in a bundle which also has a new id. The response message also quotes the request message id so that the source system can relate the response to it's request.

2.3.1.2: Absence of Reliable Messaging

Some of the message delivery mechanisms mentioned above are reliable delivery systems - the message is always delivered, or an appropriate error is returned to the source. However most implementations use methods which do not provide reliable messaging, and either the request or the response can get lost in transit. FHIR messaging describes a simple approach to handle this that receivers should conform to in order to maintain predictable functionality even when messaging is not reliable.

When considering the issue of reliable messaging, the source application should consider whether the message is a message of consequence, or a message of currency. A message of consequence is one where the message requests a change that should not be processed more than once, and where the sender needs the response that results from processing the message. A message of currency is where the correct response is the very latest information available. Typically, this is status information. Some messages fit into neither category - the response does not particularly matter. Usually these are notification messages.

In order to enable these processing rules, and to benefit from them, the original sender of the message SHALL do the following when it receives no response to a message within a configured timeout period:

When a receiver declares that it implements reliable answers, it SHALL check the incoming envelope and message ids against a cache of previously received messages. The correct action to take depends on what is received:

The duration period for caching does generally not need to very long. At a minimum, it could be 1 minute longer than the timeout of the sending system, though it may need to be longer depending on the re-sending policies of the sending system.

TODO: describe some use cases

2.3.2: Conformance Statement

Applications may only claim to be conformant to "FHIR messaging" if they publish a conformance statement so the claim may be verified. A conformance statement lists all the message events they support (either as sender or receiver) and for each event, a profile that states which resources are bundled (sender), or are required to be bundled (receiver), and any rules about the information content of the individual resources. The conformance statement is a resource with the name "Conformance" (§3.5).

2.3.3: Messaging End-points

There are two end-points defined for a RESTful server that supports Messages:

• [baseurl]/message/: a normal RESTful end point for message resources
• [baseurl]/mailbox: an address at which messages can be delivered

The first end-point is used for working within the message contents, for instance, for building messages piecemeal or for auditing received messages. Creating or updating Message resources to this end point does not represent the actual occurrence of any event, nor can it trigger any logic associated with the actual event. It is just for managing message resources.

The second end-point is used for actually sending messages as bundles (§1.2.3), to indicate that the event identified by the code has occurred. The end-point responds with a message response as defined for the particular event, or an error indicating that the attempt to process the message was unsuccessful. The functionality of this end-point is described below (§2.3.7).

Note: While the end-points above are defined for use with message resources and for delivering messages to a RESTful server, it is not necessary to use them; messages may be transported between systems using any method desired.

2.3.4: Resource Content

See also the Examples (§4.30) and the Definitions (§5.32).

<Message xmlns="http://hl7.org/fhir">
 <identifier value="[id]"/><!-- 1..1 Id of this message -->
 <timestamp value="[instant]"/><!-- 1..1 Time that the message was sent -->
 <event value="[code]"/><!-- 1..1 Code for the event his message represents -->
 <response>  <!-- 0..1 If this is a reply to prior message -->
  <identifier value="[id]"/><!-- 1..1 Id of original message -->
  <code value="[code]"/><!-- 1..1 Type of response to the message -->
  <details><!-- 0..1 Resource(OperationOutcome) Specific list of hints/warnings/errors --></details>
 </response>
 <source>  <!-- 1..1 Message Source Application -->
  <name value="[string]"/><!-- 0..1 Name of system -->
  <software value="[string]"/><!-- 1..1 Name of software running the system -->
  <version value="[string]"/><!-- 0..1 Version of software running -->
  <contact><!-- 0..1 Contact Human contact for problems --></contact>
  <endpoint value="[uri]"/><!-- 1..1 Actual message source address or id -->
 </source>
 <destination>  <!-- 1..1 Message Destination Application -->
  <name value="[string]"/><!-- 0..1 Name of system -->
  <target><!-- 0..1 Resource(Device) Particular delivery destination within the destination --></target>
  <endpoint value="[uri]"/><!-- 1..1 Actual destination address or id -->
 </destination>
 <enterer><!-- 0..1 Resource(Practitioner) The source of the data entry --></enterer>
 <author><!-- 0..1 Resource(Practitioner) The source of the decision --></author>
 <receiver><!-- 0..1 Resource(Practitioner|Organization) Intended "real-world" recipient for the data --></receiver>
 <responsible><!-- 0..1 Resource(Practitioner|Organization) Final responsibility for event --></responsible>
 <effective><!-- 0..1 Period Time of effect --></effective>
 <reason><!-- 0..1 CodeableConcept Cause of event --></reason>
 <data><!-- 0..* Resource(Any) The actual content of the message --></data>
</Message>

Alternate definitions: Schema, RDF (to do), XMI (to do), Resource Profile

2.3.4.1: Terminology Bindings

2.3.5: Notes:

• The resource references enterer, author and responsible may all be included in the bundle or left out on the basis that the recipient (and any intermediaries) are able to locate/resolve the resources independently. The former would be suitable for loosely coupled systems, and the latter for tightly coupled systems. The messaging conformance statement for an application may reference a profile (§3.36) that describes how the bundling occurs
• The actual content of the data resource is specified for each message event. The data resource is always included in the bundle

2.3.6: Event List

2.3.7: Mailbox

The mailbox is the standard name for a service hosted on a RESTful server that accepts messages and processes them as transactions and returns a message response appropriate for the message received. The server is under no obligation to do anything particular with the resources except as required by the semantics of the event code in the message resource. A server may choose to retain the resources and make them available on a RESTful interface, but is not required to do so. If the server returns 200 Ok, it must return a valid message that indicates what the outcome of the event processing is. An HTTP error indicates that the message was not processed successfully and that it should be resubmitted (and doing so should not result in a duplicate message response). Repeated failures indicate either a fatal problem with the message or a problem with the receiving application.

The mailbox can also be used to accept documents. In this case, the document is "accepted" (the server takes responsibility for custody of the received document) and an HTTP status of 204 No Content is returned, or an HTTP error is returned. The server is under no obligation to do anything with the document except as specific trading partner agreements dictate.

The following rules apply to the mailbox:

• The mailbox only accepts POST transactions - any other HTTP method will result in an HTTP error
• The request content type submitted is always a bundle (§1.2.3) containing a message or document resource as the first resource
• The response content type returned is always an HTTP error, a bundle (§1.2.3) containing a message as the first resource, or empty (if a document was received)
• If the response is an error, the body SHOULD be an Errors & Warning (§3.27) resource with full details
• The URL never takes any parameters
• The mailbox may be authenticated using standard HTTP authentication methods, including OAuth

This simple mailbox profile can be used by any HTTP end point that accepts FHIR messages or documents, not just FHIR RESTful servers.

In order to ensure consistency of processing, the logical rules regarding processing of envelope id and message id described above (§2.3.1.2) SHALL be followed when messages are processed using the MailBox. No such rules apply regarding documents - if the client receives no response, it should continue to submit the document until it does. Servers SHALL accept multiple document submissions and process them correctly.

2.3.8: Search Parameters

Search Parameters for RESTful searches. The standard parameters also apply. See Searching (§2.1.11) for more information.

(See Searching (§2.1.11)).

2.4: Resource Definition: Document

Status: Approved infrastructure resource. Draft for comment

A documentation of healthcare-related information that is assembled together into a single statement of meaning that establishes its own context. A document is composed of a set of resources that include both human and computer readable portions. A human may attest to the accuracy of the human readable portion and may authenticate and/or sign the entire whole. A document may be kept as a set of logically linked resources, or they may be bundled together in an atom feed.

FHIR resources can be used to build clinical documents that capture information about clinical observations and services. A clinical document is a bundle (§1.2.3) (a list of resources in an atom feed (§1.3.8.1)) that is fixed in scope, frozen in time and authored and/or attested as a set of logically contained resources by humans, organisations and devices. Documents built in this fashion may be exchanged between systems and also persisted in document storage and management systems, including systems such as IHE XDS. Applications claiming conformance to this framework claim to be conformant to "FHIR documents".

Note that FHIR defines both this document format and also a document reference resource (§3.13). FHIR documents are for documents that are authored and assembled in FHIR, while the document reference resource is for general references to other documents.

2.4.1: Document Content

All documents have the same structure: a bundle (§1.2.3) that has a Document resource (see below) first, followed by a series of other resources referenced from the Document header that provides guidance on how they fit together. The bundle gathers all the content of the document into a single XML document which may be signed and managed as required. The resources include both human and computer readable portions.

The document resource identifies the document and its purpose, sets the context of the document and carries key information such as the subject and author. It also divides the document up into a series of sections that contain other resources identified in this specification that carry the content. Any resource referenced directly in the Document resource must be included in the bundle when the document is assembled. Other resources that these referenced resources refer to may also be included in the bundle if the document originator chooses to.

Document profiles (§3.36) can make additional rules about which resources must be included in the bundle along with the resources that are directly referenced in the Document resource. In addition, Document Profiles can specify what sections a document contains and what the constraints on those contents are. Applications should consider publishing conformance statements (§3.5) that identify particular documents they support.

2.4.2: Document End-Points

There are two RESTful end-points used for Documents:

• [baseurl]/document/: a normal RESTful end point for document resources as standalone resources
• [baseurl]/binary/: for documents as bundles (§1.2.3)

Note: While these end-points are defined for use with document resources and document bundles, it is not necessary to use them. Documents may be transferred between systems by using the MailBox (§2.3.7) target, or by using any other method desired.

2.4.3: Resource Content

See also the Examples (§4.16) and the Definitions (§5.18).

<Document xmlns="http://hl7.org/fhir">
 <identifier><!-- 0..1 Identifier Logical identifier for document (version-independent) --></identifier>
 <versionIdentifier><!-- 0..1 Identifier Version-specific identifier for document --></versionIdentifier>
 <created value="[instant]"/><!-- 1..1 Document creation time -->
 <class><!-- 0..1 Coding Particular kind of document --></class>
 <type><!-- 1..1 CodeableConcept Kind of document (LOINC if possible) --></type>
 <title value="[string]"/><!-- 0..1 Document title -->
 <confidentiality><!-- 1..1 Coding As defined by affinity domain --></confidentiality>
 <subject><!-- 1..1 Resource(Patient|Group|Device) Who/what the document is about --></subject>
 <author><!-- 1..* Resource(Practitioner|Device) Who/what authored the final document --></author>
 <attester>  <!-- 0..* Attests to accuracy of document -->
  <mode value="[code]"/><!-- 1..1 personal | professional | legal | official -->
  <time value="[dateTime]"/><!-- 0..1 When document attested -->
  <party><!-- 0..1 Resource(Patient|Practitioner|Organization) Who attested the document --></party>
 </attester>
 <custodian><!-- 0..1 Resource(Organization) Org which maintains the document --></custodian>
 <event>  <!-- 0..1 The clinical event/act/item being documented -->
  <code><!-- 0..* CodeableConcept Code(s) that apply to the event being documented --></code>
  <period><!-- 0..1 Period The period covered by the document --></period>
  <detail><!-- 0..* Resource(Any) Full details for the event(s) the document concents --></detail>
 </event>
 <visit><!-- 0..1 Resource(Visit|InterestOfCare) Context of the document --></visit>
 <replaces value="[id]"/><!-- 0..1 If this document replaces another -->
 <provenance><!-- 0..* Resource(Provenance) Additional provenance about the document and it's parts --></provenance>
 <stylesheet><!-- 0..1 Attachment Stylesheet to use when rendering the document --></stylesheet>
 <representation><!-- 0..1 Attachment Alternative representation of the document --></representation>
 <section>  <!-- 0..* Document is broken into sections -->
  <code><!-- 0..1 CodeableConcept Classification of section (recommended) --></code>
  <subject><!-- 0..1 Resource(Patient|Group|Device) If section different to document --></subject>
  <content><!-- 0..1 Resource(Any) The actual data for the section --></content>
  <section><!-- 0..* Content as for Document.section Nested Section --></section>
 </section>
</Document>

Alternate definitions: Schema, RDF (to do), XMI (to do), Resource Profile

2.4.3.1: Terminology Bindings

2.4.3.2: Constraints

• A document must have a representation, one or more sections or both (xpath: exists(f:representation) or exists(f:section))
• A document stylesheet must have a mime type of text/css (xpath on /stylesheet: f:mimeType/@value = 'text/css')
• A section must have content or one or more sections, but not both. (xpath on /section: exists(f:content) != exists(f:section))

2.4.4: Notes:

• The author and the attester are often the same person, but this may not be the case in some clinical workflows
• The attester attests to the collated narrative portions of the document resource, the subject resource, and the resources referred to in the the Document.section.content references. When a document is bundled, additional resources can be included, but these are not attested content
• The custodian is responsible for the maintenance of the document. Principally, they are responsible for the policy regarding persistence of the documents. They need not actually retain a copy of the document, but they should do so.

2.4.5: Identifying a Document

There are two identifiers on the document information: id and versionId. These allow either a logical document id or a version specific id to be provided, or both. This supports multiple different identification strategies. The following combinations are allowed:

• A fully specified (both Identifier (§1.4.12) system and id) element is present for both id and versionId. This is the preferred option: globally unique identifiers for both version and non-version specify the document
• A fully specified element for the id element and a local id (no system) for the version number. This is equivalent to a document id and a version number. In this case the version number is assumed to be unique within the version series of the document identified by the id element
• A fully specified versionId with no id - this version of this document is identified, but there is no version independent reference. This is discouraged, as explicit replacement tracking will be required and this can be broken by missing links in the version chain

Any other combinations do not globally uniquely identity a document and are therefore not allowed.

Note that there is an additional identifier - the bundle identifier itself (atom (§1.3.8.1) feed.id). This must be an absolute URI - in effect globally unique - but has no other particular meaning anywhere else in the specification. For a document, it can be populated with some URI that is extracted from the versionId or id above, or it can be a new UUID that has no other associated use. Implementers should not rely on its value matching one of the formal document identification elements.

2.4.6: Presenting a Document

The human display of the Document is the collated narrative portions of following resources (in order):

1. The Document itself
2. The Subject resource
3. Resources referenced in the section.content

The document narrative should summarize the important parts of the document header that are required to establish clinical context for the document (other than the subject, which is displayed in its own right). To actually build the combined narrative, simply append all the narrative <div> fragments.

2.4.6.1: Styling Documents

In addition to the basic style rules (§1.3.2.2), which must be followed, a document can contain a style sheet that contains additional styles that apply to the collated narrative. Unless otherwise agreed in local trading partner agreements, applications displaying the collated narrative should use the style sheet provided in the document. Parties entering into such a trading agreement should consider the implications it will have on their long term scope for document exchange very carefully. If the parties agree on a stylesheet that is not contained in the document, then it is likely that they will never be able to share their documents in a more general context, such as a regional or national EHR, or a global personal health record.

2.4.7: Document Handling Obligations

The authors and users of Clinical Documents, whether human or software, have obligations that they must satisfy.

2.4.7.1: Author Obligations

A document author is an application that creates a document resource. The author may create new content resources and/or assemble already existing content resources while doing so. A document author has the following responsibilities:

• Build a valid document header that conforms to the Document rules explained here and that only links to other valid resources
• Ensure that the content of the document and other resources conforms to any declared Profiles (§3.36).
• Ensure that the attesters are properly aware of the presentation of the document to which they are attesting

2.4.7.2: User Obligations

A document user is an application that receives or presents documents, or extracts data from them, or makes decisions because of them. The documents may be received directly from a document author, accessed via a document management system or forward by a third party. The document user is responsible for ensuring that received documents are processed and/or rendered in accordance to this specification. A document recipient has the following obligations:

• When storing/transmitting a document, any method may be used as long as the bundled document can be (re-)assembled with sufficient integrity to validate a digital signature (i.e. it is legitimate to unbundle the resources and store them on a FHIR RESTful server, but this is not required)
• When presenting the narrative of the document, the rules described above must be followed
• A user is allowed to extract resources or data from the document for other use, but such data is no longer considered to be attested by the document author
• Wherever the data (or information derived from it) is displayed to a user, there should always be a way for the user to access a presentation of the original document
• It must correctly determine when a document has been superseded (according the statements made in the setId, version or replaces elements of received documents or those in the source document management system) and either withdraw data extracted from superseded documents, or warn users when they view the document

2.4.8: Implementation Notes

• Document Bundles may be signed using digital signatures following the rules laid out in the Atom specification (http://tools.ietf.org/html/rfc4287) . The signature SHOULD be provided by a listed attester of the document and the signature SHOULD contain a KeyInfo element (http://www.w3.org/TR/xmldsig-core/#sec-KeyInfo) that contains a KeyName element whose value is a URI that matches the Atom link element value for the matching attester resource.

2.4.9: Search Parameters

Search Parameters for RESTful searches. The standard parameters also apply. See Searching (§2.1.11) for more information.

(See Searching (§2.1.11)).

2.5: Common Scenarios in FHIR

FHIR is a framework standard that defines a common way to solve healthcare problems, and provides a set of resources that can be used in many different ways. This page describes how certain common usage scenarios are implemented using the capabilities that FHIR defines.

2.5.1: Personal Health Record (PHR)

In the PHR scenario, an Electronic Medical Record system (EMR, though many other names and acronyms are also used) provides a RESTful API that allows patients to access their own medical record using a common web portal or mobile application. In this scenario, the PHR provider:

• Provides the patient with a login that identifies them (or links the patient record to an external identity provided by OpenID, Facebook, Google, etc.)
• Authenticates the client using the appropriate OAuth server and restricts the client to viewing records associated with the specific patient

The EMR exposes a FHIR server that supports the search and read operations on the following resources:

1. the patient (§3.31) resource in order to provide demographics to the client. When a client searches patients with no search criteria, they get a list of all patients they have access too
2. search and read on the Document Reference (§3.13) resource to provide access to general patient documents in the form of PDFs
3. search and read on a set of clinical resources potentially including Observation, DiagnosticReport, various Medication resources, AdverseReaction/AllergyIntolerance, CarePlan, and Problem

Here is the conformance Profile for this scenario:

The EMR may also choose to provide additional functionality, such as shared access to patient records by relatives/carers, to allow the patient to upload their own documents, medication statements, observations (e.g. from patient monitoring devices) and/or to allow the patient to make appointments. This additional functionaly will involve additional API capabilities to be implemented and exposed. The EMR server may also choose to expose the read, search and updates operation on the Security Event resource for the patient-specific records to allow patient review of record access.

2.5.2: XDS

2.5.3: Decision Support

2.6: FHIR Security

Fast Healthcare Interoperability Resources (FHIR) is not a security protocol, nor does it define any security related functionality. However FHIR does define exchange protocols and content models that need to be used with various security protocols defined elsewhere. This section gathers all information about security in one section. A summary:

• Communications Security - all exchange of production data should be secured using TLS/SSL (e.g. https)
• Authentication - Users/Clients may be authenticated in any way desired. For web-centric use, OAuth is recommended
• Authorization/Access Control - FHIR defines a Security Label infrastructure to support access control management. FHIR may also define a set of resources to administer access control management, but does not do so at present
• Audit - FHIR defines provenance (§3.37) and security event (§3.39) resources suitable for tracking the origins, authorship, history, status and access of resources
• Digital Signatures - FHIR includes several specifically reserved locations for digital signatures
• Attachments - FHIR allows for binary resources and attachments. These have their own concerns

Time critical concerns regarding security flaws in the FHIR specification should be addressed to the FHIR email list (http://wiki.hl7.org/index.php?title=FHIR_email_list_subscription_instructions) for prompt consideration. Alternatively, issues can be raised through the community input (http://wiki.hl7.org/index.php?title=FHIR_Security_Page) mechanism.

Implementers should track developing IHE IUA Profile for additional security considerations.

A production FHIR system will need some kind of security sub-system that administers users, user authentication and user-authorization. Where this sub-system fits into the deployment architecture is a matter for system design:

The consumer that is using a healthcare related system The client application the user is using (application, mobile app, website, etc) The security system that authenticates and authorizes the user The clinical/healthcare repository

In this diagram, the red lines represent FHIR interfaces. From the perspective of the FHIR API, the client (consumer of FHIR services) may either interact with a security system that manifests as a FHIR server, and which depends on a subsequent FHIR interface to provide the actual storage, or either the client or server interacts with the security system independently. In each of these 3 scenarios, the different components may be assembled into applications or networks components differently, but the same logical layout applies.

The FHIR specification assumes that a security system exists, and that it may be deployed in front or behind the FHIR API. Because there are a plethora of standards relating to the administration and functionality of the security system, FHIR does not provide user, profile, or other such administration resources. Instead, the FHIR resources are the targets of the policies expressed in these other approaches. What FHIR does specify is a way to apply security labels to resources so that a security system may use these (along with the contents of the resources if appropriate) to determine whether a user is authorised to perform a particular FHIR operation or not.

2.6.1: Communications

For the RESTful API, normal HTTP security rules apply. The Service Root URL will specify whether SSL is required. Client authentication may be required by the server, possibly including the requirement for client certificates.

2.6.2: Authentication

Other than testing systems, FHIR servers should authenticate the clients. The server may choose to authenticate the client system and trust it, or to authenticate the individual user by a vareity of techniques. For web-centric use, OAuth (http://oauth.net/) may be used to authenticate and/or authorise the users.

2.6.3: Authorization/Access Control

todo

2.6.4: Mapping between resources and security systems

Correctly identifying people, devices, locations and organisations is one of the foundations that any security system is built on. Most uses of security protocols, whether authentication, access control, digital signatures etc rely on the correct mapping between the relevant resources and the underlying systems. Note that this isn't necessary: there is nothing in FHIR that requires or relies on any security being in place, or any particular implementation. But real world usage will generally require this.

Todo.. outline general considerations

2.6.5: Digital Signatures

to do

2.6.6: Attachments

Several FHIR resources include attachments. Attachments can either be references to content found elsewhere, or included inline encoded in base64. Attachments represent security risks in a way that FHIR resources do not, since some attachments contain executable code. Implementers should always use caution when handling resources.

2.6.7: Security Labels

3.6: Resources

The FHIR specification presently defines the following resources:

The list of resources is growing as FHIR is developed. Over the coming months, the number of resources and the number of those that have been vetted by HL7 committees will grow. A list of hypothesized list of resources can be found on the HL7 wiki (http://wiki.hl7.org/index.php?title=FHIR_Resource_Types) . Feel free to add any you feel are missing or engage with one of the HL7 Work Groups (http://www.hl7.org/Special/committees/index.cfm) to submit a proposal (http://wiki.hl7.org/index.php?title=Category:FHIR_Resource_Proposal) to define a resource of particular interest.

3.1: Resource Definition: AdverseReaction

Status: Not an approved resource: Draft. Under consideration by the Patient Care work group

AdverseReaction.

The resource name as it appears in a RESTful URL is /adversereaction/

Adverse Reaction resources are used to provide information about specific reactions to a substance. These are normally associated with an AllergyIntolerance (§3.3) resource, but can be reported on their own when no assumption of further reactions is being made, or when specific events are being described.

An Adverse Reaction normally has a set of sign or symptoms that are reported in the Symptom class. However, it is possible to convey that an adverse reaction occurred without knowing the specific signs or symptoms that occured, eg. Some unknown reaction occurred. Similarly, it is possible to convey that an adverse reaction with a set of symptoms occurred but not indicate the substance if it is not known. eg. A rash occurred for some unknown reason.

The Exposure class is used to indicate a set of exposures that preceded the reaction. There is no assertion of causality, purely a statement of timing. Each exposure can indicate a substance that might be different from the reaction if needed.

3.1.1: Resource Content

See also the Examples (§4.4) and the Definitions (§5.6).

<AdverseReaction xmlns="http://hl7.org/fhir">
 <reactionDate value="[dateTime]"/><!-- 0..1 When the reaction occurred -->
 <subject><!-- 1..1 Resource(Patient) The subject of the adverse reaction --></subject>
 <didNotOccurFlag value="[boolean]"/><!-- 1..1 To say that a reaction to substance did not occur -->
 <recorder><!-- 0..1 Resource(Practitioner|Patient) Who recorded the reaction --></recorder>
 <symptom>  <!-- 0..* The signs and symptoms that were observed as part of the reaction -->
  <code><!-- 1..1 CodeableConcept Indicates the specific sign or symptom that was observed (http://apps.who.int/classifications/icd10/browse/2010/en.htm)  --></code>
  <severity value="[code]"/><!-- 0..1 The severity of the sign or symptom -->
 </symptom>
 <exposure>  <!-- 0..* An exposure to a substance that preceded a reaction occurrence -->
  <exposureDate value="[dateTime]"/><!-- 0..1 When the exposure occurred -->
  <exposureType value="[code]"/><!-- 0..1 The type of exposure -->
  <causalityExpectation value="[code]"/><!-- 0..1 A statement of how confident that the recorder was that this exposure caused the reaction -->
  <substance><!-- 0..1 Resource(Substance) Substance(s) that is presumed to have caused the adverse reaction --></substance>
 </exposure>
</AdverseReaction>

Alternate definitions: Schema, RDF (to do), XMI (to do), Resource Profile

3.1.1.1: Terminology Bindings

3.1.2: Notes:

• Vocabulary Bindings
  • The vocabulary bindings are tentative at this point. Further guidance is needed on whether the current bindings are reasonable.
  • ExposureType is currently a code, but if a suitable value set was used, it could (should?) be changed to a CodeableConcept.

3.1.3: Search Parameters

Search Parameters for RESTful searches. The standard parameters also apply. See Searching (§2.1.11) for more information.

(See Searching (§2.1.11)).

3.2: Resource Definition: Alert

Status: prospective warnings of things that should be taken notice of when providing care to the patient

Prospective warnings of things that should be taken notice of when providing care to the patient.

The resource name as it appears in a RESTful URL is /alert/

3.2.1: Resource Content

See also the Examples (§4.5) and the Definitions (§5.7).

<Alert xmlns="http://hl7.org/fhir">
 <category><!-- 0..1 CodeableConcept The category of this alert --></category>
 <status value="[code]"/><!-- 1..1 active | inactive | incorrect -->
 <subject><!-- 1..1 Resource(Patient) Subject of this alert --></subject>
 <author><!-- 0..1 Resource(Practitioner|Patient|Device) Alert creator --></author>
 <note value="[string]"/><!-- 1..1 Text of alert -->
</Alert>

Alternate definitions: Schema, RDF (to do), XMI (to do), Resource Profile

3.2.1.1: Terminology Bindings

3.2.2: Search Parameters

Search Parameters for RESTful searches. The standard parameters also apply. See Searching (§2.1.11) for more information.

(See Searching (§2.1.11)).

3.3: Resource Definition: AllergyIntolerance

Status: Not an approved resource: Draft. Under consideration by the Patient Care work group

Allergy/Intolerance.

The resource name as it appears in a RESTful URL is /allergyintolerance/

Allergy/Intolerance resources are used to provide information about adverse sensitivities to substances that lead to physiologic changes that are clinically observable. An adverse sensitivity is defined as:

A condition expected to result in undesirable physiologic reaction to an amount of a substance that would not produce a reaction in most individuals. The substance is the trigger of an immunologic response that produces the observed physiologic changes, or in some instances nonimmunologic mechanisms that produce clinically identical physiologic changes. The immunologic response might be considered the actual cause of the reaction, but it is exposure to the trigger substance that is clinically observable.

This definition excludes clinically identical episodes that may be caused by physical agents, such as heat, cold, sunlight, or vibration, by exercise activity, or by infectious agents. Those conditions caused by physical agents or infectious would be captured on the problem list. The allergy/intolerance list is a list of conditions that represent a propensity unique to this individual for a reaction upon future exposure to a specified substance.

Note that this specification draws a distinction between the patients problem/condition list and an allergy/intolerance list, even though allergies and intolerances are also conditions. This is because it is a long established clinical workflow, even to patients. Asking an individual "if they have any problems" is not going to invoke an account of their past reactions to medications or foods. Instead, they are asked if they "have any allergies". An allergy/intolerance is also different in that a potential harm from exposure to an external substance that may be ordered by a provider in the course of their care but is not inherent to exposure to that substance for the general population.

Most of the details of the sensitivity can be found in the set of reactions (§3.1) that are associated with the resource, though these may not be present when the patient has not provided enough information. Adverse Reactions (§3.1) do not have to be always associated with an AllergyIntolerance which may appropriate when an single reaction has not provided enough evidence for a meaningful Allergy/Intolerance, or in specific views of events rather than in a general clinical record.

3.3.1: Resource Content

See also the Examples (§4.6) and the Definitions (§5.8).

<AllergyIntolerance xmlns="http://hl7.org/fhir">
 <identifier><!-- 0..1 Identifier An external identifier for the sensitivity --></identifier>
 <criticality value="[code]"/><!-- 0..1 Criticality of the sensitivity -->
 <sensitivityType value="[code]"/><!-- 1..1 Type of the sensitivity -->
 <recordedDate value="[dateTime]"/><!-- 0..1 Date when the sensitivity was recorded -->
 <status value="[code]"/><!-- 1..1 Status of the sensitivity -->
 <subject><!-- 1..1 Resource(Patient) Who the sensitivity is for --></subject>
 <recorder><!-- 0..1 Resource(Practitioner|Patient) Who recorded the sensitivity --></recorder>
 <substance><!-- 1..1 Resource(Substance) The substance that causes the sensitivity --></substance>
 <reactions><!-- 0..* Resource(AdverseReaction) Reactions associated with the sensitivity --></reactions>
 <sensitivityTest><!-- 0..* Resource(Observation) Observations that confirm or refute the sensitivity --></sensitivityTest>
</AllergyIntolerance>

Alternate definitions: Schema, RDF (to do), XMI (to do), Resource Profile

3.3.1.1: Terminology Bindings

3.3.2: Notes:

• Criticality vs Severity

Criticality is defined as "The potential seriousness of a future reaction." This represents a clinical judgment about the worst case scenario for a future reaction. It would be based on the severity of past reactions, the dose and route of exposure that produced past reactions, and the life-threatening or organ system threatening potential of the reaction type. Criticality is an attribute of the allergic condition, not the reaction(s).

High criticality does not equate to a future severe reaction, but rather the potential for a severe and life-threatening reaction. Most reaction types are dose dependent, including anaphylaxis. Therefore, although they have a sensitivity of high criticality, exposure to a small dose of the substance to which they are sensitive might result in only a mild reaction. Severity of the reaction is also dependent on the route of exposure, but criticality since it applies to the condition, is not.

3.3.3: Search Parameters

Search Parameters for RESTful searches. The standard parameters also apply. See Searching (§2.1.11) for more information.

(See Searching (§2.1.11)).

3.4: Resource Definition: CarePlan

Status: Not an approved resource: Draft. Under consideration by the Patient Care work group

Describes the intention of how one or more practitioners intend to deliver care for a particular patient for a period of time, possibly limited to care for a specific condition or set of conditions..

The resource name as it appears in a RESTful URL is /careplan/

Care Plans are used in many of areas of healthcare with a variety of scopes. They can be as simple as a general practitioner keeping track of when their patient is next due for a tetanus immunization through to a detailed plan for an oncology patient covering diet, chemotherapy, radiation, lab work and counselling with detailed timing relationships, pre-conditions and goals.

This resource takes an intermediate approach. It captures basic details about who is involved and what actions are intended without dealing in discrete data about dependencies and timing relationships. These can be supported where necessary using the extension mechanisms.

Comments are welcome about the appropriateness of the proposed level of granularity, whether it's too much detail for what most systems need, or not sufficient for common essential use cases.

3.4.1: Resource Content

See also the Examples (§4.7) and the Definitions (§5.9).

<CarePlan xmlns="http://hl7.org/fhir">
 <identifier><!-- 0..1 Identifier ID for plan --></identifier>
 <patient><!-- 1..1 Resource(Patient) Who care plan is for --></patient>
 <status value="[code]"/><!-- 1..1 planned | active | ended -->
 <period><!-- 0..1 Period Time period plan covers --></period>
 <modified value="[dateTime]"/><!-- 0..1 When last updated -->
 <concern><!-- 0..* Resource(Problem) Health issues plan addresses --></concern>
 <participant>  <!-- 0..* Who's involved in plan? -->
  <role><!-- 0..1 CodeableConcept Type of involvement --></role>
  <member><!-- 1..1 Resource(Practitioner|RelatedPerson|Patient|Organization) Who is involved --></member>
 </participant>
 <goal>  <!-- 0..* Desired outcome of plan -->
  <description value="[string]"/><!-- 1..1 What's the desired outcome? -->
  <status value="[code]"/><!-- 0..1 in progress|achieved|sustaining | abandoned -->
  <notes value="[string]"/><!-- 0..1 Comments about the goal -->
 </goal>
 <activity>  <!-- 0..* Action to occur as part of plan -->
  <category value="[code]"/><!-- 1..1 visit | procedure | observation | + -->
  <code><!-- 0..1 CodeableConcept Detail type of activity --></code>
  <status value="[code]"/><!-- 0..1 not started | ongoing | suspended | completed | abandoned -->
  <prohibited value="[boolean]"/><!-- 1..1 Do NOT do -->
  <timing[x]><!-- 0..1 Schedule|Period|string When activity is to occur --></timing[x]>
  <location><!-- 0..1 Resource(Location) Where it should happen --></location>
  <performer><!-- 0..* Resource(Practitioner|Organization|RelatedPerson|Patient) Who's responsible? --></performer>
  <product><!-- 0..1 Resource(Medication|Substance) What's administered/supplied --></product>
  <dailyAmount><!-- 0..1 Quantity How much consumed/day? --></dailyAmount>
  <quantity><!-- 0..1 Quantity How much is administered/supplied/consumed --></quantity>
  <details value="[string]"/><!-- 0..1 Extra info on activity occurrence -->
  <actionTaken><!-- 0..* Resource(Any) Appointments, orders, etc. --></actionTaken>
  <notes value="[string]"/><!-- 0..1 Comments about the activity -->
 </activity>
 <notes value="[string]"/><!-- 0..1 Comments about the plan -->
</CarePlan>

Alternate definitions: Schema, RDF (to do), XMI (to do), Resource Profile

3.4.1.1: Terminology Bindings

3.4.1.2: Constraints

• Quantity can only be specified if activity category is supply (xpath on /activity: (f:category/@value=('supply')) = exists(f:quantity))
• DailyDose can only be specified if activity category is drug or food (xpath on /activity: (f:category/@value=('drug','food')) = exists(f:dailyAmount))

3.4.2: Open Issues

• This resource combines the concepts of "Care Plan" and "Care Team" into a single resource. Is this appropriate?
• This specification leaves the specific relationship between activites in the care plan to textual description. Is more rigor required within the 80%?

3.4.3: Search Parameters

Search Parameters for RESTful searches. The standard parameters also apply. See Searching (§2.1.11) for more information.

(See Searching (§2.1.11)).

3.5: Resource Definition: Conformance

Status: Approved infrastructure resource. Draft for comment

A conformance statement about how an application or implementation supports FHIR or the set of requirements for a desired implementation.

The resource name as it appears in a RESTful URL is /conformance/

Conformance Statements provide for a degree of automatic configuration and adaptation. However, capturing absolutely every variation that could impact the interoperability of two systems, let alone keeping that detailed information up-to-date as systems evolve through maintenance and upgrades is rarely practical. Therefore, conformance statements should be seen as an interim step. They provide a degree of automation. However, they also provide a great deal of human-readable content that can minimize the need for direct communication between the operators of the systems being configured to interoperate.

Conformance statements are used in one of three ways:

3.5.1: Describe an actual implementation

In this scenario, the conformance statement describes the capabilities of a deployed and configured solution available at a particular access point or set of access points. The statement describes exactly how to interface with that deployed solution and thus provides for a degree of self-configuration of software solutions.

This is the type of profile that FHIR restful solutions are expected to make available on invocation of the conformance operation. It is also the type of statement that forms a basis for the testing, certification or commissioning of specific software installations.

A conformance statement is identified as being an implementation statement through the presence of the implementation element.

3.5.2: Describe software solution capabilities

In this scenario, the conformance statement describes the generic capabilities of a software application or component solution. The solution might be available for purchase or other acquisition and might be deployed and configured at any number of independent sites. Because it is not dependent on any particular implementation, the profile cannot provide specific details such as endpoint addresses. It may also need to document various configurations in which the application can be set up or describe the degree of customizability associated with the solution.

This type of statement may be used as a marketing tool by software and system developers to formally describe their capabilities. It can also be used as the basis for conformance testing of software solutions independent of a particular installation.

A conformance statement is identified as being a software solution statement through the presence of the software element.

3.5.3: Describe a desired solution

In this scenario, the conformance statement describes the capabilities of a desired system. It might be used as part of an architectural design process to document needed system capabilities, or might be used as part of an RFP process to formally document the requirements of a requested solution and to document the criteria by which proposals will be evaluated.

A conformance statement is identified as being a requirements statement through the presence of the proposal element.

These three types of profiles can be used together. A requirements statement can be compared against the solution statements proffered by respondents to an RFP. A solution statement for a software package forms the starting point for the implementation statement associated with a particular installation of that software package.

3.5.4: Resource Content

See also the Examples (§4.8) and the Definitions (§5.10).

<Conformance xmlns="http://hl7.org/fhir">
 <identifier value="[string]"/><!-- 0..1 Logical id to reference this statement -->
 <version value="[string]"/><!-- 0..1 Logical id for this version of the statement -->
 <date value="[dateTime]"/><!-- 1..1 Publication Date -->
 <publisher value="[string]"/><!-- 1..1 Publishing Organization -->
 <telecom><!-- 0..* Contact Contacts for Organization --></telecom>
 <software>  <!-- 0..1 Software that is covered by this conformance statement -->
  <name value="[string]"/><!-- 1..1 Name software is known by -->
  <version value="[string]"/><!-- 0..1 Version covered by this statement -->
  <releaseDate value="[dateTime]"/><!-- 0..1 Date this version released -->
 </software>
 <implementation>  <!-- 0..1 If this describes a specific instance -->
  <description value="[string]"/><!-- 1..1 Describes this specific instance -->
  <url value="[uri]"/><!-- 0..1 Base URL for the installation -->
  <software><!-- 0..1 Content as for Conformance.software The software running this instance --></software>
 </implementation>
 <proposal>  <!-- 0..1 If profile is for proposal -->
  <description value="[string]"/><!-- 1..1 Details of proposal or requirements document -->
 </proposal>
 <fhirVersion value="[id]"/><!-- 1..1 FHIR Version -->
 <acceptUnknown value="[boolean]"/><!-- 1..1 True if application accepts unknown elements -->
 <format value="[code]"/><!-- 1..* formats supported (xml | json | mime type) (http://www.rfc-editor.org/bcp/bcp13.txt.htm)  -->
 <rest>  <!-- 0..* If the endpoint is a RESTful one -->
  <mode value="[code]"/><!-- 1..1 client | server -->
  <documentation value="[string]"/><!-- 0..1 General description of implementation -->
  <security>  <!-- 0..1 Information about security of implementation -->
   <service><!-- 0..* CodeableConcept What type of security services are supported/required --></service>
   <description value="[string]"/><!-- 0..1 General description of how security works -->
   <certificate>  <!-- 0..* Certificates associated with security profiles -->
    <type value="[code]"/><!-- 0..1 Mime type for certificate (http://www.rfc-editor.org/bcp/bcp13.txt.htm)  -->
    <blob value="[base64Binary]"/><!-- 0..1 Actual certificate -->
   </certificate>
  </security>
  <resource>  <!-- 1..* Resource served on the REST interface -->
   <type value="[code]"/><!-- 1..1 Resource type -->
   <profile><!-- 0..1 Resource(Profile) Resource Profiles supported --></profile>
   <operation>  <!-- 1..* What operations are supported? -->
    <code value="[code]"/><!-- 1..1 read | vread | update | etc. -->
    <documentation value="[string]"/><!-- 0..1 Anything special about operation behavior -->
   </operation>
   <readHistory value="[boolean]"/><!-- 0..1 Whether vRead can return past versions -->
   <searchInclude value="[string]"/><!-- 0..* _include values supported by the server -->
   <searchParam>  <!-- 0..* Additional search params defined -->
    <name value="[string]"/><!-- 1..1 Name of search parameter -->
    <source value="[uri]"/><!-- 0..1 Source of definition -->
    <type value="[code]"/><!-- 1..1 Type of search parameter -->
    <documentation value="[string]"/><!-- 1..1 Contents and meaning of search parameter -->
    <target value="[code]"/><!-- 0..* Types of resource (if a resource reference) -->
    <chain value="[string]"/><!-- 0..* Chained names supported -->
   </searchParam>
  </resource>
  <batch value="[boolean]"/><!-- 0..1 If batches are supported -->
  <history value="[boolean]"/><!-- 0..1 If a system wide history list is supported -->
 </rest>
 <messaging>  <!-- 0..* If messaging is supported -->
  <endpoint value="[uri]"/><!-- 0..1 Actual endpoint being described -->
  <reliableCache value="[integer]"/><!-- 0..1 Reliable Message Cache Length -->
  <documentation value="[string]"/><!-- 0..1 Messaging interface behavior details -->
  <event>  <!-- 1..* Declare support for this event -->
   <code value="[code]"/><!-- 1..1 Event type -->
   <mode value="[code]"/><!-- 1..1 sender | receiver -->
   <protocol><!-- 0..* Coding http | ftp |MLLP | etc. --></protocol>
   <focus value="[code]"/><!-- 1..1 Resource that's focus of message -->
   <request value="[uri]"/><!-- 1..1 Profile that describes the request -->
   <response value="[uri]"/><!-- 1..1 Profile that describes the response -->
   <documentation value="[string]"/><!-- 0..1 Endpoint-specific event documentation -->
  </event>
 </messaging>
 <document>  <!-- 0..* Document definition -->
  <mode value="[code]"/><!-- 1..1 producer | consumer -->
  <documentation value="[string]"/><!-- 0..1 Description of document support -->
  <profile value="[uri]"/><!-- 1..1 Constraint on a resource used in the document -->
 </document>
</Conformance>

Alternate definitions: Schema, RDF (to do), XMI (to do), Resource Profile

3.5.4.1: Terminology Bindings

3.5.4.2: Constraints

• Must have only one of software, implementation and proposal (xpath: count(f:software | f:implementation | f:proposal) = 1)
• A Conformance profile must have at least one of rest, messaging or document (xpath: exists(f:rest) or exists(f:messaging) or exists(f:document))
• Messaging end point is required (and is only permitted) when statement is for an implementation (xpath on /messaging: exists(f:endpoint) = exists(parent::f:Conformance/f:implementation))

3.5.5: Notes:

• This conformance resource provides for an application to describe its use of the RESTful paradigm messaging events, or FHIR documents. Usually, an application would only describe one, but more than one may be described
• RESTful conformance rules:
  • RESTful servers are required to provide this resource on demand (§2.1.13). Servers SHALL specify what resource types and operations are supported, and SHOULD also specify profiles for each resource type.
  • RESTful clients SHOULD publish a conformance statement
  • The search parameters that a server supports (or a client makes use of) are specified in the resource profile that the conformance statement references
  • Resource Types or operations that are not listed are not supported
• Messaging conformance rules:
  • The interpretation of request and response depends on the mode. If the mode is sender, then request specifies what the application sends, and response specifies what it accepts. If the mode is "receiver", then this is reversed
  • If a request or response is not specified for an event, then no rules are made for it
  • Events that are not listed are not supported
• Document conformance rules:
  • Document Profiles should directly constrain the Document.information.class & type elements so so that there is no ambiguity concerning which profile any given document conforms to
• Other service based use of resources: Due to the variability of these services, the Conformance resource does not attempt to describe service based use of resources. The various service specifications will need to describe this usage in their own way

3.5.6: Search Parameters

Search Parameters for RESTful searches. The standard parameters also apply. See Searching (§2.1.11) for more information.

(See Searching (§2.1.11)).

3.6: Resource Definition: Coverage

Status: Not an approved resource: Draft. Under consideration by the Financial Management work group

Financial instrument by which payment information for health care.

The resource name as it appears in a RESTful URL is /coverage/

3.6.1: Resource Content

See also the Examples (§4.9) and the Definitions (§5.11).

<Coverage xmlns="http://hl7.org/fhir">
 <issuer><!-- 0..1 Resource(Organization) An identifier for the plan issuer --></issuer>
 <period><!-- 0..1 Period Coverage start and end dates --></period>
 <type><!-- 1..1 Coding Type of coverage --></type>
 <identifier><!-- 0..1 Identifier The primary coverage ID --></identifier>
 <group><!-- 0..1 Identifier An identifier for the group --></group>
 <plan><!-- 0..1 Identifier An identifier for the plan --></plan>
 <subplan><!-- 0..1 Identifier An identifier for the subsection of the plan --></subplan>
 <dependent value="[integer]"/><!-- 0..1 The dependent number -->
 <sequence value="[integer]"/><!-- 0..1 The plan instance or sequence counter -->
 <subscriber>  <!-- 0..1 Planholder information -->
  <name><!-- 0..1 HumanName PolicyHolder name --></name>
  <address><!-- 0..1 Address PolicyHolder address --></address>
  <birthdate value="[date]"/><!-- 0..1 PolicyHolder date of birth -->
 </subscriber>
</Coverage>

Alternate definitions: Schema, RDF (to do), XMI (to do), Resource Profile

3.6.1.1: Terminology Bindings

3.6.2: Search Parameters

Search Parameters for RESTful searches. The standard parameters also apply. See Searching (§2.1.11) for more information.

(See Searching (§2.1.11)).

3.7: Resource Definition: Device

Status: Not an approved resource: examplar. Possible owners: Devices and Patient Administration Working Group

This resource identifies an instance of a manufactured thing that is used in the provision of healthcare without being substantially changed through that activity. The device may be a machine, an insert, a computer, an application, etc. This includes durable (reusable) medical equipment as well as disposable equipment used for diagnostic, treatment, and research for healthcare and public health..

The resource name as it appears in a RESTful URL is /device/

Primarily used for recording which device performed an action and can also be used to track device location

There are 4 device related resources

• Device (this resource) - an administrative resource that tracks individual devices and their location. Primarily used for attribution of actions to devices
• Device Capabilities (§3.8) - Defines what observations a device will provide when another device connects to it
• Device Log (§3.9) - A raw report from a device at a point in time. Must be paired with the correct Device Capabilities resource in order to be processed
• Device Observation (§3.10) - A report of observations from a device

The device capabilities and log resources are used when communicating with a device, either directly or indirectly. When a channel is opened with the device, or it's proxy, it first sends the Capabilities resource, and then a series of log resources. The FHIR JSON format is used in this case.

The application that receives the log resources may choose to merge the log with the capabilities statement to create a device observation, which is suitable for wider use within a EHR/Clinical record context.

3.7.1: Resource Content

See also the Examples (§4.10) and the Definitions (§5.12).

<Device xmlns="http://hl7.org/fhir">
 <type><!-- 1..1 CodeableConcept What kind of device this is --></type>
 <manufacturer value="[string]"/><!-- 0..1 Name of device manufacturer -->
 <model value="[string]"/><!-- 0..1 Model id assigned by the manufacturer -->
 <version value="[string]"/><!-- 0..1 Version number (i.e. software) -->
 <identity>  <!-- 0..1 Universal Device Id fields -->
  <gtin value="[string]"/><!-- 0..1 GTIN assigned to this device -->
  <lot value="[string]"/><!-- 0..1 Lot number of manufacture -->
  <serialNumber value="[string]"/><!-- 1..1 Serial number assigned by the manufacturer -->
  <expiry value="[date]"/><!-- 0..1 Date of expiry of this device (if applicable) -->
 </identity>
 <owner><!-- 0..1 Resource(Organization) Organization responsible for device --></owner>
 <assignedId><!-- 0..* Identifier Identifier assigned by various organizations --></assignedId>
 <location><!-- 0..1 Resource(Location) Where the resource is found --></location>
 <patient><!-- 0..1 Resource(Patient) If the resource is affixed to a person --></patient>
 <contact><!-- 0..* Contact Details for human/organization for support --></contact>
 <url value="[uri]"/><!-- 0..1 Network address to contact device -->
</Device>

Alternate definitions: Schema, RDF (to do), XMI (to do), Resource Profile

3.7.1.1: Terminology Bindings

3.7.2: Search Parameters

Search Parameters for RESTful searches. The standard parameters also apply. See Searching (§2.1.11) for more information.

(See Searching (§2.1.11)).

3.8: Resource Definition: DeviceCapabilities

Status: Under Development with the Devices Work Group

Describes the set of data produced by a device.

The resource name as it appears in a RESTful URL is /devicecapabilities/

There are 4 device related resources

• Device (§3.7) - An administrative resource that tracks individual devices and their location. Primarily used for attribution of actions to devices
• Device Capabilities (this resource) - Defines what observations a device will provide when another device connects to it
• Device Log (§3.9) - A raw report from a device at a point in time. Must be paired with the correct Device Capabilities resource in order to be processed
• Device Observation (§3.10) - A report of observations from a device

The device capabilities and log resources are used when communicating with a device, either directly or indirectly. When a channel is opened with the device, or it's proxy, it first sends the Capabilities resource, and then a series of log resources. The FHIR JSON format is used in this case. (TODO: What's the communication protocol?) The application that receives the log resources may choose to merge the log with the capabilities statement to create a device observation, which is suitable for wider use within a EHR/Clinical record context. The Device Capabilites and Device Log resources may be used in a RESTful context, but in many contexts this will not be very useful - the data should be converted to a device observation for normal RESTful use in a patient care context.

Note that this resource is entirely concerned with devices that report data; interacting with and controlling devices such as infusion pumps etc is not in scope for this resource (no solution for this yet). This resource is based on ISO 11073.

3.8.0.1: Structure of the Device Capabilities

A medical device is conceived of as a measuring device that is capable of reporting a series of groups of measurements on a regular basis. The device capabilities resource describes the kind of data that a medical device reports. Devices are conceptualised using the following main structure:

1. Device - The actual device that external systems communicate with
2. Virtual Medical Device - A medical-related subsystem of a medical device. The virtual device that may be part of the containing device, or a separate device that may be communicating with it
3. Channel - Groups together physiological measurement data and derived data
4. Metrics - A piece of measured or derived data that will be reported by the machine
5. Facets - Additional data that qualifies the metric, or contributes to it's assessment

Very simple devices may have only a single compartment with a single channel and one metric, while complex devices may have multiple items at every level.

When the data emitted by the device (§3.9) is converted to a Device Observation (§3.10) based on the information in the capabilities, and known local context, the Metrics level usually corresponds to a single Observation (§3.26), but this is not appropriate in all cases.

3.8.1: Resource Content

See also the Examples (§4.11) and the Definitions (§5.13).

<DeviceCapabilities xmlns="http://hl7.org/fhir">
 <name value="[string]"/><!-- 0..1 The name of this device -->
 <type><!-- 0..1 CodeableConcept The type of device --></type>
 <manufacturer value="[string]"/><!-- 0..1 Company that built the device -->
 <identity><!-- 0..1 Resource(Device) Identifies this particular device uniquely --></identity>
 <virtualDevice>  <!-- 0..* A medical-related subsystem of a medical device -->
  <code><!-- 0..1 CodeableConcept Describes the compartment --></code>
  <channel>  <!-- 0..* Groups related data items -->
   <code><!-- 0..1 CodeableConcept Describes the channel --></code>
   <metric>  <!-- 0..* Piece of data reported by device -->
    <code><!-- 1..1 CodeableConcept Describes the metrics --></code>
    <key value="[string]"/><!-- 1..1 Used to link to data in device log -->
    <info>  <!-- 1..1 How to interpret this metric value -->
     <type value="[code]"/><!-- 1..1 Quantity | Coding | Array | string -->
     <units value="[string]"/><!-- 0..1 Human Readable units of data value -->
     <ucum value="[code]"/><!-- 0..1 UCUM units for data value (http://unitsofmeasure.org.htm)  -->
     <array><!-- 0..1 Array Array template (fixed values) --></array>
     <system value="[uri]"/><!-- 0..1 System for coding -->
    </info>
    <facet>  <!-- 0..* Additional clarifying or qualifiying data -->
     <code><!-- 1..1 CodeableConcept Describes the facet (http://loinc.org.htm)  --></code>
     <scale value="[decimal]"/><!-- 0..1 Factor to apply to raw values (default = 1) -->
     <key value="[string]"/><!-- 1..1 Used to link to data in device log -->
     <info><!-- 1..1 Content as for DeviceCapabilities.virtualDevice.channel.metric.info How to interpret this facet value --></info>
    </facet>
   </metric>
  </channel>
 </virtualDevice>
</DeviceCapabilities>