This page is part of the FHIR Specification (v0.0.82: (v1.0.2: DSTU 1). 2). 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

• Formats
• XML
• JSON
• RDF

1.12.5.1 1.18.1 XML Representation of Resources

Implementable Technology Specifications Work Group

Maturity Level : 5

Ballot Status : DSTU 2

Implementers should be alert to the security ramifications of possible mis-use of the XML entities. See OWASP or Wikipedia for details. HL7 recommends that implementers configure their parsers to ignore XML entities, and the implementers do not produce resources that contain XML entities other than those defined in the XML standard itself. Future versions of the FHIR specification will make this a mandatory requirement.

The XML syntax representation for a resource is closely based on the XML notation : described using this format:

 <
   <<nameA>
   <</nameB>

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

     <nameD><!-- 1..1 type>Relevant elements  --></nameD>

   </nameC>
 <name>

Notes: Using this format:

• 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 Elements must always appear in the only order documented
• When an element is allowed to repeat, the elements are ordered, and implementations must preserve order (note: the meaning of the order may not be known)
• A few properties that are represented as attributes are those defined attributes: primitive values in underlying specifications such as Atom (see below) , which is used as the XML representation for bundles, value attribute, extension URLs in the url attribute on an extension, and attributes are also used for primitive values the id property
• 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 always in the namespace http://hl7.org/fhir . This is usually specified as the default namespace on the root element. The only other namespaces namespace that occur occurs in FHIR resources are where some external content model is explicitly introduced into the resource content model. For example, XHTML namespace ( XHTML is found in every resource most resources)
• Any of the XML Infrastructural elements may have an id attribute that are common to serve as the target of an internal reference . The id attribute is all resources are not shown in this format the xml representation. These must appear prior to any other defined child elements in the following order:
  • First, the elements from the base resource , in order
  • Second, the elements from the domain resource , in order
• 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
• Implementers SHOULD trim leading and trailing whitespace before writing and SHOULD trim leading and trailing whitespace when reading attribute values
• The lock icon ( ) denotes that an element defines or is affected by additional rules that control its presence and/or content
• XML comments, processing instructions and formatting are not part of the contents of a resource. resource
• XML resources SHALL be exchanged using UTF-8 encoding. Specifying the character encoding using a <?xml encoding="" encoding="UTF-8" ?> processing instruction is optional but recommended. recommended
• Other processing Instructions instructions SHOULD not be included, except and SHALL not NOT be required in order to properly understand and/or present the data or narrative of the resource. Applications MAY preserve these processing instructions 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></title> <id></id> <link rel="self" href=" <link rel="first" href=" <link rel="previous" href=" <link rel="next" href=" <link rel="last" href=" <link rel="fhir-base" href=" <os:totalResults xmlns:os="http://a9.com/-/spec/opensearch/1.1/"> Paging: the total number of results</os:totalResults> <updated></updated> <author> <name></name> <uri></uri> </author> <entry> <title></title> <id></id> <link rel="self" href="</link> <updated></updated> <published></published> <author> <name></name> <uri></uri> </author> <category term=" <content type="text/xml"> < xmlns="http://hl7.org/fhir"> </> </content> <summary type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml"></div> </summary> </entry> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> </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 MIME-type 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"> <at:deleted-entry xmlns:at="http://purl.org/atompub/tombstones/1.0" ref=""> <link rel="self" href="</link> </at:deleted-entry> 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 format is declared. application/xml+fhir .

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=" </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 1.18.1.1 XML Schema and Schematron

This specification provides schema definitions for all of the content models described here. it describes.

The base schema is called " fhir-base.xsd " and defines all of the datatypes and also the base infrastructure types described on this page. types. 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 For schema fhir-atom.xsd processors that do not like circular includes, there is provided for validating bundles . a single schema that contains everything.

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

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. Operational systems may choose to use schema tools to check validation, but are not required to do so. Exchanged content SHALL not NOT specify the schema or even contain the schema instance namespace in the resource itself.

Given the way extensions work, applications reading XML resources will never encounter unknown elements. However once an application starts trading with other appplications that conform to later versions of this specification, unknown XML elements may be encountered. Applications MAY choose to ignore unknown elements in order to foster forwards compatibility in this regard, but may also choose not to - which would be the normal behavior for schema generated applications. Applications declare their behavior with regard to unknown elements using Conformance.acceptUnknown .

1.18.1.2 Code Generation Schema

In addition to the validation schema, this specification provides a set of schema suitable for code generation. These schema describe the same XML syntax, but apply less validation in order to create a schema that works with more code generation tooling.

Specifically, these schemas are generated without any xsd:choice elements, for code generators that don't deal with choices well. Implementers that use these schemas will need to enforce the correct usage of the choice elements without schema support.

Implementers making use of schema driven code generation tooling need to consider how to handle the decimal data type. The decimal data type is defined to be precision aware - that is, that implementers need to preserve the difference between "2.0" and "2.00" - this is ubiquitiously considered important in handling observed data in healthcare. Both schemas map this data type to xsd:decimal , but the base W3C schema decimal type is specified not to be precision aware. Schema driven implementations vary as to how precision is handled, and implementers will need to determine how their generated code handles decimals, and consider changing the type for decimal in the schema from xsd:decimal to xsd:string . Specifically, implementers may wish to change

  <xs:simpleType name="decimal-primitive">
    <xs:restriction base="xs:decimal">
      <xs:pattern value="-?([0]|([1-9][0-9]*))(\.[0-9]+)?"/>
    </xs:restriction>
  </xs:simpleType>

to this:

  <xs:simpleType name="decimal-primitive">
    <xs:restriction base="xs:string">
      <xs:pattern value="-?([0]|([1-9][0-9]*))(\.[0-9]+)?"/>
    </xs:restriction>
  </xs:simpleType>

Alternatively, if supported, implementers may wish to use the precisionDecimal from the XSD 1.1 framework.

Note that most code generation frameworks ignore the pattern restriction.

1.18.1.3 Canonical XML

Resources and/or Bundles may be digitally signed (see Bundle and Provenance ).

This specification defines the following method for canonicalizing FHIR resources, when represented as xml:

• No whitespace other than single spaces in attribute values and in the xhtml in the Narrative
• Use default namespaces for the FHIR and XHTML namespaces
• Omit all elements that have a default value, if a default value is defined
• Omit all comments
• Always use the unicode character representation for any XML entities (e.g. ' instead of " )
• Include the XML processing instruction <?xml version="1.0" encoding="UTF-8"?>
• Using the XML canonical method Canonical XML 1.1 ( http://www.w3.org/2006/12/xml-c14n11 )

This canonicalization method is identified by the URL http://hl7.org/fhir/canonicalization/xml . The following additional canonicalization URLS are also defined:

http://hl7.org/fhir/canonicalization/xml#data	The narrative ( Resource.text ) is omitted prior to signing (note the deletion is at Resource.text , not Resource.text.div )
http://hl7.org/fhir/canonicalization/xml#static	In addition to narrative (Resource.text), the Resource.meta element is removed. This makes the signature robust as the content is moved from server to server, or workflow and access tags are added or removed
http://hl7.org/fhir/canonicalization/xml#narrative	The method only covers the Resource.id and Narrative is retained

These canonicalization methods allow system the flexibility to sign the various portions of the resource that matter for the workflow the signature serves.

Note: 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 systems consider carefully the impact of any signature processes. The impact of signatures on Document bundles and their related processes is the most well understood use of digital signatures.