1.0: Welcome to FHIR

Fast Healthcare Interoperability Resources (FHIR) defines a set of "resources" for health. These resources represent granular clinical concepts that can be exchanged in order to quickly and effectively solve 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 participants 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.

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.1: Overview

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

• Granular - they are the smallest unit of operation and a transaction scope of their own
• Independent - the content of a resource can be understood without reference to other resources
• Simple - each resource is easy to understand and implement without needing 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 other contexts, such as messaging or SOA architectures, and moved in and out of RESTful paradigms as convenient
• Extensible - resources can be extended to cater for local requirements without impacting on interoperability
• Web Enabled - where possible or 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 (§1.0): Overall introduction, useful links and the FHIR license
• This roadmap
• Resource Formats (§1.2): An explanation of the general content and format of all resources and how they are described
• Data Types (§1.3): Common re-usable patterns encountered throughout healthcare data and used in the resources
• Using Codes (§1.4): Explains how the use of codes (code systems, terminologies, classifications, ontologies) is managed in FHIR
• Extensibility (§1.5): Describes the extension section of the resource and specifies the rules that apply to its use
• Resource Profiles (§1.6): Describes how resources are profiled to describe their use in a particular context

1.1.1.2: Implementation

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

• Implementation (§2.6): General requirements for using resources and various useful things including schema packs and reference implementations
• REST (HTTP) (§2.1): Defines a lightweight HTTP based paradigm for using resources
• Messaging (§2.2): A simple request/response message based transactional framework (equivalent to HL7 v2)
• Documents (§2.3): 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)
• hData Integration (§2.4): An explanation of how to use resources in a the context of an hData RESTful service
• Atom Feeds: Atom feeds are used to gather a set of resources into a single XML document when they are transferred as a group - these are called "bundles"
• Value Set (§2.6): A resource that describes a set of codes - used in association with profiles to specify resource contents and potentially usable in other contexts
• Conformance (§2.7): A resource that describes how an application does, can, or should use FHIR resources

1.1.1.3: Resources

The resources section enumerates the resources:

• Resources (§3.7): An index of the defined resources
• etc.: 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?)

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

1.2: Resource Format

In this specification, resources are described in a simple XML format. This page documents how the XML content for resources is described and controlled. The XML may be validated by schema and schemas are provided, but validation is not required in operational systems (though the XML must always be valid against this specification). 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.2.1: XML Content Models

To provide a visual sense of what the end resource instances will look like, all resources include documentation of their allowed content in a pseudo-XML syntax that uses the following notation:

 <name xmlns="http://hl7.org/fhir" [xml:lang]> 
   <nameA><!-- 1..1 type description of content  --><nameA>
   <nameB d?><!-- 0..1 type description  --></nameB>
   <nameC> <!--  1..* -->
     <nameD  d?><!-- 1..1 type>Relevant records  --></nameD>
   </nameC>
 <name>

Notes:

• The XML character set is always unicode. Specifying the character encoding is optional but recommended. Any encoding that is round trip compatible with unicode is allowed.
.
• 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 introduced into the resource content model. XHTML is found in every resource - see below.
• To build a valid resource, simply replace the contents of the elements with valid content as described by the cardinality, type rules and content description found in the comment in each 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.
• Some elements are marked with a d?, which indicates that they are able to carry the "dataAbsentReason" attribute. See below for further discussion (§1.2.3).
• The elements are assigned one or more types. All of the types are defined in the data types (§1.3) except for "Resource" and "Narrative" that are documented below. The type names are hyperlinked.
• In the Resource definitions, each element name 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 and/or understand it.
• Any of the XML elements may have an id attribute to serve as the target of an internal reference (§1.2.5). The id attribute is not shown.
• The root element of a resource may have an xml:lang the specifies the primary language of the resource.
• In addition to this description, other definitional forms are available, including W3C schema, Schematron, (Todo: Relax NG schema, RDF and eCore).

<[Name] xmlns="http://hl7.org/fhir">
 <id><!-- 0..1 id Master Resource Id, always first in all resources --></id>
 <extension><!-- 0..*  Extension   See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of [x], for human interpretation --></text>
</[Name]>

The id element is always mandatory except in the case that a resource is posted to a server to create it, and the id of the resource is not yet known. In this case, the id element is absent. The use of the id element is discussed further below (§1.2.6). The use of the extensions element is discussed under "Extensibility" (§1.5). The text ("Narrative") is discussed below (§1.2.4). In addition to these data elements, there are several pieces of metadata about a resource that are not part of the resource content, but are delegated to the infrastructure:

In any environment where the resources are used, the technical details of how these metadata elements are represents will need to be resolved. For further details, see Implementation Details (§2.6).

 <x dataAbsentReason=""/>

• Using "masked" may be a breach of security or confidentiality. However, there are times when it's use is required to support alternate workflows for gaining access to denied information.
• If the dataAbsentReason attribute is present, the element may still have additional content from its normally defined content. Usually this is where the contained elements define what data is missing (for instance, that a home phone number (§1.3.17) is unknown).
• Systems are not required to process any provided data when a dataAbsentReason is present, but may choose to do so.
• The dataAbsentReason attribute is never used inside the data types, nor can it be used in the text portion of a resource, nor inside an extension block (with the exception of the value of the extension)

In addition to this general flag that specifies the status of the narrative, there is an optional mapping between the narrative and the structured data. Each mapping has narrative id and structured data id which provide internal references (§1.2.5) to the narrative and the structured data respectively, and a flag for whether the text was generated from the data, or the data was generated from the text (by some form of retrospective processing, whether human or computer), or whether both come from an external source. The structured data target may be an empty element with a dataAbsentReason of "astext"; this means that the value of the text could not be properly represented in the data type. Any element defined as part of the resource content, or any repeating element inside a data type may carry an id attribute to serve as the target of a narrative mapping.

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

<x xmlns="http://hl7.org/fhir">
 <status><!-- 1..1 code generated | extensions | additional --></status>
 <div xmlns="http://www.w3.org/1999/xhtml"> <!-- Limited xhtml content< --> </div>
 <image>  <!-- 0..* Images referenced in xhtml -->
  <mimeType><!-- 1..1 code Mime type of image --></mimeType>
  <content><!-- 1..1 base64Binary base64 image data --></content>
 </image>
 <map>  <!-- 0..* -->
  <text><!-- 1..1 idref Narrative source (by id attribute) --></text>
  <data><!-- 1..1 idref Data source (by id attribute) --></data>
  <source><!-- 1..1 code text | data --></source>
 </map>
</x>

Terminology Bindings

• Narrative.status has the definition NarrativeStatus: "The status of a resource narrative". Possible values:

  generated	The contents of the narrative are entirely generated from the structured data in the resource.
  extensions	The contents of the narrative are entirely generated from the structured data in the resource and some of the content is generated from extensions
  additional	The contents of the narrative contain additional information not found in the structured data

• Narrative.image.mimeType has the definition MediaType: "The mime type of an attachment". For example values, see BCP 13 (RFCs 2045, 2046, 2047, 4288, 4289 and 2049) (http://www.rfc-editor.org/bcp/bcp13.txt)
• Narrative.map.source has the definition NarrativeMapSource: "Which is the source in a Narrative <-> Data mapping". Possible values:

  text	The text is the original data
  data	The data is the original data

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.

  <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 image source may be a local reference within the resource:

  <img src="#a5"/>

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

  <narrative>
    <html xmlns="http://www.w3.org/1999/xhtml">
      <p>
        <img src="#a1/>.
      </p>
    </html>
    <image id="a1">
      <mimeType>image/png</mimeType>
      <data>MEKH....SD/Z</data>
    </image>
  <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.

The dataAbsentReason is not used on the narrative element or any elements contained in it. The xhtml element must have some non-whitespace content.

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

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.3.4.1).

• In the XHTML/data mapping above
• From an extension element (§1.5.1) to its target element
• Inside a CodeableConcept data type to identify the primary encoding (§1.3.7)
• On an img src reference in the narrative

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 has no content (text or children elements) and just a single attribute named "idref". The value of the idref attribute must match the value of an id attribute in the same resource (or, for a CodeableConcept, inside the same datatype).

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

In a single resource, this works exactly 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, duplicate values may occur between resources. This must be managed by applications reading the resources.

<x xmlns="http://hl7.org/fhir">
 <type><!-- 0..1 code Resource Type --></type>
 <id><!-- 0..1 uri URL/Id of the reference --></id>
 <version><!-- 0..1 uri Specific version URL/Id of resource referenced --></version>
 <text><!-- 0..1 string Text alternative for the resource --></text>
</x>

Terminology Bindings

• ResourceReference.type has the definition of any defined Resource Type name (§1.4.5)

Whether or not the type of the resource reference is fixed for a particular element, the reference includes the resource type.

Both the id and the version are URL based references - they must be literal URLs that resolve to the location of the resource. Both URLs may be relative URLS, in which case they are interpreted to contain the logical id and versionId respectively of the resource in question, and the resolution of the logical reference is a matter of implementation logic. 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 between separated eco-systems. Absolute URLs do not need to point to a FHIR RESTful server (§2.1), though this is the preferred approach.

A resource reference may contain either a version independent reference ("id") or a version dependent reference ("version") or both. If both are provided, it is at the descretion of the processor of the data which to use in a particular context. If relative references are used, a version cannot be provided without an id, since the version may be scoped by the id.

  <context>
    <type>Patient</type>
    <id>034AB16</id>
  <context>

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

The logical id and version id of a Resource can take one of the following forms:

Resource ids must be represented in lowercase. Ids are always opaque, and systems should not and need 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. Note that absolute URLs that do not point to FHIR RESTful servers do not need to include the id in the URL, though this is good practice. If the id is in the URL, it must be present in lower case. Irrespective of whether the URL points to a FHIR RESTful server or includes the logical id in the URL, URLs are always considered to be case-sensitive and lowercase is preferred.

Plain text narrative may be provided that describes the resource in addition to the resource reference (or in place of, if a dataAbsentReason is allowed).

  <id>
    <type>Organisation</type>
    <id>1234</id>
    <text>HL7, Inc</text>
  <id>

1.2.7: Inter-version Compatibility

There is no explicit version marker in the XML. Subsequent versions of this specification may introduce new elements at any point in the content models, but the path and meaning of existing data elements will not be changed. Given that, in a typical scenario, mixed versions may need to exist, applications SHOULD ignore elements that they do not recognize unless those elements are marked with a "must understand" attribute. However, in a healthcare context, many application vendors are unwilling to consider this approach because of concerns about clinical risk. Applications are not required to ignore unknown elements, but must declare whether they will do so in their conformance statements using the acceptUnknown element.

1.2.8: 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.

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, though there is no requirement to validate instances against either, 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.

• 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 value representations for primitive types (§1.3.1) such as string, decimal, etc. are identical between the XML and the JSON 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.
• JSON does not have a notion of attributes versus elements, so FHIR's only attributes (dataAbsentReason and id) 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

These differences - particularly the repeating element one, which cannot be avoided - ensure that generic XML --> JSON converters are not able to perform correctly. The reference platforms will provide XML <--> JSON conversion functionality.

1.2.10.1: JSON representation of primitive types

FHIR elements with primitive values are represented as JSON object members of the same name, with their value encoded as a string. Native JSON types other than "string" are never used to guarantee equivalence of the serialized representation between XML and JSON.

Primitive elements used inside the FHIR datatypes cannot have an 'id' or 'dataAbsentReason' attribute, so they are rendered in JSON as a property and value:

 <date>1972-11-30</date>

is represented in JSON as

"date": "1972-11-30"

Primitive elements inside resources can have 'id' or (if allowed) 'dataAbsentReason' attributes, so their JSON representation uses a JSON object with members '_id', 'dataAbsentReason' and 'value', which contains the actual primitive value as string. Note that in most cases, the primitive will not have a value when there is a dataAbsentReason present, in which case the special 'value' member must not be present. So,

 <dob id='314159'>1972-11-30</dob>

is represented in JSON as:

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

while this example would look like this in the case of a dataAbsentReason:

"dob": { "_id": "314159", "dataAbsentReason": "Unknown" }

1.2.10.2: Repeating elements

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

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

is represented in JSON like so:

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

1.2.10.3: JSON representation of composite datatypes

Resources and other composite 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's and dataAbsentReasons, therefore these attributes get converted to JSON members values, in the same manner as described for primitives. These members will be placed before all other members. For example:

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

is represented in JSON as:

