XD* Metadata Primer

From Direct Project
Jump to: navigation, search
XD* Metadata can be a confusing topic to those just starting out with IHE profiles.

At the core, the object models for XD* Metadata are quite simple, but they are mapped on to OASIS ebXML in ways that can be quite confusing at first, particularly for those who do not come into healthcare interoperability from an ebXML registry/repository perspective. This document takes the perspective of treating ebXML and the ebRIM* object model and XML representation like a foreign language for which you need to learn the basics for a vacation. Because you are only visiting, and have no plans on living in the country or even remembering the language a month from now, your knowledge of the language will be necessarily idiosyncratic, consisting mainly of words for eating and drinking at restaurants, cafes and bars, reserving rooms, finding directions, and, most importantly, going to the bathroom. Polite words are also important, but are optional for Americans.

This guide will be biased towards only metadata concepts needed to implement XDR and XDM, and will mainly ignore XDS; the guide does, however, promise to be polite. It also has superheros.

This guide is informative, not normative. The IHE document is the normative guide; any divergence between this document and the IHE document must be resolved in favor of the IHE document.

* The use of the term "RIM" in the XDS Metadata document refers to the ebXML Registry Information Model, not the HL7 Reference Information Model. This can be confusing on first read. Or second read.

Basic Objects


XD* Metadata has three basic objects:

  1. Submission Set
  2. Document Entry
  3. Folder


In addition, the Association object is used to combine Document Entries into Folders

These objects are represented in XML in the following way:

All objects are contained in a <SubmitObjectsRequest> element that contains a single RegistryObjectList element.

That is, the core of the XML document is:

<SubmitObjectsRequest>
  <RegistryObjectList>
  </RegistryObjectList>
</SubmitObjectsRequest>


Submission Set XML Representation


