Resource XML

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, W3C Schema and UML models are provided that may be a useful aid for system implementation.

XML Content Models

All the content model definitions provided in this specification follow the same general pattern:

 <name xmlns="...">  <!-- Cardinality -->
   <nameA opt type="?"> description of content <name>
   <nameBs type="list">  <!-- Zero+ -->
     <nameB mand type="?">Relevant records</link>
   </links>
 <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
• All the XML is in the namespace http://www.hl7.org/rfh, which is usually specified as the default namespace on the root element (except for XHTML discussed below)
• While the content model shows the control flag (i.e. "opt") and type of the element (i.e. type="?") as attributes, they do not appear in the actual XML content that is exchanged.
• The elements are assigned types. All the types are defined in the data types except for "Resource" and "Narrative" that are documented below. The type names are hyperlinked.
• In addition, each element has a control flag shown in red, that specifies whether it is optional or may be replaced by alternative content. This is explained below. The control flags are link to their definitions.
• The "nameBs" element itself must always appear once. It may have Zero or more "nameB" elements as children. Each "nameB" element itself is mandatory (i.e. if it appears, it must have valid content).
• Each element name is also a hyperlink to the formal definition of the element in the data dictionary that underlies the exchange formats.
• The transactions page documents some additional XML content that may be part of the XML for a transaction (including create, update, or delete)
• Any of the XML elements may have an xml id attribute to serve as the target of an reference.

Control Flags

Data Quality - or the lack thereof- is a ubiquitious issue in healthcare. The control flags are used to control the degree to which missing or poor quality data is tolerated on a per element basis. The control flag on each element must have one of the following values:

If no control flag is specified, the element must be present, but may have a dataAbsentReason instead of it's normal content. Note that the elements defined inside the data types do not have a control flag; instead, a "Use" section specifies the rules as to what elements must be populated.

dataAbsentReason

This attribute may appear on any element in a resource other than those marked mandatory (except text, see below). It may also appear on some elements in the data types as documented.

 <x dataAbsentReason=""/>

The dataAbsentReason attribute can have one of the following values:

Notes:

• "astext" can only be used where a text substitute is allowed. See below.
• Using "masked" may be breach of security or confidentiality, but there are times when it's use is required to support alternate workflows for gaining access to denied information.
• If the dataMissingReason attribute is present, the element may still have additional content from it's definition. Usually this is where the contained elements define what data is missing.
• Systems are not required to process any provided data when a dataAbsentReason is present, except as described in their conformance statement.

Text vs Data

Some data types carry a text element which can be used to carry a textual representation suitable for human consumption of the content in place of structured data that can be processed automatically. A textual representation might exist because:

• The original source system only ever collected text from the human
• Some error occurred during the process of collecting the data
• The correct value is not allowed by the system

When the "correct value" is not allowed by the system, it is generally because the system definition is too simple for the real world. One way of handling this is to correct the system definition and make it more complicated. Interoperability specifications are so driven to become ever more complicated, while offering fewer and fewer returns for the additional complexity. Instead, this specification focuses on capturing the bulk of data that can be cleanly captured, and allowing a graceful fall back to a text based alternative for special/edge/error cases.

The text/structure model allows for the following scenarios:

1. The data was collected in a fully structured way, and conveyed as such
2. The data was collected in a fully structured way, and conveyed as such. In addition, a textual summary is automatically generated for the benefit of human users of systems that do not support the structure
3. The user is allowed to enter structured data or to choose some text alternative
4. Text was collected from the user, and no attempt has been made to code it into a structured representation
5. Text was collected from the user, and it has been partially converted into a structured representation, with variable degrees of success
6. Some error has occurred, and the text describes the error
7. The data is missing

This table summarises the values of the various components for the cases:

Notes:

