This page is part of the FHIR Specification (v0.0.82: DSTU 1). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

1.12.5.1 XML

The XML syntax is closely based on the XML notation:

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

Notes:

• To build a valid XML instance of a resource, simply replace the contents of the elements and attributes with valid content as described by the cardinality, type rules and content description found in the comment in each element
• Resource and Element names are case-sensitive (though duplicates that differ only in case are never defined)
• Note that the only properties that are represented as attributes are those defined in underlying specifications such as Atom (see below), which is used as the XML representation for bundles, and attributes are also used for primitive values
• FHIR elements are always in the namespace http://hl7.org/fhir. This is usually specified as the default namespace on the root element. The only other namespaces that occur in FHIR resources are where some external content model is explicitly introduced into the resource content model. For example, XHTML is found in every resource
• Any of the XML elements may have an id attribute to serve as the target of an internal reference. The id attribute is not shown in this format
• FHIR elements are never empty. If an element is present in the resource, it SHALL have either a value attribute, child elements as defined for its type, an id attribute that is the link target of narrative, or 1 or more extensions
• Attributes can never be empty. Either they are absent, or they are present with at least one character of non-whitespace content
• XML comments, processing instructions and formatting are not part of the contents of a resource.
• Specifying the character encoding using a <?xml encoding="" ?> processing instruction is optional but recommended. Other processing Instructions SHOULD not be included, except and SHALL not be required in order to properly understand and/or present the data or narrative of the resource. Applications MAY preserve these when handling resources, but are not required to do so. Note that digital signatures may depend on them (depending on the canonicalization method used)

When represented as XML, resources may be validated by schema and schematron (see below), but operational systems are not required to do so (though the XML SHALL always be valid against this specification and the schema and Schematron).

1.12.5.1.1 Atom Bundle Representation

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

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

1.12.5.1.1.1 Notes

• Logically, a bundle is a set of resources that are prepared to be sent somewhere for consumption - a "feed"
• The order of elements does not matter in an atom feed (but not entries: the order of the entries is important and may have some meaning associated with it). The order of elements in the atom namespace as documented above does not need to be followed, though it is followed by the FHIR reference platforms
• The title for the feed and the entry are arbitrary human-readable content. The title of the entry SHOULD be derived from information present in the resource itself. Systems may ignore content present in the title
• Every bundle SHALL have a unique id and that id SHALL be a valid absolute uri. UUIDs are recommended (urn:uuid:...)
• The entry element carries the three pieces of resource metadata: Id (.id), Version Id (.link), Last Updated (.updated)
• Each entry also carries all the Tags affixed to the resource in the category element. The category element can be used in other ways too
• The entry.id SHALL be an absolute URL, the tail element of which is the logical id of the resource. The id is a version independent reference
• The entry.link to self is a version specific reference to the resource.
• When used in a RESTful implementation, the entry.link and entry.id are the URLs of the resource on the system; the version specific link can be used as the basis synchronizing pub/sub systems using the atom bundle with the updates operation. In other contexts, the values should be literal references to a server if one is available
• Note that the atom specification requires a known author for every entry. If an author is provided in the base feed element, a specific author is not needed on each entry
• The author of a resource is not explicit in the FHIR resource model; instead it is delegated to the infrastructure. The name is the name of a human author or a device. The uri is a link to the author (possibly a Practitioner resource)
• xml:base elements SHOULD NOT be used and implementations do not need to support it
• The entry.content is optional, but SHALL always be present except in the special case of a transaction response
• The entire bundle can be signed with a single Enveloped Digital Signature as described in the Atom specification (section 5.1)
• The feed.link element with relationship "self" is assigned no particular meaning the FHIR specification, except in the case of a search operation, but may be used to provide a reference to the source of the feed
• The feed.link elements with relationship "first", "last", "previous" and "next" are used to implement paging in the RESTful interface and allow a client to browse through a multi-page result. See search/query
• The feed.link element "fhir-base" is used to resolve relative urls in a bundle, see relative references

1.12.5.1.1.2 Bundling versions - deletion

When returning a set of resources or versions of a resource, an entry might indicate that the entry has been deleted. Deleted resources are represented in an atom feed as defined by rfc6721.txt:

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

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

1.12.5.1.2 Implementation Notes

• Atom Feeds may be signed following the rules described in the Atom specification. One consequence of signing the document is that URLs, identifiers and internal references are frozen and cannot be changed. This might be a desired feature, but it may also cripple interoperability between closed ecosystems 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. These id attributes are unique and resolved within the context of a single resource. When resources are combined into a bundle, different resources may contain duplicate id attributes. Thus it is important to limit the scope of resolution of an id attribute to the resource in which the id attribute is declared.

1.12.5.1.2.1 Binary Resources

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

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

Binary resources can also be embedded as contained resources. If there is a desire to capture metadata about a binary object, an appropriate resource type must be used such as DocumentReference or Media.

1.12.5.1.3 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 SHALL be valid against the w3c schema and Schematron, though being valid against the schema and Schematron is not sufficient to be a conformant instance: this specification makes several rules that cannot be checked by either mechanism. Exchanged content SHALL not specify the schema or even the schema instance namespace in the resource itself.