A Submission Set goes in the section as a child of the RegistryObjectList. It is composed of a RegistryPackage element with an associated Classification element that marks it as a Submission Set (this is necessary because both Folders and Submission Sets use RegistryPackage elements. It apparently would be bad ebRIM mojo to mark this as a Submission Set in a simple attribute, or a special purpose element (because ebRIM does not allow subclassing the Submission Set), which is why the Classification element is used.

The XDS Metadata specification says that the Classification can either be a peer or child element to the RegistryPackage element that it marks as a Submission Set. It seems conceptually simpler to treat it as a child element rather than a peer element when generating metadata, but when reading metadata implementations need to be able to look both places.

The Submission Set MUST have an id attribute. The id is also called the entryUUID Submission Set attribute** in the documentation for the Submission Set metadata. Is this confusing? Yes. Just remember entryUUID object attribute == id XML attribute. Think of it like a superhero. Mild-mannered id by day, powerful crime-fighting entryUUID by night, but you've just unmasked its secret identity.

** To make this more confusing, the core objects have what the XDS Metadata spec calls "attributes" that are really properties of the object, and are usually not (but sometimes are) expressed as XML attributes. Is that also confusing? Yes. To be clear, this guide will never use the bare term "attribute" and will always qualify "XML attribute" to refer to XML attributes or "object attribute", "Document Entry attribute", etc. to refer to the various object properties.

Here's the boilerplate for a Submission Set XML representation:

<RegistryPackage id="[entryUUID object attribute]" [other object properties expressed as attributes]>
  <Classification classificationNode=”urn:uuid:a54d6aa5-d40d-43f9-88c5-b4633d873bdd”
                  classifiedObject=”[entryUUID object attribute]”
                  objectType="urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:Classification"/>
</RegistryPackage>


Treat that Classification element as boilerplate, and remember that the classifiedObject XML attribute has to link to the RegistryPackage id XML attribute.

Disambiguating RegistryPackage Elements


Both Submission Sets and Folders are expressed as RegistryPackage elements, and are disambiguated by a special Classification element.

When reading XD* Metadata, remember that the Classification can be a peer to or child of the RegistryPackage. If you come across a RegistryPackage, you need to check if there is a child or peer Classification element whose classifiedObject XML attribute links to the RegistryPackage id XML attribute, and then check the classificationNode XML attribute of the Classification.

classificationNode value
Object type
urn:uuid:a54d6aa5-d40d-43f9-88c5-b4633d873bdd
Submission Set
urn:uuid:d9d542f3-6cc4-48b6-8870-ea235fbc94c2
Folder
Anything else
A closely guarded IHE secret known only to large enterprise vendors, an object from the future through an XML wormhole, or an error


It all feels so wrong, but it gives the resulting XML more self-esteem about ebRIM conformance, so indulge the XML.

Document Entry XML Representation


A Document Entry goes in the section as a child of the RegistryObjectList. It is an ExtrinsicObject XML element with an objectType XML attribute with the magic value of "urn:uuid:a6e06ca8-0c75-4064-9e5c-88b9045a96f6". It also has an id that is used to link the Document Entry data to Folders and to the actual document binary, and like the Submission Set, that id XML attribute has a secret superhero identity as the entryUUID object attribute. Pretty simple.

<ExtrinsicObject  objectType="urn:uuid:7edca82f-054d-47f2-a032-9b2a5b5186c1"
   id="[entryUUID object attribute]" [other object attributes expressed as XML attributes] >
</ExtrinsicObject>


Folder XML Representation


[TODO]

Association XML Representation


[TODO]

Object Attribute XML Representations


This is the secret decoder ring of this guide, or the Hungarian Phrasebook, to keep with the foreign language metaphor. You think "This document has an author", you flip through the phrasebook and learn that you need to say "My hovercraft is full of eels.".

For the purposes of this guide, we will pretend that there are object types used to map XML for the object attributes:

Object type
Description
Example
XML Attribute
The object attribute is expressed as an XML attribute on the XML element that expresses the object
<ExtrinsicObject mimeType="text/plain" ...>
Name
A name for the parent object. Except that instead of just putting the name in a Name element, it's actually the value XML Attribute of the LocalizedString Element of the Name Element. That whacky ebRIM. Always having fun. There can only be one Name element for any particular object.
<Name><LocalizedString value="Stately Wayne Manor"/></Name>
Description
Like Name, generally used for comments, contains the same subelements as Name, but called Description
<Description><LocalizedString value="The very best place to party in Gotham City! But mind the gate crashers, and bring your gas mask"/></Description>
Single Valued Slot
The object attribute representation is wrapped in a Slot with a name XML attribute that uniquely identifies this slot and a single ValueList that contains one and only one Value
<Slot name="secretIdentity"><ValueList>
  <Value>Bruce Wayne</Value>
</ValueList></Slot>
Multivalued Slot
Just like a Single Valued Slot, but the ValueList can contain multiple values
<Slot name="superHeroAliases"><ValueList>
  <Value>Batman</Value>
  <Value>The Dark Knight</Value>
  <Value>The Caped Crusader</Value>
</ValueList></Slot>
Classification

An element called Classification that has the following XML attributes:

  • classificationScheme: a UUID that uniquely identifies the object attribute
  • nodeRepresentation: a, uhh, representation of the node. Whatever that means. For a coded value, this is the code (see below) for Author, this is blank, and for the sort of classification that disambiguates a Submission Set from a Folder, the attribute is unused. If you have secret ebRIM vision powers, this all makes sense.
  • classifiedObject: The id AKA entryUUID of the containing object
  • objectType:The static value "urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:Classification"The classification will contain one or more of the object types in this table
See below
Coded Value Classification
A Classification element used for expressing coded object attributes. The nodeRepresentation attribute is the code, has a single Name sub-element whose value is the decoded string, and a single Single Valued Slot, named "codingScheme" whose value is the coding scheme the code is selected from
<Classification classificationScheme="urn:uuid:blahblahblah"
                nodeRepresentation="TV"
                classifiedObject="[entryUUID for the document, submission set, etc]
                objectType="urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:Classification">
  <Name><LocalizedString value="TV Series Batman Incarnations"/></Name>
  <Slot name="codingScheme"><ValueList><Value>Systematic Nomenclature of Batman Attribute Types</Value></ValueList></Slot>
</Classification>
External Identifier

An XML Element named ExternalIdentifier. Holds identifiers for the containing object. Has the following attributes:

  • identificationScheme: a UUID that uniquely identifies this object attribute
  • objectType: Always "urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:ExternalIdentifier"
  • value: The actual value of the identifierIn addition, the element has a child Name object type, whose value is a static string labeling the object attribute, always valued with the pattern "ObjectType.attributeName"
    Why? Superhero Justice League TopSecret classification. Sorry.
<ExternalIdentifier identificationScheme="urn:uuid:2e82c1f6-a085-4c72-9da3-8640a32e42ab"
                    value="111-11-1111"
                    objectType="urn:oasis:names:tc:ebxml- regrep:ObjectType:RegistryObject:ExternalIdentifier" >
  <Name><LocalizedString value="SuperheroDocumentEntry.socialSecurityId"/></Name>
</ExternalIdentifier>


Document Entry Attributes


This table was stolen liberally from Keith Boone's posting on this topic

Attribute
Object Type
UUIDs and static text
Value representation
author
Classification
Contains various Slots specified below
authorInstitution
Multivalued Slot
  • name "authorInstitution"
XON representation of the institutions
authorPerson
Single Valued Slot
  • name "authorPerson"
XCN
authorRole
Multivalued Slot
  • name "authorRole"
Each value is human readable text
authorSpecialty
Multivalued
  • name "authorSpecialty"
Each value is human readable text
classCode
Coded Value Classification
As constrained by XD* Metadata for Directed Messaging specification


[TODO: from Keith's blog post]

comments
Description
O
confidentialityCode
Classification
f4f85eac-e6cb-4883-b524-f2705394840f
R
creationTime
Slot
R
DTM
eventCodeList
Classification
2c6b8cb7-8b2a-4051-b291-b1ae6a575ef4
O
formatCode
Classification
a09d5840-386c-46f2-b5ad-9c3699a4309d
R
hash
Slot
R
SHA1 hash
healthcareFacilityTypeCode
Classification
f33fb8ac-18af-42cc-ae0e-ed0b0bdb91e1
R
languageCode
Slot
R
legalAuthenticator
Slot
O
XCN
mimeType
ExtrinsicObject.mimeType
R
patientId
ExternalIdentifier
6b5aea1a-874d-4603-a4bc-96a0a7b38446
R
CX
practiceSettingCode
Classification
cccf5598-8b07-4b77-a05e-ae952c785ead
R
serviceStartTime
Slot
R2
DTM
serviceStopTime
Slot
R2
DTM
size
Slot
R
Integer
sourcePatientId
Slot
R
CX
sourcePatientInfo
Slot
O
title
Name
O
typeCode
Classification
41a5887f-8865-4c09-adf7-e362475b143a
R
uniqueId
ExternalIdentifier
2e82c1f6-a085-4c72-9da3-8640a32e42ab
R
OID or OID^identifier
URI
Slot
R
URI

[TODO]

NIST validator