• These are the only combinations allowed
• If the element is not marked with the text or opt control flags, only combinations A, B, and H are allowed
• If the element is marked with the mand control flag, only combinations A, and B are allowed
• If the element is marked with the text control flag, only combinations A to E are allowed
• When there is no dataAbsentReason, the structure is properly populated
• The narrative is only present if the dataAbsentReason is "astest" or "error", or if it is generated
• If the narrative is flagged as generated, it can only contain what is in the data
• In case #5, Narrative is considered fully coded if all the content in the narrative that is represented in the structure is properly encoded, whether or not the narrative contains aditional information

An additional rule is that every Resource includes a generated narrative summary as a fall back for human interpretation in a text element as the last child of the resource. The narrative summary need not encode all the structured data, but it should be clinically safe to read just the narrative (i.e. it should include the internal narrative that isn't properly encoded). This text must be flagged as generated.

Although this specification allows structure and text to be traded for some elements and some datatypes, applications are not required to do this in all cases. Applications must indicate in their conformance statements whether they support data, text or both. This will allow implementors to determine whether applications can interoperate. See conformance for further details.

Narrative

This type is used throughout the exchange specification to describe the contents of the text element which appears on several data types. The text element includes xhtml, along with inline images if appropriate.

  <text>
    <plain>plain text</plain>
    <xhtml:html type="xhtml>xhtml content</xhtml:html>
    <image id="[id]">  <!-- Zero+ -->
      <mimeType type="string">mime type of image</mimeType>
      <data type="string">base64 image data</data>
    </image>
    <generated type="boolean">true if generated</generated>
  </text>

The text element contains either an plain element containing plain text or an html element in the xhtml namespace. The contents of the html element are an XHTML fragment containing only the basic html formatting elements described in chapters 7-11 and 15 of the HTML 4.0 standard, <a> elements (either name or href), images, and internally contained stylesheets. The XHTML content may not contain a head, a body, external stylesheet references, scripts, forms, base/link/xlink, frames, iframes, and objects. Technically, the content of the text element is the XHTML Schema type "[todo]", with the additional rules applied.

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

An additional address scheme is used within the xhtml for image location:

  <img src="xxx:#45"/>

This is a reference to an id attribute on an element in the same XML document, either in the image attachments on the text element directly, or an element of type "Data".

  <text>
   <html xmlns="http://www.w3.org/1999/xhtml">
     <p>
       <img src="xxx:#a1/>.
     </p>
   </html>
   <image id="a1">
     <mimeType>image/png</mimeType>
     <data>MEKH....SD/Z</data>
   </image>
  <text>

Applications processing the html should always be able to strip external images (images not using the alternative "xxx" scheme above), and still be able to present the information correctly to a human reader. Additionally, applications processing the html should always be able to strip the HTML tags completely (correcting for implicit paragraph elements such as headers) and still be safe (so where internal images are used, they must include an appropriate caption).

If present, the value of the generated element must be "true" and it indicates that the content was entirely generated from the accompanying structural data (though not all the structural data must be represented).

Note: Elements of type Narrative never have a dataAbsentReason itself, and if they exist, they must have some non-whitespace content in either plain or html.

Resource References

The "Resource" type indicates a reference from one resource to another. Since each resource is identified by a master id that never changes, references are done by id.

  <x>
    <type type="resourceType">Resource Type</type>
    <id type="id">Id of the reference</id>
    <text type="Narrative">Text alternative for the resource</text>
  </x>

The resourceType type is the name of one of the resources defined in this specification, such as "Patient". Whether or not the type of the resource is fixed for a particular element, the reference includes the resource type (this is to assist with future prooting the specification).

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

The id type 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.

When resources are being aggregated, the reference to the resource is replaced with the content of the resource. For instance, the resource in non-aggregated form might look like this:

  <institution>
    <type>Organization</type>
    <id>1145c09c-73d0-4297-9835-620e4afa9deb</id>
  </institution>

This is a reference to an organization that this the institution at which a patient is registered (see the Patient model). When the patient resource is drawn into an aggregated document, some of the references from the patient resource to other resources will also be aggregated, like this:

  <institution>
    <Organization>
      <id>1145c09c-73d0-4297-9835-620e4afa9deb</id>
      <!-- Other contents for Organization -->      
    </Organization>
  </institution>

The conversion can also be reversed when de-composing aggregated content. Aggregation doesn't make any difference where the resource pointer has been replaced by narrative (where allowed).

  <institution>
    <text>
      <plain>Acme Healthcare Inc</plain>
    </text>
  </institution>

When an aggregated document is built, it may contain multiple instances of the same resource (Organizations are a common case). If the aggregated document already contains the resource that is being aggregated, the id reference may be left in place, and it must then be resolved when an application reads the document. Since resources may be cyclically linked, applications must be able to resolve links like this when reading aggregated documents. Applications that create aggregated documents should ensure that the full resources is encountered first when reading the instance before encountering simple references to it.

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 meaning of existing data elements will not be changed or qualified.

Given that in a typical scenario, mixed versions may need to exist, applications would best ignore elements that they do not recognize. 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.

Extensibility

This exchange specification is based on generally agreed common requirements across healthcare - many jurisdications, domains, and different functional approaches. As such, it is not unusual for specific implementations to have valid requirements that will not be adopted by this specification.

The content models defined in this specification may be extended using the extensions element. This is defined in each resource. This element is identified by the type name "Extensions".

 <extensions type="list">  <-- Zero+ -->
   <extension> 
     <code mand type="string"> code that identifies the meaning of the extension <code>
     <ref opt type="uri"> Internal reference to context of the extension <code>
     <[type] opt>[elements for value]</[type]>
   </extension>
 <extensions>

Notes:

• The code defines the meaning of the extension. Any codes must be integrated with the data dictionary this specification is based on (how to do this), and specified in the conformance statement.
• Because extensions can only be defined in the one place in the resource, but may need to extend a specific part of the content model, a ref to the part - by XML ID - is allowed.
• [type] is the name of any of the defined data types, or "Extension" for a nested extension element. The content model must conform to the type specified
• The [type] element is optional, but individual conformance statements may make additional rules about the element
• The extensions may clarify the existing information, and provide further details. But it cannot negate or qualify the information: it must be safe to ignore the content
• Applications consuming the XML must ignore extensions that they do not recognise.
• In many interoperability specifications, the use of extensions acquires a substantial stigma. This is because either they are often abused, or the schemas etc do not support them. The need for a formal definition of the code is intended to discourage abuse, and the schemas etc provide formal support for the extensions

XML Schema

This specification provides schema definitions for all the content models described here. Two schemas are provided for each resource to describe the content model as as stand alone resource, or in it's aggregated form.

XML that is exchanged must be valid against the schema, though there is no requirement to validate instances against the schema, nor is being valid against the schema sufficient to be a conformant instance (this specification makes many rules that cannot be checked by schema). Exchanged content must not specify the schema or even the schema instance namespace in the XML.

Should schema based validation or code generation be of interest, applications can define their own schemas that more closely match the working content mode given their conformance statement. These schemas can eliminate elements not used by the application, and explicitly define extensions that are used. However the xml format they describe must be consistent with the xml and rules defined in this specification.

Object Models

In addition to the schema, this specification also provides object models defined in UML that may be of assistance in defining systems that work with the resources defined here.

Although the UML models provided express the same contents as the xml formats, because of the wide variation in how different architectures and tools map from UML to XML, there should be no expectation that any particular tool will produce compatible XML from these UML diagrams. Systems are welcome to use these object models as a basis for serialization internally, or even between trading partner systems, with any form of exchange technology (including JSON). Systems that use this form of exchange cannot claim to be conformant with this specification, but can describe themselves as using "RFH consistent object models".

To Do: Miscellaineous XML issues

about signing documents. When aggregating documents, careful of clashing ids. Signatures will not apply

© 2011