DSTU2 STU 3 Candidate
This page is part of the FHIR Specification (v1.0.2: DSTU 2). The current version which supercedes this version is

This page is part of the FHIR Specification (v1.4.0: STU 3 Ballot 3). The current version which supercedes this version is 5.0.0 . For a full list of available versions, see the Directory of published versions . For a full list of available versions, see the Directory of published versions . Page versions: . Page versions: R5 R4B R4 R3 R2

1.18.1 1.17.1 XML Representation of Resources XML Representation of Resources

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 representation for a resource is described using this format:
Implementable Technology Specifications Implementable Technology Specifications Work Group Work Group Maturity Level : 5 Maturity Level : 5 Ballot Status : DSTU 2 Ballot Status : DSTU 2

The XML representation for a resource is described using this format: 

 <name xmlns="http://hl7.org/fhir" (attrA="value")>   doco
   <nameA><!-- ?? 1..1 type description of content  --><nameA>
   <nameB[x]><!-- 0..1 type1|type1 description  --></nameB>
   <nameC> <!--  1..* -->
     <nameD><!-- 1..1 type>Relevant elements  --></nameD>
   </nameC>
 <name>
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)
Elements
must
always
appear
in
the
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
are
represented
as
attributes:
primitive
values
in
the

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)
  • Elements must always appear in the 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 are represented as attributes: values of primitive types in a value attribute, extension URLs in the attribute, extension URLs in the url attribute on an extension, and the id property Any of the XML elements may have an id attribute to serve as the target of an internal reference . The attribute on an extension, and the id attribute is not shown in this format FHIR elements are always in the namespace http://hl7.org/fhir property on elements (but not on resources, where the resource id is an element)
  • 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 namespace that occurs in FHIR resources is the XHTML namespace ( . This is usually specified as the default namespace on the root element. The only other namespace that occurs in FHIR resources is the XHTML namespace ( XHTML is found in most resources) XHTML is found in most resources) Infrastructural elements that are common to all resources are not shown in 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, or 1 or more
  • Infrastructural elements that are common to all resources are not shown in the xml representation. These must appear prior to any other defined child elements in the following 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, 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 (
  • 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 XML resources SHALL be exchanged using UTF-8 encoding. Specifying the character encoding using a <?xml encoding="UTF-8" ?> processing instruction is optional but recommended Other processing instructions SHOULD not be included, and SHALL NOT be required in order to properly understand and/or present the data or narrative of the resource. Applications MAY preserve processing instructions when handling resources, but are not required to do so The MIME-type for this format is ) 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
  • XML resources SHALL be exchanged using UTF-8 encoding. Specifying the character encoding using a <?xml encoding="UTF-8" ?> processing instruction is optional but recommended
  • Other processing instructions SHOULD not be included, and SHALL NOT be required in order to properly understand and/or present the data or narrative of the resource. Applications MAY preserve processing instructions when handling resources, but are not required to do so
  • The MIME-type for this format is application/xml+fhir .

1.18.1.1 XML Schema and Schematron 1.17.1.1 XML Schema and Schematron This specification provides schema definitions for all of the content models it describes. The base schema is called "

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

The base schema is called " fhir-base.xsd " and defines all of the datatypes and base infrastructure types. In addition, there is a schema for each resource and a common schema " and defines all of the datatypes and base infrastructure types. In addition, there is a schema for each resource and a common schema fhir-all.xsd that includes all the resource schemas. For schema processors that do not like circular includes, there is 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. 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 specify the schema or even contain the schema instance namespace in the resource itself. Given the way that includes all the resource schemas. For schema processors that do not like circular includes, there is 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.

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

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 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 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 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 , 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 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 to xsd:string . Specifically, implementers may wish to change . 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:

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

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. from the XSD 1.1 framework.

Note that most code generation frameworks ignore the pattern restriction.

1.18.1.3 Canonical XML 1.17.1.3 Canonical XML Resources and/or Bundles may be digitally signed (see

Resources and/or Bundles may be digitally signed (see Bundle and 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 ).

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.
  • 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. &#39; instead of instead of &quot; ) Include the XML processing instruction <?xml version="1.0" encoding="UTF-8"?>
  • Include the XML processing instruction <?xml version="1.0" encoding="UTF-8"?> Using the XML canonical method Canonical XML 1.1
  • 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

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

http://hl7.org/fhir/canonicalization/xml#data The narrative ( The narrative ( Resource.text ) is omitted prior to signing (note the deletion is at ) is omitted prior to signing (note the deletion is at Resource.text , not , not Resource.text.div )
http://hl7.org/fhir/canonicalization/xml#static In addition to narrative (Resource.text), the 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 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 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 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. © HL7.org 2011+. FHIR DSTU2 (v1.0.2-7202) updated on Sunday, May 15, 2016 10:52 Eastern. Links: Search 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.