{
  "Person" : {
    "id" : { "value" : "34234" },
    "name" : [{
      "use" : "official",
      "part" : [
        {
          "type" : "given",
          "value" : "Karen" 
        },
        {
           "_id" : "n1",
           "type" : "family",
           "value" : "van"
        }]
     }],
    "dob" : { "dataAbsentReason" : "notasked" },
    "language" : [
      {
        "code" : { "_id" : "lang-1", "value" : "dut" },
        "use" : { "value" : "fluent" }
      },
      {
        "code" : { "value" : "cmn" },
        "use" : { "value" : "useable" }
      }],
    "text" : {
      "status" : "generated",
      "div" : "<div xmlns='http://www.w3.org/1999/xhtml'>...</div>"
    }
}

Things to note here are:

• 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 'code' within member 'language' is a part of the resource definition and therefore serialized as a JSON object, whereas the member 'use' within 'name' is a primitive inside a datatype and therefore serialized as a JSON string value.
• The XHTML content in the 'div' element which in the Narrative element 'text' is represented as an escaped string in JSON. The xhtml's root element needs to be a <div> in the xhtml namespace.

1.2.11: UML Models and dataAbsentReason

This specification describes the use of the dataAbsentReason attribute, which is used throughout the content models on elements of any type to indicate missing data. The dataAbsentReason attribute "may appear on any element in a resource other than those marked mandatory".

In Object-Orientated paradigms, the dataAbsentReason is a mixin. The definition of a mix-in (http://en.wikipedia.org/wiki/Mixin#) is that it is an abstract class that provides functionality that is not inherited by specialization but rather by collecting functionality. A mixin can be thought of as a generic class that specializes its parameter class:

This shows a mixin called "DataQualityAspect" which expresses the attribute "dataAbsentReason". The two derived classes, DataQualityAspectQuantity which inherits both Quantity and DataQualityAspect and DataQualityAspect(Quantity), which binds Quantity to the parameter T on the DataQualityAspect mixin both have the same semantics (are identical other than their type derivation).

The problem with this approach is that not only is the <<mixin>> stereotype not a recognised standard UML syntax, but most mainstream programming languages cannot implement multiple inheritance in this form. There are two alternative approaches for implementing mixins in object-oriented platforms. The first is using a wrapper class:

The problem with this variation is that Quantity and DataQualityAspect(Quantity) are no longer both types of Quantity, as with a pure mixin and this will have a series of effects on implementations. The other alternative is simply to make DataQualityAspect a base class:

This is the simplest approach, but has the disadvantage that all instances of the Quantity data type carry the dataAbsentReason attribute, whether it is appropriate or not.

Implementers that use these objects in an environment where mixins are not supported must choose one of these two approaches. For simplicity, the object models defined in this specification simply bind the target type directly to the specified data type, and ignore the issue of the dataAbsentReason mixin.

Note that the dataAbsentReason may also be associated with primitive types as well so use of one of these mixin mechanisms will be required there as well.

1.3: Data Types

The FHIR data types include primitive types imported from XML schema and additional data types that capture patterns that are ubiquitous throughout the scope of the healthcare data that will be exchanged.

The data types defined on this page on this page are categorised as "Primitive Types", "Types" or "Structures". Primitive Types are those either drawn from W3C Schema types or directly derived from them. Types and Structures are more complex, made up of multiple properties. "Structures" are higher level concepts that some systems internally treat differently from Types. There is no functional difference between the two categories, and systems are not required to treat them any differently.

The following table summarises the primitive types that are used by are used in the exchange specifications and are directly imported from w3c schema (though sometimes aliased). The possible values for these types are those specified in the W3C Schema specification part 2. All elements that contain text content have one of these primitive types. Elements of this type can only be empty if they have a dataAbsentReason (§1.2.3) attribute on them (and only where that attribute is allowed).

The default value specifies the implicit semantic meaning of a missing element. Note that some implementations are able to distinguish between missing values and the default values, but the semantic meaning is still required anyway. The string patterns that follow share the same default value as the string type, and all the rest of the types have a default value of null.

Implementations that convert the xml described in this specification to other formats such as JSON or some object based notation will have to find equivalent types.

  <x>1951-06-04</x>

<x xmlns="http://hl7.org/fhir">
 <mimeType><!-- 1..1 code Mime type of the content --></mimeType>
 <data><!-- 0..1 base64Binary Data inline, base64ed --></data>
 <url><!-- 0..1 uri Uri where the data can be found --></url>
 <hash><!-- 0..1 base64Binary sha-256 hash of the data (base64 ) --></hash>
 <lang><!-- 0..1 code ISO 639-3 language code --></lang>
 <title><!-- 0..1 string Label to display in place of the data --></title>
</x>

Terminology Bindings

• Attachment.mimeType has the definition MediaType: "The mime type of an attachment". For example values, see BCP 13 (RFCs 2045, 2046, 2047, 4288, 4289 and 2049) (http://www.rfc-editor.org/bcp/bcp13.txt)
• Attachment.lang has the definition Language: "A human language". For example values, see ISO 639-3 (http://www.sil.org/iso639-3/codes.asp)

The mimeType element must always be populated. 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, they must point to the same content. The reference can never be reused to point to different data (which means that 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 of a location have not changed and also so that a signature of the xml content can implicitly sign the content of an image without having to include the data or reference the url in the signature. The lang element can help a consumer choose between multiple different Attachment elements.

In many cases where Attachment is used, the cardinality is >1; repeats are used to convey the same content in different mime types and languages.

  <x>
   <mimeType>application/pdf</mimeType>
   <data>/9j/4...KAP//Z</data> <!-- covers many lines -->
   <lang>eng</lang>
   <title>Definition of Procedure</title>
  </x>

  <x>
   <mimeType>application/dicom</mimeType>
   <url>http://10.1.2.3:1000/wado?requestType=WADO&wado details...</url>
   <hash>EQH/..AgME</hash>
  </x>

<x xmlns="http://hl7.org/fhir">
 <system><!-- 0..1 uri The namespace for the identifier --></system>
 <id><!-- 0..1 string The actual identifier --></id>
</x>

The system may be either a specific application or a recognised concept for which the specific application may be implicit. The system is a URI that may be an OID (oid:) or a UUID (uuid:), a sid (a specially defined URI from the named systems list (§1.4.2)) or a URL that references a definition of the identifier. 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.

In some cases, the system may not be known - only the id is known (e.g. a simple device that scans a barcode). In this case, no useful matching may be performed using the id unless the system can be safely inferred by the context.

Note that the system defines the scheme that controls uniqueness of the id. The id must be unique within the defined system. If the id itself is actually an OID, a UUID, or a URI, then the system will be either "http://hl7.org/fhir/sid/oid", "http://hl7.org/fhir/sid/uuid" or "http://hl7.org/fhir/sid/uri" respectively and the OID, UUID or URI would be in the id element. Ids are always case sensitive. UUIDs must be represented in lower case.

  <x>
   <system>oid:2.16.840.1.113883.16.4.3.2.5</system>
   <id>123</id>
  </x>

  <x>
   <system>http://pas-server/xxx/patient</system>
   <id>443556</id>
  </x>

  <x>
   <system>http://hl7.org/fhir/sid/uuid</system>
   <id>a76d9bbf-f293-4fb7-ad4c-2851cac77162</id>
  </x>

  <x>
   <system>http://hl7.org/fhir/sid/uri</system>
   <id>http://server.acme.com/fhir/people/@1</id>
  </x>

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

There must be a system that identifies the terminology or ontology the code is defined by. The system is a URI that may be an OID (oid:) a UUID (uuid:), a specially defined URI from the named systems list (§1.4.2), a url that references a definition of the system or any other URI. 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. If no code is present and there is no dataAbsentReason, the coding should be interpreted to mean that the concept cannot be encoded in the identified 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.

If two Codings have the same the system and code then they have the same meaning. 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 of the system for a given code system can be determined by:

• the System Identifiers (§1.4.2) 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

  <x>
    <code>G44.1</code>
    <system>http://hl7.org/fhir/sid/icd-10</system>
  </coding>
  </x>

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

1.3.6.1: Choosing Coding vs. CodeableConcept

A Coding is a simple direct reference to a code in a code system. The following type, CodeableConcept is a complex type that may include multiple Coding and/or a text representation. The interplay between one or more coding systems and a text representation is an extremely common pattern encountered in healthcare data and the CodeableConcept caters for the general case. Accordingly, it is usually used in resources in preference to the simpler Coding. Some resource definitions use Coding directly because the interplay between text and codes is inherently part of the resource model. In such cases, these resource definitions have to make allowance for the design issues directly.

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

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.

Whether or not coding elements are present, the text is a human language representation of the concept as seen/selected/uttered by the user who entered the data, and/or which 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 ID that must match an id attribute on one of the codings.

  <x>
    <coding>
      <code>R51</code>
      <system>http://hl7.org/fhir/sid/icd-10</system>
    </coding>
    <coding id="1">
      <code>25064002</code>
      <system>http://snomed.info</system>
    </coding>
    <text>general headache</text>
    <primary>1</primary>
  </x>

  <x>
    <coding>
      <code>tab</code>
      <system>oid:2.16.840.1.113883.19.5.2</system>
      <display>Tablet</display>
    </coding>
    <coding>
      <system>http://unitsofmeasure.org</system>
    </coding>
  </x>

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

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

The code is the selected value. A list of possible values 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 order.

  <x>
    <code>+</code>
    <value>
      <code>neg</code>
    </value>
    <value>
      <code>trace</code>
    </value>
    <value>
      <code>+</code>
    </value>
    <value>
      <code>++</code>
    </value>
    <value>
      <code>+++</code>
    </value>
    <isOrdered>true</isOrdered>
  </x>

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

Terminology Bindings

• Quantity.range has the definition QuantityRange: "how the Quantity should be understood and represented". Possible values:

  <	The actual value is less than the given value
  <=	The actual value is less than or equal to the given value
  >=	The actual value is greater than or equal to the given value
  >	The actual value is greater than the given value

The value contains the numerical value of the quantity, including an implicit precision. The range indicates how the value should be understood and represented. If no range is specified, the value is a point value (i.e. '='). The range element can never be ignored.

The units element must contain a displayable unit that defines what is measured. The units may additionally be coded in the code and the system, which is a URI, OID or a SID that defines the code (see CodeableConcept (§1.3.7) for further information about system).

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.3.9.1: Defined Variations on Quantity

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

  <x>
    <value>25</value>
    <unit>sec</unit>
    <code>s</code>
    <system>http://unitsofmeasure.org</system>
  </x>

  <x>
    <value>40000</value>
    <range>&gt;</range>
    <unit>mcg/L</unit>
    <code>ug</code>
    <system>http://unitsofmeasure.org</system>
  </x>

  <x>
    <value>3</value>
    <unit>capsules</unit>
    <code>385049006</code>
    <system>http://snomed.info</system>
  </x>

  <x>
    <value>25.45</value>
    <unit>US$</unit>
    <code>USD</code>
    <system>http://hl7.org/fhir/sid/iso-4217</system>
  </x>

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

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. A dataAbsentReason flag must be provided on the Range in this case.

The range flag on the low or high elements cannot have the values <, <=, =>, or >. Note that the Range type should not be used to represent measurements where the range flag might 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.

  <x>
   <low>
     <value>2.8</value>
     <unit>m</unit>
   </low>
   <high>
     <value>4.6</value>
     <unit>m</unit>
   </high>
  </x>

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

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" and 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.

  <x>
   <numerator>
     <value>1</value>
   </numerator>
   <denominator>
     <value>128</value>
   </denominator>
  </x>

  <x>
   <numerator>
     <value>103.50</value>
     <unit>US$</unit>
     <code>USD</code>
     <system>http://hl7.org/fhir/sid/iso-4217</system>
   </numerator>
   <denominator>
     <value>128</value>
     <unit>day</unit>
     <code>day</code>
     <system>http://unitsofmeasure.org</system>
   </denominator>
  </x>

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

If the low or high elements are missing, the meaning is that the low or high boundaries are not known. If the low element is missing, a dataAbsentReason flag must be provided on the Period element in this case. If the high is missing, it means that the period is ongoing.

The high 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.

  <x>
   <low>
     <date>2011-05-23</date>
   </low>
   <high>
     <date>2011-05-27</date>
   </high>
  </x>

<x xmlns="http://hl7.org/fhir">
 <type><!-- 0..1 Coding Code for identifier type --></type>
 <identifier><!-- 0..1 Identifier Actual identifier --></identifier>
 <period><!-- 0..1 Period Time period when id was valid for use --></period>
 <assigner><!-- 0..1 Resource(Organization) Organisation that issued id --></assigner>
</x>

Terminology Bindings

• HumanId.type has the definition IdentifierType: "The type of human identifier" (sid = urn:hl7-org:sid/fhir/CodeList). Possible values:

  account	Account number
  credit	Credit Card Number
  microchip	Microchip Number
  registry	A Registry Number
  insurance	Insurance Scheme Member Number
  national	National Healthcare Identifier
  ssn	National Social Security Number (or equivalent)
  jurisdiction	Jurisdictional Healthcare Identifier
  patient	Patient identifier
  facility	Facility ID
  provider	Provider number

Note that in many cases, the assigner is used to indicate what registry/state/facility/etc. assigned the identifier. Another possible source for the type of an identifier is HL7 v2 table 0203.

The resource elements often use HumanId for an identifier that may be an external human mediated reference, that may also come from a direct unambiguous reference to a resource or may be from a separate workflow, possibly human mediated. When the identifier is actually a direct resource reference, the type should be a resource type, the identifier.system should be the URL of the source system or, if a particular end point is not known, then "http://hl7.org/fhir/sid/fhir/[X]" where "[X]" is the resource name , and the identifier.id should be the resource id.

  <x>
    <type>
      <code>ssn</code>
      <system>http://hl7.org/fhir/sid/fhir/identifier-type</system>
    </type>
    <identifier>
      <system>http://hl7.org/fhir/sid/us-ssn</system>
      <id>000111111</id>
    </identifier>
  </x>

  <x>
    <type>
      <code>patient</code>
      <system>http://hl7.org/fhir/sid/fhir/identifier-type</system>
    </type>
    <identifier>
      <system>oid:0.1.2.3.4.5.6.7</system>
      <id>2356</id>
    </identifier>
   <period>
     <low>2009-06-05</low>
   </period>
  </x>

<x xmlns="http://hl7.org/fhir">
 <use><!-- 0..1 code The use of this name --></use>
 <text><!-- 0..1 string Text representation of the full name --></text>
 <part>  <!-- 0..* A part of a name -->
  <type><!-- 0..1 code Type of name part (see below) --></type>
  <value><!-- 1..1 string The content of the name part --></value>
 </part>
 <period><!-- 0..1 Period Time period when name was/is in use --></period>
</x>

Terminology Bindings

• HumanName.use has the definition NameUse: "The use of a human name". Possible values:

  usual	Known as/conventional/the one you normally use
  official	The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called "legal name".
  temp	A temporary name. A name valid time can provide more detailed information. This may also be used for temporary names assigned at birth or in emergency situations.
  anonymous	Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons)
  old	This name is no longer in use (or was never correct, but retained for records)
  maiden	A name used prior to marriage. Marriage naming customs vary greatly around the world. This name use is for use by applications that collect and store "maiden" names. Though the concept of maiden name is often gender specific, the use of this term is not gender specific. The use of this term does not imply any particular history for a person's name, nor should the maiden name be determined algorithmically.

• HumanName.part.type has the definition NamePartType: "Type of a part of a human name". Possible values:

  family	Family name, this is the name that links to the genealogy. In some cultures (e.g. Eritrea) the family name of a son is the first name of his father.
  given	Given name. NOTE: Not to be called "first name" since given names do not always come first.
  suffix	Part of the name that is acquired as a title due to academic, legal, employment or nobility status, etc. and that comes at the end of the name
  prefix	Part of the name that is acquired as a title due to academic, legal, employment or nobility status, etc. and that comes at the start of the name

The text element specifies the entire name as it should be represented. This may be provided instead of or as well as specific part elements. Every part must have a value.

Note that the order of the parts within a given part type has significance and must be observed. The different part types may be re-ordered between different contexts of use and the order between part types is not expected to be meaningful.

  <x>
    <use>usual</use>
    <part>
      <type>given</type>
      <value>Peter</value>
    </part>
    <part>
      <type>given</type>
      <value>James</value>
    </part>
    <part>
      <type>family</type>
      <value>Chalmers</value>
    </part>
  </x>

<x xmlns="http://hl7.org/fhir">
 <use><!-- 0..1 code The use of this address --></use>
 <text><!-- 0..1 string Text representation of the address --></text>
 <part>  <!-- 0..* -->
  <type><!-- 0..1 code Type of address part (see below) --></type>
  <value><!-- 1..1 string The content of the address part --></value>
 </part>
 <period><!-- 0..1 Period Time period when address was/is in use --></period>
</x>

Terminology Bindings

• Address.use has the definition AddressUse: "The use of an address". Possible values:

  home	A communication address at a home
  work	An office address. First choice for business related contacts during business hours
  temp	A temporary address. The period can provide more detailed information
  old	This address is no longer in use (or was never correct, but retained for records)

• Address.part.type has the definition AddressPartType: "Type of address part". Possible values:

  part	Part of an address line (typically used with an extension that further defines the meaning of the part).
  line	A line of an address (typically used for street names & numbers, unit details, delivery hints, etc.) .
  city	The name of the city, town, village, or other community or delivery centre.
  state	Sub-unit of a country with limited sovereignty in a federally organized country. A code may be used if codes are in common use (i.e. US 2 letter state codes).
  country	Country. ISO 3166 3 letter codes can be used in place of a full country name.
  zip	A postal code designating a region defined by the postal service.
  dpid	A value that uniquely identifies the postal address. (Often used in barcodes).

The text element specifies the entire address as it should be represented. This may be provided instead of or as well as specific part elements. Every part must have a value.

  <x>
   <use>work</use>
   <text>
       1050 W Wishard Blvd
       RG 5th floor
       Indianapolis, IN 46240
     </html>
   </text>
   <part> 
     <type>city</type>
     <value>Indianapolis</value>
   </part>
   <part> 
     <type>state</type>
     <value>IN</value>
   </part>
   <part> 
     <type>zip</type>
     <value>46240</value>
   </part>
  </x>

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

Terminology Bindings

• Contact.system has the definition ContactSystem: "What kind of contact this is". Possible values:

  phone	The value is a telephone number used for voice calls. Use of full international numbers starting with + is recommended to enable automatic dialing support but not required.
  fax	The value is a fax machine. Use of full international numbers starting with + is recommended to enable automatic dialing support but not required.
  email	The value is an email address
  url	The value is a url. This is intended for various personal contacts including blogs, Twitter, Facebook, etc. Do not use for email addresses

• Contact.use has the definition ContactUse: "How to use this address". Possible values:

  home	A communication contact at a home; attempted contacts for business purposes might intrude privacy and chances are one will contact family or other household members instead of the person one wishes to call. Typically used with urgent cases, or if no other contacts are available.
  work	An office contact. First choice for business related contacts during business hours.
  temp	A temporary contact. The period can provide more detailed information.
  old	This contact is no longer in use (or was never correct, but retained for records)
  mobile	A telecommunication device that moves and stays with its owner. May have characteristics of all other use codes, suitable for urgent matters, not the first choice for routine business

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.

  <x>
   <system>phone</system>
   <value>+15556755745</value>
   <use>home</use>
  </x>

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

Terminology Bindings

• Schedule.repeat.when has the definition EventTiming: "A real world event that a schedule is related to". Possible values:

  HS	event occurs duration before the hour of sleep (or trying to)
  WAKE	event occurs duration after waking
  AC	event occurs duration before a meal (from the Latin ante cibus)
  ACM	event occurs duration before breakfast (from the Latin ante cibus matutinus)
  ACD	event occurs duration before lunch (from the Latin ante cibus diurnus)
  ACV	event occurs duration before dinner (from the Latin ante cibus vespertinus)
  PC	event occurs duration after a meal (from the Latin post cibus)
  PCM	event occurs duration after breakfast (from the Latin post cibus matutinus)
  PCD	event occurs duration after lunch (from the Latin post cibus diurnus)
  PCV	event occurs duration after dinner (from the Latin post cibus vespertinus)

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.

There are 3 rules concerning the contents of a Schedule:

1. There can only be a repeat element if there is none or one event
2. Only one of frequency and when can be present
3. Only one of count and end can be present

  <x>
    <event>
      <low>2012-01-07T09:00</low>
      <high>2012-01-07T13:00</high>
    </event>
    <event>
      <low>2012-01-14T09:00</low>
      <high>2012-01-14T13:00</high>
    </event>
    <event>
      <low>2012-01-22T11:00</low>
      <high>2012-01-22T15:00</high>
    </event>
  </x>

  <x>
   <repeat>
     <frequency>2</frequency>
     <duration>
       <value>1</value>
       <units>day</units>
       <code>d</code>
       <system>http://unitsofmeasure.org</system>
     </duration>
   </repeat>
  </x>

  <x>
    <event>
      <low>2011-12-23</low>
    </event>
    <repeat>
      <when>ACM</when>
      <duration>
        <value>30</value>
        <units>min</units>
        <code>min</code>
        <system>http://unitsofmeasure.org</system>
      </duration>
      <end>2012-01-02</end>
    </repeat>
  </x>

1.3.19: Schema & UML models

Data Types Schema.

With regard to the UML models, see notes about the UML Object models (§1.2.9), and particularly the note regarding the UML representation of dataAbsentReason (§1.2.11)

1.4: Terminologies: Using Codes

Many elements in the FHIR resources are assigned a type of code, Coding (§1.3.6) or CodeableConcept (§1.3.7). These elements contain codes that have defined meanings and come from sets of codes of varying sophistication and size. In many simple cases, the set of codes is 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.

1.4.1: Bindings

All these elements of type code, Coding (§1.3.6) or CodeableConcept (§1.3.7) are given a "binding name" that defines the set of possible codes that can be used in the element in question. In Resource Profiles (§1.6), the elements can be assigned a new binding name that defines a new set of possible codes. The set of codes defined by a profile must be a subset of the set of codes defined in the base resource and those defined by any imported profiles. Binding Names can identify sets of codes in the following ways:

Value set and code list bindings also have two properties that govern their use - extensibility and conformance:

• Extensibility indicates whether additional codes are expected to be needed beyond those listed. It has two values:
  
  

  complete	No additional codes are to be used beyond the list provided
  extensible	Some concepts won't be covered by the provided value set, so supplemental codes or plain text may be needed

• Conformance indicates the expectations for implementers of the specification. There are three possible values:
  
  

  required	Only codes in the specified set are allowed. Profiles can only specify a subset of the defined codes. If the strength is 'extensible', other codes may be used for concepts not covered by the value set but cannot be used for concepts covered by the bound code list, even if a profile constrains out some of those codes). Specifications may render this as "SHALL"
  preferred	For greater interoperability, implementers are strongly encouraged to use the bound set of codes, however alternate codes may be used in profiles if necessary without being considered non-conformant. Specifications may render this as "SHOULD"
  example	The codes in the set are an example to illustrate the meaning of the field. There is no particular preference for its use. Specifications may render this as "MAY"

See the second tab of this page for a full list of the binding names defined for all FHIR resources.

This specification defines the following names (URIs) as fixed names that may be used in the system element of the Identifier (§1.3.5) Coding (§1.3.6) or CodeableConcept (§1.3.7) data types. If a URI is defined here, it must be used in preference to other identifying mechanisms such as OIDs found in the HL7 OID registry.

Important Note: The set of sids listed above is incomplete and subject to change. Some values may be dropped and others will likely be added in the coming months as HL7 institutes a formal process for determining what code systems and identifier types should be handled in this manner rather than as OIDs or other identifiers.

Internally defined codes useful throughout the specification where Coding (§1.3.6) or CodeableConcept (§1.3.7) is used. These are defined by the code system "http://hl7.org/fhir/sid/special-values" which has OID 2.16.840.1.113883.6.305.

1.5: Extensibility

This exchange specification is based on generally agreed common requirements across healthcare - covering many jurisdications, 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 resource includes an extension section that may be used 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.

<x xmlns="http://hl7.org/fhir">
 <code><!-- 1..1 id Code that identifies the meaning of the extension --></code>
 <profile><!-- 1..1 uri Profile that defines the extension --></profile>
 <ref><!-- 0..1 idref Internal reference to context of the extension (xml:id) --></ref>
 <mustUnderstand><!-- 0..1 boolean Must  you recognize this extension to safely read the resource? --></mustUnderstand>
 <value[x] d?><!-- 0..1 Value of extension --></value[x]>
 <extension><!-- 0..* Extension Nested Extensions --></extension>
</x>

Notes:

• The code identifies the meaning of the extension. The only codes that can be used are those defined using the methodology described below.
• The source of the definition must be declared using the definition element. The definition identifies a resource profile (§1.6) that defines the meaning of the extension.
• If present, the id in the ref element is an internal reference (§1.2.5) to a target element that is extended by the content as if it contained the extension itself. The id must point within the same resource. If id is not present, the extension applies to the root resource
• The order that extensions appear in is significant - where multiple extensions have the same target, they extend the target element in the order in which they appear in the extension section
• Any element defined as part of the resource content, or any repeating element inside a data type, may carry an id attribute to serve as the target of an extension
• An extension may have a value, or nested extensions, but not both. The actual name of the value element has the type added to it in place of the [x], such as valueQuantity

As well as providing additional information, extensions may be used to qualify the meaning of other elements or even to negate the meanings of other elements. This behavior makes these kinds extensions unsafe to ignore. Such extensions must have an attribute mustUnderstand = true. Any application processing the data of a resource must check for extensions labeled "mustUnderstand". If the application does not recognise the code on an extension that is labeled "mustUnderstand", and where the extension either has no internal reference, or the reference is data 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. Note that it must always be safe to show the narrative to humans; any extension that is labelled as "mustUnderstand" must be represented in the narrative. Applications are encouraged to ignore un-required extensions that they do not recognise if "mustUnderstand" is not set to true. "mustUnderstand" extensions SHALL be attached to reference points within an instance such that all data elements whose meaning may be impacted by the extension are part of the element to which the extension is attached.

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:

• dateTime
• string
• uri
• code - if the extension definition provides a binding to a suitable set of codes
• Coding (§1.3.6)
• CodeableConcept (§1.3.7)
• Attachment (§1.3.4)
• Identifier (§1.3.5)
• Quantity (§1.3.9)
• Choice (§1.3.8)
• Range (§1.3.10)
• Period (§1.3.12)
• Ratio (§1.3.11)
• HumanId (§1.3.14)
• HumanName (§1.3.15)
• Address (§1.3.16)
• Contact (§1.3.17)
• Schedule (§1.3.18)
• Resource - a reference to another resource

Some of the primitive (§1.3.1) datatypes are not included in this list. Extensions that might wish to use one of the ommitted primitives are expected to use one of the more complex types in their place. For example, decimal and integer are handed by Quantity (§1.3.9), base64Binary by Attachment (§1.3.4), etc.

Nested extensions cannot have a ref element. The [type] element is optional unless the definitions of the extension codes make rules about it. Extensions can never have a default value.

Extensions may be defined by any project or jurisdication, up to and including international standards organisations such as HL7 itself, and are published as part of a Resource Profile (§1.6). Extensions are always defined against some particular context. 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 (§2.1) supporting the Resources Profile, or a logical reference (e.g. using a urn:) - for instance, to a national published standard.

1.5.3: 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 implementors 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 instition'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

1.6: Resource Definition: Profile

Status: An infrastructure resource. This is an approved resource, and its status is draft for comment

A Resource Profile - a statement of use of FHIR. May include constraints on Resources, Terminology Binding Statements and Extension Definitions.

The resource name as it appears in a RESTful URL (§2.1) is /profile/

1.6.1: Background

This specification describes a set of base resources that are used in many different contexts in healthcare. In order to make this manageable, applications and specifications need to be able to:

• Explain how a set of resources is used in a particular context
• Describe restrictions on the use of the elements defined as part of the resource(s)
• Define the extensions that are used with the resources
• Describe how resources are bound to terminology in a particular context

All these things are done by a Resource Profile, which is itself a resource that describes the usage of one or more other resources. Profiles have a metadata section that describes who published the profile, and why, as well as optional lists of resources constraints, extension definitions, and vocabulary bindings.

1.6.2: Slicing

One common operation in a resource profile is to take an element that may occur more than once, and describe a series of different constraints on the elements in the list. In this way, the list is split into a series of individual elements or sub-lists. In FHIR, this operation is known as "Slicing" a collection. Here is an example to illustrate the process:

In this example, the resource definition defines the "relationship" element which may occur multiple times. The profile for Acme, Inc. constrains the relationship element into 3 different named kinds: 1 or 2 parents, up to 6 children, and maybe a guardian. No other relationships are supported by the Acme system.

Note that in FHIR, only the resource is ever actually exchanged. The profile describes a way of using the resource, but the item profile names ("parent", etc. in this list) are never exchanged. The slicing description is more useful if it is "unambiguous": if systems are able to determine which relationships in the relationship list that is actually exchanged are parent, child, or guardian; in this particular case, the determination is allowed by fixing the value of the relationship type element. Fixing a code value is the most common way to slice a list.

1.6.3: Resource Content

See also the Examples (§4.15) and the Definitions (§5.16).

<Profile xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Fixed identifier for this profile --></id>
 <name><!-- 1..1 string Informal name for this profile --></name>
 <version><!-- 0..1 string Version number for external references --></version>
 <author>  <!-- (Organisation or individual) -->
  <name><!-- 1..1 string Name of the recognised author --></name>
  <reference><!-- 0..* uri Web reference to the author --></reference>
 </author>
 <description><!-- 1..1 string Natural language description of the profile --></description>
 <code><!-- 0..* Coding Assist with indexing and finding --></code>
 <status>  <!-- Current status -->
  <code><!-- 1..1 code draft | testing | review | production | withdrawn | superceded --></code>
  <date><!-- 1..1 dateTime date for given status --></date>
  <comment><!-- 0..1 string Supplemental status info --></comment>
 </status>
 <import>  <!-- 0..* External source of extensions and bindings -->
  <uri><!-- 1..1 uri Profile location --></uri>
  <prefix><!-- 0..1 string Short form for referencing --></prefix>
 </import>
 <bundle><!-- 0..1 code If this describes a bundle, the first resource in the bundle --></bundle>
 <resource>  <!-- 0..* A constraint on a profile -->
  <type><!-- 1..1 code The Type of the resource being described --></type>
  <profile><!-- 0..1 uri Resource Profile that supplies the constraints --></profile>
  <name><!-- 0..1 string Name for this Constraint Statement --></name>
  <purpose><!-- 0..1 string Human summary: why describe this resource? --></purpose>
  <element>  <!-- 0..* Definition of elements in the resource -->
   <path><!-- 1..1 string The path of the element (see the formal definitions) --></path>
   <name><!-- 0..1 string Name of constraint for slicing - see above --></name>
   <definition>  <!-- More specific definition of the element  -->
    <short><!-- 1..1 string Concise definition for xml presentation --></short>
    <formal><!-- 1..1 string Formal definition --></formal>
    <comments><!-- 0..1 string Comments about the use of this element --></comments>
    <requirements><!-- 0..1 string Why is this needed? --></requirements>
    <synonym><!-- 0..* string Other names --></synonym>
    <min><!-- 1..1 integer Minimum Cardinality --></min>
    <max><!-- 1..1 string Maximum Cardinality (a number or *) --></max>
    <type>  <!-- 0..* Type of the element -->
     <code><!-- 1..1 code Data type or Resource --></code>
     <profile><!-- 0..1 uri Profile to apply (Resource only) --></profile>
    </type>
    <nameReference><!-- 0..1 string To another element constraint (by element.name) --></nameReference>
    <value[x] d?><!-- 0..1 Fixed value: [as defined for type] --></value[x]>
    <maxLength><!-- 0..1 integer Length for strings --></maxLength>
    <dataAbsentReason><!-- 1..1 boolean If @dataAbsentReason is allowed --></dataAbsentReason>
    <condition><!-- 0..* id reference to invariant about presence --></condition>
    <constraint>  <!-- 0..* Condition that must evaluate to true -->
     <id><!-- 1..1 id Target of 'condition' reference above --></id>
     <name><!-- 0..1 string Short human label --></name>
     <severity><!-- 1..1 code error | warning --></severity>
     <human><!-- 1..1 string Human description of constraint --></human>
     <xpath><!-- 1..1 string XPath expression of constraint --></xpath>
     <ocl><!-- 0..1 string OCL expression of constraint --></ocl>
    </constraint>
    <mustSupport><!-- 0..1 boolean If the element must be usable --></mustSupport>
    <mustUnderstand><!-- 0..1 boolean If the element must be understood --></mustUnderstand>
    <binding><!-- 0..1 string Binding - see bindings below (only if coded) --></binding>
    <mapping>  <!-- 0..* Map element to another set of definitions -->
     <target><!-- 1..1 string Which mapping this is (v2, CDA, openEHR, etc.) --></target>
     <map><!-- 0..1 string Details of the mapping --></map>
    </mapping>
   </definition>
   <bundled><!-- 0..1 boolean If type is Resource, is it in the bundle? --></bundled>
   <closed><!-- 0..1 boolean If list, whether derived profiles can slice more --></closed>
  </element>
 </resource>
 <extensionDefn>  <!-- 0..* Definition of an extension -->
  <code><!-- 1..1 code identifies the extension in the instance --></code>
  <contextType><!-- 1..1 code resource | datatype | mapping | extension --></contextType>
  <context><!-- 1..* string Where the extension can be used in instances --></context>
  <definition><!-- 1..1 Content as for Profile.resource.element.definition Definition of the extension and its content --></definition>
 </extensionDefn>
 <binding>  <!-- 0..* Define code sets for coded elements -->
  <name><!-- 1..1 string binding name --></name>
  <definition><!-- 0..1 string Human explanation of the binding --></definition>
  <type><!-- 1..1 code valueset | codelist | reference | special --></type>
  <isExtensible><!-- 1..1 boolean Can additional codes be used? --></isExtensible>
  <conformance><!-- 1..1 code required | preferred | example --></conformance>
  <reference><!-- 0..1 uri Source of binding content --></reference>
  <concept>  <!-- 0..* Enumerated codes that are the binding -->
   <code><!-- 1..1 code Code to use for this concept --></code>
   <system><!-- 0..1 uri source for the code, if taken from another system --></system>
   <display><!-- 0..1 string Print name. Defaults to code if not provided --></display>
   <definition><!-- 1..1 string Meaning of the concept --></definition>
  </concept>
 </binding>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of resource profile for human interpretation --></text>
</Profile>

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

Terminology Bindings

• Profile.status.code has the definition ResourceProfileStatus: "The lifecycle status of a Resource Profile". Possible values:

  draft	This profile is still under development
  testing	this profile was authored for testing purposes (or education/evaluation/evangelisation)
  review	This profile is undergoing review to check that it is ready for production use
  production	This profile is ready for use in production systems
  withdrawn	This profile has been withdrawn
  superseded	This profile was superseded by a more recent version

• Profile.bundle and Profile.resource.type share the definition of any defined Resource Type name (§1.4.5)
• Profile.resource.element.definition.type.code has the definition of any defined data Type name (§1.3) (including Resource (§1.2.6))
• Profile.extensionDefn.contextType has the definition ExtensionContext: "The type of context expression applicable". Possible values:

  resource	The context is all elements matching a particular resource element path
  datatype	The context is all nodes matching a particular data type element path (root or repeating element) or all elements referencing a particular primitive data type (expressed as the datatype name)
  mapping	The context is all nodes whose mapping to a specified reference model corresponds to a particular mapping structure. The context identifies the mapping target. The mapping should clearly identify where such an extension could be used, though this
  extension	The context is a particular extension from a particular profile. Expressed as uri#name, where uri identifies the profile and #name identifies the extension code

• Profile.binding.type has the definition BindingType: "How this binding is mapped to a set of codes". Possible values:

  valueset	The binding name has an associated URL which is a reference to a Value Set Resource that provides a formal definition of the set of possible codes
  codelist	The binding name is associated with a simple list of codes, and definitions from some identified code system (SID, URI, OID, UUID). In resource definitions, the system reference may be omitted, and a list of custom codes with definitions supplied (this is for status and workflow fields that applications need to know)
  reference	The binding name has an associated URL which refers to some external standard or specification that defines the possible codes
  special	The binding points to a list of concepts defined as part of FHIR itself (see below for possible values)

• Profile.binding.conformance has the definition BindingConformance: "Must applications comply with this binding?". Possible values:

  required	Only codes in the specified set are allowed. If the binding is extensible, other codes may be used for concepts not covered by the bound set of codes.
  preferred	For greater interoperability, implementers are strongly encouraged to use the bound set of codes, however alternate codes may be used in profiles if necessary without being considered non-conformant.
  example	The codes in the set are an example to illustrate the meaning of the field. There is no particular preference for its use

Constraints

• Provide either a profile reference or constraints on the resource elements (but not both) (xpath on /resource: exists(f:profile) != exists(f:element))
• Bundled may only be specified if one of the allowed types for the element is a resource (xpath on /resource/element: not(exists(f:bundled)) or exists(f:definition/f:type/f:code[starts-with(., 'Resource(')]))
• Either a name or a fixed value (but not both) is permitted (xpath on /resource/element/definition: not(exists(f:nameReference) and exists(f:*[starts-with(local-name(.), 'value')])))
• Value may only be specified if the type consists of a single repetition that has a type corresponding to one of the primitive data types. (xpath on /resource/element/definition: not(exists(f:*[starts-with(local-name(.), 'value')])) or (count(f:type)=1 and f:type/f:code[substring(.,1,1)=lower-case(substring(.,1,1))]))
• Binding can only be present for coded elements (xpath on /resource/element/definition: not(exists(f:binding)) or f:type/f:code=('code','Coding','CodeableConcept'))
• Max must be a number or "*" (xpath on /resource/element/definition/max: .='*' or (normalize-space(.)!='' and normalize-space(translate(., '0123456789',''))=''))
• Profile is only allowed if code is a resource (xpath on /resource/element/definition/type: not(exists(f:profile)) or starts-with(f:code, 'Resource('))
• Codes must be unique in the context of a profile (xpath on /extensionDefn/code: count(ancestor::f:Profile/f:extensionDefn/f:code[.=current()])=1)
• reference must be present and may only be present if binding type is "reference" or "valueset" (xpath on /binding: (f:type=('reference', 'valueset')) = exists(f:reference))
• concepts must be present and may only be present if binding type is "codelist" (xpath on /binding: (f:type='codelist') = exists(f:concept))
• Binding name must be unique in the context of a profile (xpath on /binding/name: count(ancestor::f:Profile/f:binding/f:name[.=current()])=1)

Metadata Notes:

• The name of the profile is not required to be globally unique, but the name should have some scoping information (i.e. Acme Inc (USA), Allergy List)
• Multiple codes may be assigned to the profile. These may either describe the template, or the focus of the template, or both. They are solely to help find the profile by searching for structured concepts
• When importing from other profiles, only the extensions and bindings defined in the other profiles are imported. Any extensions and bindings that are defined in other resources must have import statements referencing the location of the profile.

Interpretation Notes:

• The name of a resource constraint (Profile.resource.name) is only used as a logical target for .element.resource.profile. A reference may reference another resource constraint in same Resource Profile by Profile.resource.name as #[name]), or a different resource constraint in another profile by an absolute uri. In the case of an absolute uri, it must resolve literally or logically to a Resource Profile (§1.6) and specify a #[name] portion in the URI that references a particular constraint in the target profile by name
• The constraint statement has a flat list of elements. The path element provides the overall structure and it must match the structure and names in the resource structure exactly
• The condition element is used to assert that a constraint defined on another element affects the allowed cardinality of this element
• The type is used to specify which types apply when the underlying resource allows a choice of types. When the type of the element is fixed in the underlying resource definitions, it should still be stated in the profile. The type is optional because repeating groups of elements do not have a type.
• The definition (short, formal, comments and the mappings) for an element are provided so that the resource profile can provide a more specific definition for the field in a specific context. For instance, the underlying resource definition might be "Result value", and the more specific resource definition could be "Plasma Cholesterol Test Value". The meaning needs to be consistent with the underlying definition, but narrower - a constraint on it.
• For an element with a maximum cardinality of 1, there can only be one entry in the value list, which is either a literal fixed type (with an element name matching the type of the fixed value), or a name, which is a reference to a named constraint pattern. If the element has a type of "list", then there can be multiple values - again, either fixed values with a type, or a named constraint. Each of these appears in the list with the order and cardinality specified. By this means, a list may be "sliced" into a series of different components
• There can be more than one entry for each element path. The constraint specification can define multiple different constraints for any element, and then use them in different places. In practice, this is useful when slicing a list, and the differently named constraint profiles are invoked using the values element. The name of the element constraint must be unique within the constraint specification for that resource. If a constraint does not have a name, it applies to the base resource, and must be found in the correct place in the structure
• For an extension definition, the cardinality constraints are limits on the constraints of any reference to the extension in a profile. For example, if the minimum cardinality of an extension is 1 when it is defined, then any profile that includes that extension in the instance must include it with a minimum cardinality of 1, and therefore any instance that conforms to the profile must include the extension. Note, however, that if the extension is simply directly referenced in an instance rather than applied through a profile, the minimum cardinality doesn't apply, though the maximum one still does.

TODO: Is any control over narrative required?

1.6.4: Profiled FHIR

If a profile is unambiguous, then the FHIR profile tooling (ref to be provided) is able to generate reference implementation based object models that express the profiled model natively, where the object interface does not include prohibited elements, treats declared extensions as primary properties, and slices lists according to the profile. This eases the burden on an implementer, though this object model can only be used with a sub-set of the possible resources.

The tooling is also able to generate bi-directional transforms between the normal XML format (§1.2) and an XML representation of this profiled object model, and schema for this profiled XML representation. This XML form has extensions promoted into the primary XML form by using the extension code as the XML name, and sliced lists are renamed to use the Profile.resource.element.name as the XML element name. Profiles are only suitable for this use if they ensure that there are no clashing extension names when the extension definition spaces are ignored, and that the sliced list names are appropriate.

Implementations are allowed to exchange this profiled XML format. Implementations that do so are not fully conformant to FHIR; instead they can claim to be conformant to "Profiled FHIR". Implementations should consider carefully before adopting this approach; while it will reduce the amount of work required to initially implement particular profiles, it will increase the amount of work required to exchange this data with other communities, or to re-use tooling and applications that are also used in other contexts. This cost should particularly be considered in light of the fact that the previously discussed tooling allows applications to be written as though they are dealing with "Profiled FHIR" instances when they are in fact sending and receiving fully conformant FHIR instances.

1.6.5: Search Parameters

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

(See Searching (§2.1.12)).

2.6: Implementation Details

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

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 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. 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 references need to be able to be resolved. 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 a resource repository 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 resource metadata (§1.2.2) item "Master Location" may be useful as part of a solution towards resolving resource references and/or handling issues pertaining to distributed use and re-use of resources and implementations should describe how this data item is handled.
• The conformance statement (§2.7) 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.

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

• All schemas as a .zip (includes base schemas, resource schemas, Schematrons and FHIR-specific atom schemas and Schematrons)
• Single combined definitions of resources and data types as processable XML
• Single combined 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

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

2.6.7.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/) 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.7.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 RESTful implementation using HTTP (http://www.w3.org/Protocols/rfc2616/rfc2616.html) - an implementation of the OMG Health RESTful specification (http://www.omg.org) . 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. These HTTP calls may be authenticated against a single user account (including using OAuth (http://www.oauth.org) ), but this arrangement doesn't cater for common transaction metadata such as multiple users, responsible party, reasons, consents, etc. that are commonly encountered in healthcare. Instead, use of this protocol assumes that appropriate security and logs are managed by the client (perhaps through using ATNA), and that the server trusts the client to maintain these. One implication is that this RESTful framework is only suitable for use where such trust relationships exist (e.g. in a single institution) and is not suitable where such trust does not exist (e.g. state & national EHR systems and health record systems that support disparate systems). Similarly, this simple RESTful interface has no support for explicit archiving and similar functions. These types of more sophisticated usages should consider a messaging (§2.2) or SOA-based approach (§2.6.6) or some kind of profiled REST interface, such as hData (§2.4).

The following logical interactions are supported:

Note that while these same logical interactions are defined on all resources, applications are not required to implement all of them. Applications must provide a conformance statement (§2.7) that says what interactions are supported.

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 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 the service root URL below. 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: except for the Service Root Portion of the URL, all the URLs (and ids that form part of the URL) defined by this specification are case sensitive and are required to be in lowercase.

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

For this specification, normal HTTP security and authentication rules apply. The Service Root URL will specify whether SSL is required. HTTP authentication may be required by the server, possibly including the requirement for client certificates. It is a matter of application requirements and local configuration whether all interactions run under the account of a trusted system user whether each interaction runs under the account of the individual user or whether some other arrangement is required.

OAuth (http://oauth.net/) may be used to provide security. Applications are recommended to use the variants of the OAuth protocol that do not require URL parameters, but these may be used if necessary.

2.1.4: Content Types and File Extensions

The formal mime type for FHIR resources is text/xml+fhir (still to be registered) and SHOULD be use by clients and servers. Servers are required to support the XML format of the resources defined in this specification, but may support other alternatives, including the informative JSON (§1.2.10) representation. Servers must support the content-type negotiation support described by the HTTP specification, but in order to support various implementation limitations, may choose to support the (?format=) parameter to specify alternative return formats by their mime types. For the format parameter, the mime types text/xml & text/xml+fhir must be interpreted to mean the normative XML format defined by FHIR and application/json must be interpreted to mean the informative JSON format.

2.1.5: 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.

2.1.6: 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. Servers may return a content-location header with the response which is the url requested and a Last-Modified header.

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. The vread interaction should succeed even after a resource is deleted as long as a correct version identifier is provided.

2.1.7: update

The update interaction changes an existing resource or creates a new resource if it doesn't already exist. The update interaction is performed by an HTTP PUT operation as shown:

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

The server must return 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 Content-Location header that refers to the version created by the updated operation.

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 incorrect, the server SHALL return a 412 Preconditions failed response. Clients SHOULD submit a proper Content-Location header and SHALL correctly understand a 412 response as an update conflict.

2.1.8: 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.5) of a resource return a 410 error and that the resource is no longer found through search operations. If a 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. 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.9: history

The history interaction retrieves the history of the resource. The interaction is performed by an HTTP Get operation as shown:

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

The return content is an Atom feed containing the version history for that resource, sorted with oldest versions first. ToDo: how deletions are represented.

2.1.10: 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:

  todo: harmonise these with the RLUS REST specification
  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 checking 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 are applied as well. The return content has status 200 OK if the content validates ok or 409 Conflict, with the following content:

 <validation xmlns="http://hl7.org/fhir">
   <error mand type="string">General error message</error>  
   <messages type="list">   <!-- Zero+ -->
     <message>
       <path opt type="string"xpath to the issue</path>
       <error mand type="string">Description of the problem</error>
     </message>
   <messages>
 </validation>

The validation operation has complex semantics and rules. Implementers wishing to use this operation should consult the full discussion of the operation in the OMG REST specification.

2.1.11: updates

The updates interaction retrieves a list of the resources of a particular type, ordered by the date of last update in reverse (most recently changed first). The interaction is performed by an HTTP Get operation as shown:

  GET [service-url]/[resourcetype] (?format=mimeType)

The return content is an Atom feed containing list of resources, sorted with oldest updates first.

The updates list can be restricted to a limited period by the Last-Modified header. Additional parameters can be used to filter the updates list using the search parameters defined by the resource type.

2.1.12: search

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

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

Because of the way that some user agents treat POST requests, POST submissions are also allowed, though the semantics are exactly the same as a GET operation. Search operations take a series of parameters that are encoded in the URL or as an x-multi-part-form submission for a POST. Each FHIR resource type defines a set of applicable search parameters with their meanings and servers may declare additional parameters in their conformance statements. In addition, the following common search parameters apply to all resource types:

It is at the discretion of the server how many results to return, though the client may request a particular number with the count parameter. If the client wishes for more results, it should use the n parameter. More generally, the client uses parameters to narrow the search and increase its usefulness. Note that which parameters to support is at the discretion of the server.

The return content is an Atom feed containing the results of the search as a list of resources in a defined order. This specification does not assign any particular meaning to the order of the resources.

If more sophisticated searching is required, a FHIR-based service interface can be defined to enable the workflow and functionality desired. At this time, support for messaging-based queries is not expected to be needed in FHIR.

2.1.12.1: Search Parameter Types

2.1.13: create

The create interaction creates a new resource. The interaction is performed by an HTTP POST operation as shown:

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

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

 Location: [service-url]/[resourcetype]/{new-id} version aware.... 

The resource id element SHALL not be present. If the client wishes to specify the id of the submitted resource, then it should use the update operation instead.

2.1.14: conformance

The conformance interaction retrieves the application's conformance statement for the resource. The interaction is performed by an HTTP OPTIONS operation as shown:

  OPTIONS [service-url] (?format=mimeType)

Applications SHALL return a Conformance Resource (§2.7) that specifies which resource types and operations are supported. If a 404 Unknown is returned, FHIR is not supported on the nominated service url.

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.

2.1.15: 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 rogue caching.

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 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.2: Resource Definition: MessageHeader

Status: An infrastructure resource. This is an approved resource, and its status is 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 (§2.5) 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 (§2.5) of resources, with the first resource in the bundle being a Message (§2.2.4) resource with a response section that reports the outcome of processing the message and any additional response resources required.

2.2.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, LLP (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 case, 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 described below in both directions.

2.2.1.1: 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 applications must conform to, whether messaging appears to be reliable or not.

A message receiver must always check the incoming bundle identifier (atom feed.id), and check them against a store of previously received messages (going back a reasonable period in time). If it receives a duplicate message id that it has already responded to, it should assume that the original response was lost (failed to return to the request issuer), and resend the original response in a new bundle. If the source application gets no response to its request from the destination application, the source application should resend the same bundle with the same atom feed.id.

2.2.2: Conformance Statement

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

The second end-point is used for actually sending messages as bundles (§2.5), 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.2.6).

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.

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

<MessageHeader xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Master Resource Id = Message Id --></id>
 <instant><!-- 1..1 instant Instant the message was sent --></instant>
 <event><!-- 1..1 code Code for the event his message represents --></event>
 <response>  <!-- If this is a reply to prior message -->
  <id><!-- 1..1 id Id of original message --></id>
  <code><!-- 1..1 code Type of response to the message --></code>
 </response>
 <source>  <!-- Message Source Application -->
  <name><!-- 0..1 string Name of system --></name>
  <software><!-- 1..1 string Name of software running the system --></software>
  <version d?><!-- 0..1 string Version of software running --></version>
  <contact d?><!-- 0..1 Contact Human contact for problems --></contact>
  <endpoint><!-- 1..1 uri Actual message source address or id --></endpoint>
 </source>
 <destination>  <!-- Message Destination Application -->
  <name><!-- 0..1 string Name of system --></name>
  <target d?><!-- 0..1 Resource(Device) Particular delivery destination within the destination --></target>
  <endpoint><!-- 1..1 uri Actual destination address or id --></endpoint>
 </destination>
 <enterer d?><!-- 0..1 Resource(Agent) The source of the data entry --></enterer>
 <author d?><!-- 0..1 Resource(Agent) The source of the decision --></author>
 <receiver d?><!-- 0..1 Resource(Person|Organization) Intended "real-world" recipient for the data --></receiver>
 <responsible d?><!-- 0..1 Resource(Agent|Organization) Final responsibility for event --></responsible>
 <effective d?><!-- 0..1 Period Time of effect --></effective>
 <reason d?><!-- 0..1 CodeableConcept Cause of event --></reason>
 <data><!-- 0..* Resource(Any) The actual content of the message --></data>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of message, for human interpretation --></text>
</MessageHeader>

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

Terminology Bindings

• MessageHeader.event has the definition of the Event List in the messaging framework (§2.2.5)
• MessageHeader.response.code has the definition ResponseCode: "The kind of response to a message". Possible values:

  ok	The message was accepted and processed without error
  error	Some internal unexpected error occurred - wait and try again. Note - this is usually used for things like database unavailable, which may be expected to resolve, though human intervention may be required
  rejection	The message was rejected because of some content in it. There is no point in re-sending without change. The response narrative must describe what the issue is
  rules	The message was rejected because of some event-specific business rules, and it may be possible to modify the request and re-submit (as a different request). The response data must clarify what the change would be, as described by the event definition
  undeliverable	A middleware agent was unable to deliver the message to its intended destination

• MessageHeader.reason has the definition EventReason: "The reason for an event occurring"

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 (§1.6) 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

• 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 (i.e. an atom feed) containing a message or document resource as the first resource
• The response content type returned is always an HTTP error, a bundle (i.e. an atom feed) containing a message as the first resource, or empty (if a document was received)
• 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.

2.2.7: Search Parameters

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

(See Searching (§2.1.12)).

2.3: Resource Definition: DocumentHeader

Status: An infrastructure resource. This is an approved resource, and its status is 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 (a list of resources in an atom feed) 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".

2.3.1: Document Content

All documents have the same structure: a bundle that has a Document Header resource (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 header 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.

The Document.id identifies the logical document. Multiple versions of the document may exist, each with their own unique bundle identifier (Atom feed.id). The means the Document.id maps to CDA ClinicalDocument.setId and the feed.id to ClinicalDocument.id.

Document profiles (§1.6) 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 their contents are. Applications should consider publishing conformance statements (§2.7) that identify particular documents they support.

2.3.2: Document End-Points

There are two RESTful end-points defined for Documents:

• [baseurl]/documentheader/: a normal RESTful end point for document header resources
• [baseurl]/document/: a RESTful end point that serves documents as bundles. This is described below (§2.3.6)

The first end-point is used for working within the document contents, for instance, for building documents piecemeal, for auditing received documents or for providing a document registry. The second end-point is used for working with whole documents, such as providing a document repository. Servers may un-bundle documents received through the /document/ end-point, and make the document resources they contain available through the /documentheader/ end-point, but are not required to do so.

RESTful systems may also accept documents through their mailbox (§2.2.6).

Note: While the end-points above are defined for use with document resources and document bundles, it is not necessary to use them. Documents may be transferred between systems using any method desired.

2.3.3: Resource Content

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

<DocumentHeader xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Master Resource Id = document Id --></id>
 <instant><!-- 1..1 instant Document Creation Time --></instant>
 <type><!-- 1..1 CodeableConcept Kind of Document (LOINC if possible) --></type>
 <title d?><!-- 0..1 string Document Title --></title>
 <replaces><!-- 0..1 id If this document replaces another --></replaces>
 <enterer d?><!-- 0..1 Resource(Agent) The source of the data entry --></enterer>
 <subject><!-- 1..1 Resource(Patient|Group|Device) Who/what the document is about --></subject>
 <informant d?><!-- 0..1 Resource(Person) Who provided information in document --></informant>
 <author><!-- 1..* Resource(Agent) Who/what authored the final document --></author>
 <attester>  <!-- 0..* Attests to accuracy of document -->
  <mode><!-- 1..1 code Personal | professional | legal | official --></mode>
  <time d?><!-- 0..1 dateTime When document attested --></time>
  <party d?><!-- 0..1 Resource(Agent|Organization) Who attested the document --></party>
 </attester>
 <recipient d?><!-- 0..* Resource(Agent|Organization) Expected to receive a copy  --></recipient>
 <custodian><!-- 1..1 Resource(Organization) Org which maintains the document --></custodian>
 <context d?><!-- 0..1 Resource(Any) The clinical item being documented --></context>
 <encounter d?><!-- 0..1 Resource(Admission|InterestOfCare) Context of the document --></encounter>
 <stylesheet d?><!-- 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 -->
  <type><!-- 0..1 CodeableConcept Type of section (recommended) --></type>
  <instant d?><!-- 0..1 instant Section Creation Time --></instant>
  <author><!-- 0..1 Resource(Agent) Who/what authored the section --></author>
  <enterer d?><!-- 0..1 Resource(Agent) The source of the data entry --></enterer>
  <subject><!-- 0..1 Resource(Patient|Group|Device) If section different to document --></subject>
  <informant d?><!-- 0..1 Resource(Person) Who provided information in section --></informant>
  <content d?><!-- 0..1 Resource(Any) The actual data for the section --></content>
  <text d?><!-- 0..1 Narrative Human Readable Text Summary of the section --></text>
  <section><!-- 0..* Content as for DocumentHeader.Section Nested Section --></section>
 </section>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of document, for human interpretation --></text>
</DocumentHeader>

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

Terminology Bindings

• DocumentHeader.type has the definition DocumentType: "Type of a clinical document". If an appropriate code exists in LOINC Document Types then it should be used
• DocumentHeader.attester.mode has the definition DocumentAuthenticationMode: "The way in which a person authenticated a document". Possible values:

  personal	The person authenticated the document in their personal capacity
  professional	The person authenticated the document in their professional capacity
  legal	The person authenticated the document and accepted legal responsibility for its content
  official	The organization authenticated the document as consistent with their policies and procedures

• DocumentHeader.section.type has the definition DocumentSectionType: "Type of a clinical document section". If an appropriate code exists in LOINC Section Types then it should be used

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 = 'text/css')
• A section must have content or one or more sections, but not both. (xpath on /section: exists(f:content) != exists(f:section))

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 resources
• The author, subject, enterer and informant features are inherited in contained sections and need not be repeated. Specifying any of these in a section replaces the inherited value
• 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.3.4: 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 summarise 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.

In addition to the basic style rules (§1.2.4.1), 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 no their long term scope for document exchange very carefully.

2.3.5: Document Handling Obligations

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

2.3.5.1: Author Obligation

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 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 (§1.6).
• Ensure that the presentation of the document is properly attested according to the information supplied in the attesters.

2.3.5.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 or accessed via a document management system. 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

• Documents 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 attester.

The standard RESTful endpoints (such as [baseurl]/person/@{id} for a Person resource or [baseurl]/document/@{id} for the Document resource) handle the individual resources and not bundles (though, per the RESTful spec, they serve up atom feeds for the history (§2.1.9), search (§2.1.12) and update (§2.1.7) operations). The Document (§2.3) framework defines an additional end-point for handling document bundles at [baseurl]/document/@{id}). In this context, the id is the id of the Document Header resource. The end-point supports the following operations:

Note that the history, updates and search methods all return atom feeds that contain bundles - that is, atom feeds that contain entries where the content type is another atom feed. Atom feeds are only ever nested two levels deep (i.e. one atom feed containing a series of atom feeds that are bundles that contain resources).

2.3.8: Search Parameters

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

(See Searching (§2.1.12)).

2.4: Using FHIR Resources with hData

hData (Known Broken Link - needs to be resolved) describes the use of a RESTful architecture to manage a set of granular resources in a coherent record structure. hData and FHIR share the same basic RESTful transport (the RESTful specification (§2.1) is a profile on the OMG hData RESTful (Known Broken Link - needs to be resolved) transport). hData builds on top of that a set of resources and addresses issues that provide the architecture to maintain a coherent record, such as a patient care record. This page documents how FHIR resources may be used for the components of an hData record architecture.

Notes:

content profile for hData for each resource
  template for a content profile - available @ hdata wiki page on hl7 wiki (ArB is going to review that)
  schema + rddl (see rddl.org)
  set link rel in atom feed on per type 

Whenever resources are gethered into a list, this is done using the Atom format (http://tools.ietf.org/html/rfc4287), following this template:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:gd="http://schemas.google.com/g/2005">
  <title 1..1 type="string">text statement of purpose</title>
  <updated 1..1 type="instant">when the bundle was built</updated>
  <id 1..1 type="uri">unique uri for this bundle</id>
  <link 1..1 rel="self" href="[building application url]"/>

  <entry gd:etag="version id">    <!-- Zero+ -->
    <title 1..1 type="string">text summary of resource</title>
    <link 1..1 rel="self" href="Master Location for Resource"/>
    <id 1..1 type="uri">Master Id (uri) for this resource</id>
    <updated 1..1 type="instant">Last Updated for resource</updated>
    <published 0..1 type="instant">Time resource copied into the feed</updated>
    <author>
      <name 1..1 type="string">Name of Human or Device that authored the resource</name>
      <uri 0..1 type="uri">Link to the resource for the author</uri>
    </author>
    <category 1..1 term="[Resource Type]" scheme="http://hl7.org/fhir/sid/fhir/resource-types"/>  
    <content 1..1 type="text/xml">
      <[ResourceName] xmlns="http://hl7.org/fhir">
         <id 1..1 type="id">Resource Id (i.e. normal resource content)</id>
         <!-- Content for the resource -->
      </[ResourceName]>
    </content>
    <summary 0..1 type="xhtml">
        <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. The order of elements in the atom namespace as documented here does not need to be followed
• The title for the feed and the entry are arbitary 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 id. UUIDs are recommended
• The link elements are mandatory in the atom feed format.
• The type attribute on the content element does appear in the xml instance (it's an atom type, not a FHIR type)
• The entry element carries the three pieces of resource metadata (§1.2.2): Version Id, Last Updated, and Master Location
• Author is a required element by the atom element. 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 resource for the author
• In a RESTful implementation, the Master Location is the URL of the resource on a system that is the master for that resource. In the absence of a known master or a RESTful implementation, some other location may be used.
• An xml:base element may be specified on the content element, though one is not needed for FHIR resources.
• The entire bundle can be signed with a single Enveloped Digital Signature as described in the Atom specification. See below for further comment

Readers of the resources bundles should always look through the resources in the atom feed when a resource reference (§1.2.6) 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>Organization</type>
    <id>1145c09c-73d0-4297-9835-620e4afa9deb</id>
  </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 that organization is in the feed, it would look like this:

   .. feed ..
  <entry>
    .. 
    <id>1145c09c-73d0-4297-9835-620e4afa9deb<id>
    .. 
    <category term="Organization" scheme="http://hl7.org/fhir/sid/fhir/resource-types"/>

    <content type="text/xml">
      <Organization xmlns="http://hl7.org/fhir">
         <id>1145c09c-73d0-4297-9835-620e4afa9deb</id>
         <!-- other Content for the resource -->
      </Organization>
    </content>
  ... feed ...

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

  <institution>
    <type>Organization</type>
    <id>http://acme.com/fhir/patient/@23</id>
  </institution>

A reader trying to find this institution should always look through the entries in the atom feed prior to looking anywhere else for the institution. If that patient is in the feed, it would look like this:

   .. feed ..
  <entry>
    .. 
    <link rel="self" href="http://acme.com/fhir/patient/@23"/>
    <id>23<id>
    .. 
    <category term="Patient" scheme="http://hl7.org/fhir/sid/fhir/resource-types"/>

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

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. Note that this example used a FHIR RESTful URL (§2.1), but this is not required.

2.5.1: 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 good feature, but it may also cripple interoperability between closed eco-systems where re-identification 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 (§1.2.5). 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 to the resource in which the id attribute is declared.
• When representing the atom feed as JSON, use the method described here (http://www.ibm.com/developerworks/library/x-atom2json/index.html) .
• The Document (§2.3.6) framework defines an additional RESTful end-point that works like a normal RESTful interface (§2.1) but serves document bundles instead of document resources.

2.6: Resource Definition: ValueSet

Status: An infrastructure resource. This is an approved resource, and its status is draft for comment

Value Set - a set of defined codes from one or more code systems that may be bound to a context.

The resource name as it appears in a RESTful URL (§2.1) is /valueset/

A value set specifies a set of codes drawn from one or more code systems. Value sets don't actually define the code themselves - they just define what codes are included or excluded from the set. Value sets are defined to control what codes or concepts can be used in a particular context.

A value set resource is directly mappable to a CTS2 value set definition and an automated transform should be possible in order to use a CTS2 server to provide value set functionality

2.6.1: Resource Content

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

<ValueSet xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Fixed identifier for this value set resource --></id>
 <name><!-- 1..1 string Informal name for this value set --></name>
 <author>  <!-- (Organisation or individual) -->
  <name><!-- 1..1 string Name of the recognised author --></name>
  <reference><!-- 0..1 uri Author contact --></reference>
 </author>
 <description><!-- 1..1 string Human language description of the value set --></description>
 <status><!-- 1..1 code draft | testing | production | withdrawn | superseded --></status>
 <date><!-- 1..1 dateTime Date for given status --></date>
 <identifier><!-- 1..1 id Logical id to reference this value set --></identifier>
 <version><!-- 1..1 id Logical id for this version of the value set --></version>
 <restricts><!-- 0..* uri Can replace these value sets when profiling --></restricts>
 <import><!-- 0..* uri Import the contents of another value set --></import>
 <include>  <!-- 0..* Include one or more codes from a code system -->
  <system><!-- 1..1 uri The system the codes come from --></system>
  <version><!-- 0..1 string Specific version of the code system referred to --></version>
  <mode><!-- 1..1 code code | children | descendants | all --></mode>
  <code><!-- 0..* code Code or concept --></code>
  <filter>  <!-- 0..* Celect codes/concepts by their properties -->
   <property><!-- 1..1 code A property defined by the code system  --></property>
   <op><!-- 1..1 code = | is_a | is_not_a | regex --></op>
   <value><!-- 1..1 code Code from the system, or regex criteria --></value>
  </filter>
 </include>
 <exclude><!-- 0..* Content as for ValueSet.include Explicitly exclude codes --></exclude>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of value set for human interpretation --></text>
</ValueSet>

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

Terminology Bindings

• ValueSet.status has the definition ValueSetStatus: "The lifecycle status of a Value Set". Possible values:

  draft	This valueset is still under development
  testing	This valueset was authored for testing purposes (or education/evaluation/evangelisation)
  production	This valueset is ready for use in production systems
  withdrawn	This valueset should no longer be used
  superseded	This valueset has been replaced and a different valueset should be used in its place

• ValueSet.include.mode has the definition CodeSelectionMode: "The way in which the code is selected". Possible values:

  code	Only this code is selected
  children	Only the immediate children (codes with a is_a relationship) are selected, but not this code itself
  descendants	All descendants of this code are selected, but not this code itself
  all	This code and any descendants are selected

• ValueSet.include.filter.op has the definition FilterOperator: "The kind of operation to perform as part of a property based filter". Possible values:

  =	The property value has the concept specified by the value
  is_a	The property value has a concept that has an is_a relationship with the value
  is_not_a	The property value has a concept that does not have an is_a relationship with the value
  regex	The property value representation matches the regex specified in the value

Constraints

• A value set with only one import must also have an include and/or an exclude (xpath: count(f:include)!=1 or exists(f:include) or exists(f:exclude))
• A value set must have an include or an import (xpath: exists(f:include) or exists(f:import))
• A selection criteria must have at least one code or filter (xpath on /include: count(f:code|f:filter)!=0)

Notes:

• The content of the value set is a union of all the import and include statements and then with any excluded codes eliminated
• A value set needs to do something. It can't simply include an existing value set without also including additional content or excluding content
• The point of declaring that this value set restricts another is that this value set can then replace the other in a profile without changing the meaning. Declaring this explicitly allows profile tools to reason about the relationship without having to compute the relationship, which might not be possible for a profile tool
• The identifier and version elements may be used to reference this value set in a design, a profile, a CDA template or V3 message (valueSet and valueSetVersion). These different contexts may make additional restrictions on the possible values of these elements

2.6.2: Search Parameters

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

(See Searching (§2.1.12)).

2.7: Resource Definition: Conformance

Status: An infrastructure resource. This is an approved resource, and its status is 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 (§2.1) is /conformance/

Conformance statements are used in one of three ways:

2.7.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.

2.7.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 aquisition 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.

2.7.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 proferred 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.

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.

2.7.4: Resource Content

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

<Conformance xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id ConformanceStatement Id --></id>
 <date><!-- 1..1 dateTime Publication Date --></date>
 <publisher>  <!-- Publisher of the statement -->
  <name><!-- 1..1 string Publishing Organization --></name>
  <address><!-- 0..1 Address Address of Organization --></address>
  <contact><!-- 0..* Contact Contacts for Organization --></contact>
 </publisher>
 <implementation>  <!-- If profile is for implementation -->
  <description><!-- 1..1 string What implementation is covered? --></description>
  <url><!-- 0..1 uri Base URL for interfaces --></url>
 </implementation>
 <software>  <!-- If profile is for software offered -->
  <name><!-- 1..1 string Name software is known by --></name>
  <version><!-- 0..1 string Version covered by this statement --></version>
  <releaseDate><!-- 0..1 dateTime Date this version released --></releaseDate>
 </software>
 <proposal>  <!-- If profile is for proposal -->
  <description><!-- 1..1 string Details of proposal or requirements document --></description>
 </proposal>
 <version><!-- 1..1 id FHIR Version --></version>
 <acceptUnknown><!-- 1..1 boolean True if application accepts unknown elements --></acceptUnknown>
 <rest>  <!-- 0..* If the endpoint is a RESTful one -->
  <mode><!-- 1..1 code client | server --></mode>
  <documentation><!-- 0..1 string Security, etc. --></documentation>
  <resource>  <!-- 1..* Resource served on the REST interface -->
   <type><!-- 1..1 code Resource type --></type>
   <profile><!-- 0..1 uri Profile describing resource support --></profile>
   <operation>  <!-- 1..* What operations are supported? -->
    <code><!-- 1..1 code read | vread | update | etc. --></code>
    <documentation><!-- 0..1 string Anything special about operation behavior --></documentation>
   </operation>
   <search>  <!-- Only if supported -->
    <documentation><!-- 0..1 string General guidance on searching --></documentation>
    <param>  <!-- 1..* Search params supported -->
     <name><!-- 1..1 string Name of search parameter --></name>
     <documentation><!-- 0..1 string contents and meaning of search parameter --></documentation>
    </param>
   </search>
  </resource>
 </rest>
 <messaging>  <!-- 0..* If messaging is supported -->
  <endpoint><!-- 0..1 uri Actual endpoint being described --></endpoint>
  <documentation><!-- 0..1 string Messaging interface behavior details --></documentation>
  <event>  <!-- 1..* Declare support for this event -->
   <code><!-- 1..1 code Event type --></code>
   <mode><!-- 1..1 code sender | receiver --></mode>
   <protocol><!-- 0..* Coding http | ftp |MLLP | etc. --></protocol>
   <focus><!-- 1..1 code Resource that's focus of message --></focus>
   <request><!-- 0..1 uri Profile that describes the request --></request>
   <response><!-- 0..1 uri Profile that describes the response --></response>
   <documentation><!-- 0..1 string Endpoint-specific event documentation --></documentation>
  </event>
 </messaging>
 <document>  <!-- 0..* document definition -->
  <mode><!-- 1..1 code producer | consumer --></mode>
  <documentation><!-- 0..1 string Description of document support --></documentation>
  <profile><!-- 1..1 uri Constraint on a resource used in the document --></profile>
 </document>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of conformance profile for human interpretation --></text>
</Conformance>

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

Terminology Bindings

• Conformance.rest.mode has the definition RestfulConformanceMode: "The mode of a restful conformance statement". Possible values:

  client	The application acts as a server for this resource
  server	The application acts as a client for this resource

• Conformance.rest.resource.type and Conformance.messaging.event.focus share the definition of any defined Resource Type name (§1.4.5)
• Conformance.rest.resource.operation.code has the definition RestfulOperation: "Operations supported by REST". Possible values:

  read	Read the current state of the resource
  vread	Read the state of a specific version of the resource
  update	Update an existing resource by its id (or create it if it is new)
  delete	Delete a resource
  history	Retrieve the update history for the resource
  validate	Check that the content would be acceptable as an update
  updates	Get a list of prior updates to resources of this type, optionally with some filter criteria
  create	Create a new resource with a server assigned id

• Conformance.messaging.event.code has the definition of the Event List in the messaging framework (§2.2.5)
• Conformance.messaging.event.mode has the definition ConformanceEventMode: "The mode of a message conformance statement". Possible values:

  sender	The application sends requests and receives responses
  receiver	The application receives requests and sends responses

• Conformance.messaging.event.protocol has the definition MessageTransport: "How messages are delivered" (sid = urn:hl7-org:sid/fhir/CodeList). Possible values:

  http	The application sends or receives messages using HTTP POST (may be over http or https)
  ftp	The application sends or receives messages using File Transfer Protocol
  mllp	The application sends or receivers messages using HL7's Minimal Lower Level Protocol

• Conformance.document.mode has the definition DocumentMode: "Whether the application produces or consumes documents". Possible values:

  producer	The application produces documents of the specified type
  consumer	The application consumes documents of the specified type

Constraints

• Must have one and only one of software, implementation or 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))

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.14). 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
  • Resource Types or operations that are not listed are not supported
• Messaging conformance rules:
  • The interpretation of request and resource 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:
  • Ideally, the criteria in different document profile should be able to distinguish between multiple document profiles, so that there is no ambiguity concerning which profile any given document conforms to. However this is not always possible

2.7.5: Search Parameters

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

(See Searching (§2.1.12)).

3.7: Resources

The FHIR specification presently defines the following resources:

Of these, only the Infrastructure resources have undergone any degree of vetting. The remaining administrative and clinical resources exist to provide a sense of what such resources will look like eventually. 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: Agent

Status: A domain resource developed as an examplar. Not an approved resource. Under consideration by the Patient Admin work group

A person who represents an organisation, and is authorised to perform actions on its behalf.

The resource name as it appears in a RESTful URL (§2.1) is /agent/

3.1.1: Resource Content

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

<Agent xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Master Resource Id, always first in all resources --></id>
 <person><!-- 1..1 Resource(Person) The person who is the agent --></person>
 <organization><!-- 1..1 Resource(Organization) The represented organization --></organization>
 <role><!-- 1..* CodeableConcept A role the agent has --></role>
 <period d?><!-- 0..1 Period The period for which this agency applies (date only) --></period>
 <identifier d?><!-- 0..* HumanId A Human identifier for the person as this agent --></identifier>
 <address d?><!-- 0..* Address An address that applies for the person as this agent --></address>
 <contact d?><!-- 0..* Contact A contact that applies for the person as this agent --></contact>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of the agent, for human interpretation --></text>
</Agent>

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

Terminology Bindings

• Agent.role has the definition AgentRole: "The role a person plays representing an organization"

Notes:

• Any person can represent the same organisation in multiple different ways. This may be represented as a single agent resource with multiple role codes, or multiple agent resources. Which is correct depends on whether the combined roles share other attributes, such as identifiers and time periods.
• The person and organization references are mandatory, so must be a full resource reference by identifier

3.1.2: Search Parameters

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

(See Searching (§2.1.12)).

3.2: Resource Definition: Animal

Status: A domain resource developed as an examplar. Not an approved resource. Under consideration by the Patient Admin work group

An animal that has relevance to the care process -usually this is for animals that are patients..

The resource name as it appears in a RESTful URL (§2.1) is /animal/

3.2.1: Resource Content

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

<Animal xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Master Resource Id, always first in all resources --></id>
 <identifier d?><!-- 0..* HumanId Human identifiers for this animal --></identifier>
 <name d?><!-- 0..* HumanName A name associated with the animal --></name>
 <dob d?><!-- 0..1 dateTime The birth date for the animal --></dob>
 <species d?><!-- 0..1 CodeableConcept Species for the Animal --></species>
 <strain d?><!-- 0..1 CodeableConcept Strain for the Animal --></strain>
 <gender d?><!-- 0..1 CodeableConcept Gender for the Animal --></gender>
 <relatedEntity>  <!-- 0..* Kin, owner, care giver etc -->
  <identifier d?><!-- 0..1 HumanId Identifier for the entity --></identifier>
  <role><!-- 1..1 CodeableConcept Type of relationship --></role>
  <name d?><!-- 0..1 HumanName Name of the related entity --></name>
  <address d?><!-- 0..* Address An address (usually human, but may be kin) --></address>
  <contact d?><!-- 0..* Contact Contact details (usually for humans) --></contact>
 </relatedEntity>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of animal, fall back for human interpretation --></text>
</Animal>

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

Terminology Bindings

• Animal.species has the definition AnimalSpecies: "The species of an animal"
• Animal.strain has the definition AnimalStrain: "The strain of an animal"
• Animal.gender has the definition AnimalGender: "The gender of an animal"
• Animal.relatedEntity.role has the definition AnimalRelationship: "The relationship of an animal to another entity (person, corporation, or other animal)"

Notes:

• Animals are assigned human names, since humans tend to assign names using human patterns.
• Related entities include owners, and care givers, as well as the kin of the animal should that be relevant.
• The organization references are all optional, so can be replaced by simple text rather than a full resource reference
• The organization references are all optional, so can be replaced by simple text rather than a full resource reference
• A related entity can be either reference to another resource using the id, or can provide what is known about the entity directly

3.2.2: Search Parameters

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

(See Searching (§2.1.12)).

3.3: Resource Definition: AssessmentScale

Status: A domain resource being developed in association with the Patient Care work group to investigate FHIR. Not an approved resource

Assessment scales or scores combine the findings of individual values into a total score which can be interpreted more easily against a reference population.

The resource name as it appears in a RESTful URL (§2.1) is /assessmentscale/

3.3.1: Resource Content

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

<AssessmentScale xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Master Id, first in all resources --></id>
 <subject><!-- 1..1 Resource(Patient) Who the assessment score is about --></subject>
 <performer><!-- 1..1 Resource(Agent|Person) Who performed the assessment --></performer>
 <time><!-- 1..1 dateTime When the assessment was finalized --></time>
 <definition d?><!-- 0..1 Resource(AssessmentDefinition) Details of how assessment was performed --></definition>
 <interpretation d?><!-- 0..* CodeableConcept What the value of the assessment means --></interpretation>
 <score>  <!-- The actual score -->
  <code><!-- 1..1 CodeableConcept Indicates the type of assessment --></code>
  <value[x]><!-- 0..1 Quantity|CodeableConcept|Choice|boolean Outcome of the assessment --></value[x]>
  <score d?><!-- 0..* Content as for AssessmentScale.score Nested Score elements --></score>
  <measure>  <!-- 0..* Data from which the score is derived -->
   <code><!-- 0..1 CodeableConcept What this value represents --></code>
   <value[x] d?><!-- 0..1 Quantity|CodeableConcept|Choice|boolean actual value --></value[x]>
   <time d?><!-- 0..1 dateTime when the value was measured --></time>
   <source d?><!-- 0..1 Resource(Any) source reference for further information --></source>
  </measure>
 </score>
 <reason d?><!-- 0..1 string why the assessment was performed --></reason>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of [template] for human interpretation --></text>
</AssessmentScale>

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

Terminology Bindings

• AssessmentScale.score.code has the definition AssessmentScaleType: "A code that identifies the assessment scale that was performed". A good candidate for codes is Loinc Observables that identify scales
• AssessmentScale.score.measure.code has the definition AssessmentScaleMeasure: "Identifies the type of measure". A good candidate for codes is Loinc Observables

Constraints

• A score may have a value and/or one (and only one) of measure or sub-scores (xpath on /score: (exists(f:*[starts-with(local-name(.), 'value')]) or exists(f:measure) != exists(f:score)) and not (exists(f:measure) and exists(f:score)))

Notes:

• Note here

3.3.2: Search Parameters

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

(See Searching (§2.1.12)).

3.4: Resource Definition: LabReport

Status: A domain resource developed as an exmplar - based on the NEHTA peEHR model (Australia) (= openEHR archetype for lab report). Not an approved resource. Under consideration by the Orders and Observations work group

The findings and interpretation of pathology tests performed on tissues and body fluids. This is typically done in a laboratory but may be done in other environments such as at the point of care.

The resource name as it appears in a RESTful URL (§2.1) is /labreport/

3.4.1: Resource Content

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

<LabReport xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Master Resource Id, always first in all resources --></id>
 <status><!-- 1..1 code registered|interim|final|amended|cancelled|withdrawn --></status>
 <issued><!-- 1..1 instant date issed for current status --></issued>
 <patient><!-- 1..1 Resource(Patient) The patient the report is about --></patient>
 <admission d?><!-- 0..1 Resource(Admission) Admission Context --></admission>
 <laboratory><!-- 1..1 Resource(Organization) Responsible Laboratory --></laboratory>
 <reportId><!-- 0..1 Identifier Id for external references to this report --></reportId>
 <requestDetail>  <!-- 0..* What was requested -->
  <requestOrderId d?><!-- 0..1 Identifier Id assigned by requester --></requestOrderId>
  <receiverOrderId d?><!-- 0..1 Identifier Receiver's Id for the request --></receiverOrderId>
  <requestTest d?><!-- 0..* CodeableConcept Test Requested --></requestTest>
  <requester d?><!-- 0..1 Resource(Agent|Organization) Responsible for request --></requester>
  <clinicalInfo d?><!-- 0..1 Resource(Any) Clinical information provided --></clinicalInfo>
 </requestDetail>
 <reportName><!-- 1..1 CodeableConcept Name for the entire report --></reportName>
 <service d?><!-- 0..1 CodeableConcept Biochemistry, Haematology etc --></service>
 <diagnosticTime><!-- 1..1 dateTime Effective time of diagnostic report --></diagnosticTime>
 <specimen d?><!-- 0..* Resource(Specimen) Specimen (incl. time of collection) --></specimen>
 <resultGroup>  <!-- 0..* Results grouped by specimen/kind/category -->
  <name d?><!-- 0..1 CodeableConcept What defines the group --></name>
  <specimen d?><!-- 0..1 Resource(Specimen) Specimen details --></specimen>
  <result>  <!-- 1..* A particular result -->
   <name><!-- 0..1 CodeableConcept Name or code of the result --></name>
   <value[x] d?><!-- 0..1 Quantity|CodeableConcept|Attachment|
              Ratio|Choice|Period|string Result. [x] = type name --></value[x]>
   <flag><!-- 0..1 code + | ++ | +++ | - | -- | ---  --></flag>
   <status><!-- 1..1 code Registered|Interim|Final|Amended|Cancelled|Withdrawn --></status>
   <comments d?><!-- 0..1 string Comments about result --></comments>
   <referenceRange>  <!-- 0..* Guide for interpretation -->
    <meaning d?><!-- 0..1 CodeableConcept The meaning of this range --></meaning>
    <range[x]><!-- 1..1 Quantity|Range|string Reference --></range[x]>
   </referenceRange>
  </result>
 </resultGroup>
 <conclusion d?><!-- 0..1 string Clinical Interpretation of test results --></conclusion>
 <codedDiagnosis d?><!-- 0..* CodeableConcept Codes for the conclusion --></codedDiagnosis>
 <representation><!-- 0..* Attachment Entire Report as issued --></representation>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of report, for human interpretation --></text>
</LabReport>

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

Terminology Bindings

• LabReport.status and LabReport.resultGroup.result.status share the definition LabReportStatus: "The status of a report or result item". Possible values:

  registered	The existence of the result is registered, but there is no result yet available
  interim	This is an initial or interim result: data may be missing or verification not been performed
  final	The result is complete and verified by the responsible pathologist
  amended	The result has been modified subsequent to being Final, and is complete and verified by the responsible pathologist
  cancelled	The result is unavailable because the test was not started or not completed (also sometimes called "aborted")
  withdrawn	The result has been withdrawn following previous Final release

• LabReport.requestDetail.requestTest has the definition LabRequests: "codes for requestable tests"
• LabReport.reportName has the definition LabReportNames: "codes for report names". If an appropriate code exists in LOINC Panel Names then it should be used
• LabReport.service has the definition LabServices: "codes for laboratory services". If an appropriate code exists in HL7 v2 table 0074 then it should be used
• LabReport.resultGroup.name has the definition LabResultGroupNames: "codes for result groups". If an appropriate code exists in LOINC Panel Names then it should be used
• LabReport.resultGroup.result.name has the definition LabResultNames: "codes for results". If an appropriate code exists in LOINC Result names then it should be used
• LabReport.resultGroup.result.value[x] has the definition (Error!!!)
• LabReport.resultGroup.result.flag has the definition LabResultFlag: "codes for result flags". Possible values:

  -
  --
  ---
  +
  ++
  +++
  R	Resistent
  S	Moderately Susceptible
  SS	Very Susceptible

• LabReport.resultGroup.result.referenceRange.meaning has the definition LabReferenceRanges: "Code for the meaning of a reference range"
• LabReport.codedDiagnosis has the definition LabDiagnosisCodes: "Codes for laboratory diagnoses". A good candidate for codes is SNOMED-CT Diagnoses

3.4.2: Search Parameters

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

(See Searching (§2.1.12)).

3.5: Resource Definition: Organization

Status: A domain resource developed as an examplar. Not an approved resource. Under consideration by the Patient Admin work group

For any company/corporation/institution/government department that has relevance to the care process.

The resource name as it appears in a RESTful URL (§2.1) is /organization/

3.5.1: Resource Content

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

<Organization xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Master Resource Id, always first in all resources --></id>
 <identifier d?><!-- 0..* HumanId Identifier for this organization --></identifier>
 <name>  <!-- 0..* name used for the organisation -->
  <value><!-- 1..1 string A name associated with the organization --></value>
  <period d?><!-- 0..1 Period When this name is/was in use (date only) --></period>
 </name>
 <address d?><!-- 0..* Address An address for the organization --></address>
 <contact d?><!-- 0..* Contact A contact detail for the organization --></contact>
 <code d?><!-- 0..1 CodeableConcept kind of organisation --></code>
 <industryCode d?><!-- 0..1 CodeableConcept kind of industry --></industryCode>
 <accreditation>  <!-- 0..* formal certifications that convey authority -->
  <identifier d?><!-- 0..1 Identifier Identifier for the accreditation --></identifier>
  <code d?><!-- 0..1 CodeableConcept What kind of accreditation --></code>
  <institution d?><!-- 0..1 Resource(Organization) Who conferred it --></institution>
  <period d?><!-- 0..1 Period When the accreditation is valid (date only) --></period>
 </accreditation>
 <relatedOrganization>  <!-- 0..* sub-, super-, and partner organisations -->
  <identifier d?><!-- 0..1 HumanId Identifier for the organization --></identifier>
  <code><!-- 1..1 CodeableConcept How the organizations are related --></code>
  <name d?><!-- 0..1 string Name of the organization --></name>
  <address d?><!-- 0..* Address An address for the organization --></address>
  <contact d?><!-- 0..* Contact General contact details for the organization --></contact>
  <period d?><!-- 0..1 Period When the organizations were related (date only) --></period>
 </relatedOrganization>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of organization, fall back for human interpretation --></text>
</Organization>

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

Terminology Bindings

• Organization.code has the definition OrganisationType: "The type of an organisation". A good candidate for codes is SNOMED-CT Organisation codes and the HL7 v3 Entity Code table
• Organization.industryCode has the definition Industry: "Code for the type of industry". If an appropriate code exists in HL7 v3 OrganizationIndustryClass value set then it should be used
• Organization.accreditation.code has the definition Accreditation: "Accreditations an organization may be granted"
• Organization.relatedOrganization.code has the definition OrganizationRelationship: "The relationship an organization has to the subject, including sub and super organizations, and other kind of relationships such as partner organisations"

Notes:

• The organization references are all optional, so can be replaced by simple text rather than a full resource reference

3.5.2: Search Parameters

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

(See Searching (§2.1.12)).

3.6: Resource Definition: Patient

Status: A domain resource developed as an examplar. Not an approved resource. Under consideration by the Patient Admin work group

A patient is a person or animal that is receiving care.

The resource name as it appears in a RESTful URL (§2.1) is /patient/

3.6.1: Resource Content

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

<Patient xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Master Resource Id, always first in all resources --></id>
 <link><!-- 0..* Resource(Patient) Other patients linked to this resource --></link>
 <active><!-- 1..1 boolean Whether this patient record is active (in use) --></active>
 <subject><!-- 1..1 Resource(Person|Animal) The person or animal that is the patient --></subject>
 <provider><!-- 1..1 Resource(Organization) Organization managing the patient --></provider>
 <identifier d?><!-- 0..* HumanId An identifier for the person as this patient --></identifier>
 <diet d?><!-- 0..1 CodeableConcept Dietary restrictions for the patient --></diet>
 <confidentiality d?><!-- 0..1 CodeableConcept Confidentiality of the patient records --></confidentiality>
 <recordLocation d?><!-- 0..1 CodeableConcept Where the paper record is --></recordLocation>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of person, for human interpretation --></text>
</Patient>

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

Terminology Bindings

• Patient.diet has the definition PatientDiet: "casual dietary restrictions associated with this patient"
• Patient.confidentiality has the definition PatientConfidentiality: "The confidentiality of the records associated with this patient"
• Patient.recordLocation has the definition PaperRecordLocation: "A physical location for a record. (Usually site specific)"

Notes:

• Links: linking patient records is an assertion that they both are about the same actual person. If any patient record is linked to another, then the other must be linked back to the source record. Ensuring that the links are in agreement across the patient resources in a RESTful contexts is the responsibility of the server: it must modify the referenced resources whenever a change the links on any patient is updated. In a messaging context, patient links SHALL only be updated though the link/unlink events
• The patient may be a person or an animal (in order to support vetinary medicine). Either a person or an animal resource link must be provided, but not both.
• The dietary restrictions are not for specifying medical diets, but for casual dietary restrictions such as vegetarian, diary-free, nut-free, etc

3.6.2: Managing Patient Registration

Managing Patient registration is a well known difficult problem. Around 2% of registrations are in error, mostly duplicate records. Sometimes the duplicate record is caught fairly quickly and retired before much data is accumulated. In other cases, substantial amounts of data may accumulate. For these and other reasons, the identifiers associated with a patient may change over time.

The master identifier for the Patient Resource can never change. For this reason the identifiers with which humans are concerned (often called MRN - Medical Record Number, or UR - Unit Record) should not be used as the master identifier. Instead they should be represented in the Patient.identifier list where they can be managed. This is also useful for the case of institutions that have acquired multiple numbers because of mergers of patient record systems over time.

In this specification, patient records are never merged. If multiple patient records are found to be duplicates, they are linked. In a RESTful context, this is done using the "link patients" transaction described below. In other contexts, equivalent functionality will be needed. When patient resources are linked, one may be chosen as the "master" - the correct record. In this case, the active status of all the other resources is set to false, and all the content is moved to the active record by updating it directly.

Patient records may only be in one of two statuses: active and retired. A normal record is active - it is in use. The status retired is used when a record is created in error. Once the error is discovered, it can either be retired or deleted. A record does not need to be linked to be retired.

3.6.3: RESTful Transactions

The patient resource type defines one special transaction provided by the patient manager: "Link" for linking resources. The reason is that linking records is effectively a transaction that involves at least two resources, and all or none must change. Since the transaction involves multiple resources, it is implemented on the resource manager as a POST to [todo]

There is no content model for the response, except for an HTTP status code.

3.6.4: Search Parameters

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

(See Searching (§2.1.12)).

3.7: Resource Definition: Person

Status: A domain resource developed as an examplar. Not an approved resource. Under consideration by the Patient Admin work group

A person who is involved in the healthcare process.

The resource name as it appears in a RESTful URL (§2.1) is /person/

3.7.1: Resource Content

See also the Examples (§4.13) and the Definitions (§5.14).

<Person xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Master Resource Id, always first in all resources --></id>
 <identifier d?><!-- 0..* HumanId A Human identifier for this person --></identifier>
 <name d?><!-- 0..* HumanName A name associated with the person --></name>
 <address d?><!-- 0..* Address An address for the person --></address>
 <contact d?><!-- 0..* Contact A contact detail for the person --></contact>
 <dob d?><!-- 0..1 dateTime The birth date for the person --></dob>
 <gender d?><!-- 0..1 CodeableConcept Administrative Gender --></gender>
 <religion d?><!-- 0..1 CodeableConcept Religion of the person --></religion>
 <race d?><!-- 0..* CodeableConcept The race of a person --></race>
 <qualification>  <!-- 0..* Qualifications, Accreditations, Certifications -->
  <identifier d?><!-- 0..1 Identifier Identifier for the qualification --></identifier>
  <code d?><!-- 0..1 CodeableConcept A code for the qualification --></code>
  <institution d?><!-- 0..1 Resource(Organization) Who conferred it --></institution>
  <period d?><!-- 0..1 Period When the qualification is valid (date only) --></period>
 </qualification>
 <language>  <!-- 0..* language (with proficiency) -->
  <code><!-- 1..1 code ISO 639-3 code for language --></code>
  <use d?><!-- 0..1 code How well the language is used --></use>
 </language>
 <relatedPerson>  <!-- 0..* Kin, Guardians, Agents, Caregivers -->
  <identifier d?><!-- 0..1 HumanId Identifier for the person --></identifier>
  <role><!-- 1..1 CodeableConcept Type of relationship --></role>
  <name d?><!-- 0..1 HumanName Name of the person --></name>
  <contact d?><!-- 0..* Contact Contact details for the person --></contact>
 </relatedPerson>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of person, for human interpretation --></text>
</Person>

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

Terminology Bindings

• Person.gender has the definition AdministrativeGender: "The gender of a person used for administrative purposes "
• Person.religion has the definition Religion: "The denomination to which a person professes affiliation "
• Person.race has the definition Race: "The race of the person". If an appropriate code exists in HL7 v2 table 0200 then it should be used
• Person.qualification.code has the definition Qualifications: "Formal qualifications, accreditations, and Certifications acquired by a person "
• Person.language.code has the definition Language: "A human language". For example values, see ISO 639-3 (http://www.sil.org/iso639-3/codes.asp)
• Person.language.use has the definition LanguageUse: "How well a person speaks a language". Possible values:

  none	The person does not speak the language at all
  poor	The person has minimal functional capability in the language
  useable	The person can use the language, but may not be full conversant, particularly with regards to health concepts
  fluent	The person is fully capable of using the language

• Person.relatedPerson.role has the definition PersonRelationship: "The relationship a person has to the subject, including familial, marital, financial, legal, and casual relationships "

Notes:

• There are various types of people of interest - patients, employees, etc. Different types of people might come from different service end points.
• The administrative gender of the patient is that one that matters for the record. This may match the gendor of birth or the current socially-reported gender.
• Qualifications covers both formal education gained in the past, and ongoing certification and accreditation often associated with healthcare providers.
• Various jurisdictions define their own qualification and/or codes, and some care about this more than others.
• The organization references are all optional, so can be replaced by simple text rather than a full resource reference
• A related person can be either reference to another resource using the id, or can provide what is known about the person directly

3.7.2: Search Parameters

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

(See Searching (§2.1.12)).

3.8: Resource Definition: Prescription

Status: A domain resource developed as an exmplar - based on the NICTIZ national model(The Netherlands). Not an approved resource. Under consideration by the pharmacy work group

Directions provided by a prescribing practitioner for a specific medication to be administered (and possibly) supplied to an individual.

The resource name as it appears in a RESTful URL (§2.1) is /prescription/

3.8.1: Resource Content

See also the Examples (§4.14) and the Definitions (§5.15).

<Prescription xmlns="http://hl7.org/fhir">
 <id><!-- 1..1 id Master Resource Id, always first in all resources --></id>
 <identifier><!-- 0..* HumanId Prescription identification --></identifier>
 <status><!-- 1..1 code Status: Active|Completed --></status>
 <patient><!-- 1..1 Resource(Patient) Patient receiving medicine --></patient>
 <prescriber><!-- 1..1 Resource(Agent) Prescribing doctor --></prescriber>
 <prescribed><!-- 1..1 dateTime Date/time prescribed --></prescribed>
 <dispense>  <!-- Details of included dispense request -->
  <repeats><!-- 0..1 integer Number of repeats --></repeats>
  <quantity><!-- 1..1 Quantity Quantity per repeat --></quantity>
  <dispenser d?><!-- 0..1 Resource(Agent|Organization) Person to fullfil the requested dispense --></dispenser>
 </dispense>
 <medicine>  <!-- Prescribed medicine -->
  <identification d?><!-- 0..1 CodeableConcept Test and/or code(s) for medicine --></identification>
  <activeIngredient>  <!-- 0..* Active substance -->
   <identification d?><!-- 1..1 CodeableConcept Text and/or Code(s) for active ingredient --></identification>
   <quantity[x] d?><!-- 0..1 Ratio|code Relative quantity of active ingredient --></quantity[x]>
  </activeIngredient>
  <inactiveIngredient>  <!-- 0..* Inactive substance -->
   <identification d?><!-- 1..1 CodeableConcept Text and/or Code(s) for inactive ingredient --></identification>
   <quantity[x] d?><!-- 0..1 Ratio|code Relative quantity of inactive ingredient --></quantity[x]>
  </inactiveIngredient>
 </medicine>
 <administrationRequest>  <!-- Instructions for use -->
  <description d?><!-- 0..1 string Textual instructions for use --></description>
  <totalPeriodicDosis d?><!-- 0..1 Ratio Total periodic dosis --></totalPeriodicDosis>
  <start d?><!-- 0..1 dateTime Startdate for administration --></start>
  <end d?><!-- 0..1 dateTime Enddate for administration --></end>
  <duration d?><!-- 0..1 Quantity Total duration of administration --></duration>
  <numberOfAdministrations d?><!-- 0..1 integer Maximum number of separate administrations --></numberOfAdministrations>
  <dosageInstruction>  <!-- 1..* Dosage instruction -->
   <precondition d?><!-- 0..* CodeableConcept Precondition for starting administration --></precondition>
   <prn><!-- 0..1 boolean Pro re nate: Yes|No --></prn>
   <additionalInstruction d?><!-- 0..* CodeableConcept Additional instructions --></additionalInstruction>
   <route d?><!-- 0..1 CodeableConcept Route of administration --></route>
   <dose[x]><!-- 1..1 Quantity|Range Dose per administration --></dose[x]>
   <rate d?><!-- 0..1 Quantity Flow-rate for IV --></rate>
   <schedule><!-- 1..* Schedule Schedule for administration --></schedule>
  </dosageInstruction>
 </administrationRequest>
 <reason d?><!-- 0..1 CodeableConcept Reason for prescription --></reason>
 <extension><!-- 0..* Extension  See Extensions  --></extension>
 <text><!-- 1..1 Narrative Text summary of the prescription, for human interpretation --></text>
</Prescription>