HL7 version 3

1. HL7 version 3 XML serialization Scope: serialization/deserialization of in-memory objects, XML based conformance and validation. Slide contents published under the Creative Commons / Attribute-Share Alike license Source: www.ringholm.de/download/HL7v3_implementation.zip

2. Agenda • About the HL7 v3 XML Schema • Serialization/deserialization of in-memory objects • Structures, data types • XML Based conformance/validation • ITS Schema and Schematron • Implementation experiences

3. RIMBAA Technology Matrix Persistent Representation Object Representation Serialized Representation RIM (generic) Model RIM Constrained Information Model Application specific Model

4. XML Serialization About the HL7 v3 XML Schema Slide contents published under the Creative Commons / Attribute-Share Alike license Source: www.ringholm.de/download/implementation_mechanics.ppt

5. Two XML-based ITSs XML ITS 1.1 RIM ITS New (2010) Based on serialization of the RIM XML element names based on the RIM core class names. One single schema for all RIM-based models; 50 classes. • Has been in use since the beginnings of HL7 v3 • Based on serialization of an R-MIM (SIM) • XML elements names based on clone/business names for classes as used in the R-MIM • Separate schema for each and every R-MIM (SIM)

6. XML ITS example <component typeCode="COMP"> <commonObservationEvent classCode="OBS" moodCode="EVN” <templateId root='2.16.840.1.113883.10.20.1.24'/> <code code="8302-2" codeSystem="2.16.840.1.113883.6.1" displayName="Lichaamslengte“> <statusCode code="completed"/> <effectiveTime value="200907011346" /> <value xsi:type="PQ" value="90" unit="cm" /> <subject typeCode="SBJ" contextControlCode="OP"> <patient classCode="PAT"> <patientPerson classCode="PSN“ determinerCode="INSTANCE"> <name>ROELOFSEN, TOM</name>

7. RIM ITS example <rim-graph xmlns="urn:hl7-org:v3-rim" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="0226" xmlns:sbad=“urn:oid:2.16.840.1.113883.10.20.1.24” > <outboundRelationship xsi:type="ActRelationship" assocName="subject" cloneName="Subject2" contextControlCode="AN" typeCode="SUBJ" contextConductionInd="false"> <target xsi:type="SubstanceAdministration" classCode="SBADM" moodCode="RQO“ templates=“sbad:root” > <id root=""/> <code code="DRUG" codeSystem=""/> <participation xsi:type="Participation" contextControlCode="OP" typeCode="DIR"> <role xsi:type="Role" assocName="medication" cloneName="Medication" classCode="ADMM"> <player xsi:type="ManufacturedMaterial“ assocName="administerableMedicine" classCode="MMAT" determinerCode="KIND"> <code code="" codeSystem="?"/>

8. RIM ITS - References <communicationFunction typeCode="SND"> <telecom value="http://10.0.1.1:1001"/> <entity classCode="DEV" ID="1" determinerCode="INSTANCE"> <id root="1.2.3.4.52" extension="A12345"/> <name>Sender-Name</name> </entity> </communicationFunction> <communicationFunction typeCode="RSP> <telecom value="http://10.0.1.1:1001"/> <entity IDREF="1" > </communicationFunction>

9. ITSs - RIMBAA Technology Matrix Persistent Representation Object Representation Serialized Representation Note: RIM ITS RIM (generic) Model Note: XML ITS RIM Constrained Information Model Application specific Model

10. Using HL7 v3 Schemas HL7 produces informative XML Schema Definitions (XSD) for all v3 messages There are nonormativeXML schema (current workitem) normative schema are being discussed Things to understand An XML document that satisfies Schema validation is not necessarily a valid HL7 v3 Message/Document

11. Schemas Tips and Tricks The HL7 (XML ITS) schemas are tough Thoroughly test the schemas with your tool of choice to spot incompatibilities Might be necessary to modify the schemas based on the specific use case (removing unused parts, simplify data types…) HL7 uses default and fixed attribute values in a number of cases to represent structural codes Implementation Guide should specify whether default and fixed attributes should be used XML ITS

12. Schema versions XML ITS • The Schema generator (part of the v3Generator tool) has undergone ‘patches’ to improve compliance of the generated schema with the XML ITS. • Schemaset as published with one Normative edition may not be compatible with the next Normative Edition.

13. Schema dif

14. XML ITS Schema - Abstract Models XML ITS • In v3, Element Names are derived from the permitted structural codes • No meaning is lost if you strip all element names from HL7v3 XML • <Foo classCode=“PSN”>..</Foo> is the semantic equivalent of • <Person classCode=“PSN”>..</Person> • However, most XML tools are useless if you strip all element names from a document. • First generation implementations will use XML element names, later systems will be driven off the structural vocabulary (classCode, moodCode, typeCode.. ) • Model Driven Architectures / Code Generation

15. XML Schema what are schemas bad at • No ambiguous content models allowed • Problem for model-XML mapping (requires use of clone class names in XML instances) • No conditional constraints • cannot have an element that may either have a nullFlavour, or a set of attributes • Date+Time types are a mess • HL7 uses short ISO dates (without validation) • Code list validation • Only for small (enumerated) code lists • Friendly messages when validation fails

16. XML Serialization Serialization/Deserialization (using XML techniques) Slide contents published under the Creative Commons / Attribute-Share Alike license Source: www.ringholm.de/download/implementation_mechanics.ppt

17. Parsing and ValidationUsing XML Techniques Serialized Message to Application Object Streaming API SAX, XmlReader for efficient parsing of XML instances Stripping out of those parts one needs only, skipping all other content DOM, XPath Total control on XML processing In memory object which represents all of the XML contents

18. Parsing and ValidationUsing XML Techniques

19. Normalization HL7 HL7 Rules HL7 v3Message SchemaValidation HL7 v3Schema ImplementationSpecific InformationModel Extended Validation MessageParsing ClinicalRepository ApplicationRules

20. TransformationUsing XML Techniques Serialized Message to/from other serialized model: XSLT 1.1, XSLT 2.0, EXSLT Every platform has multiple implementations of XSLT for XML transformations Saxon, .NET Framework, JAXP… Cascade XSLT transformations to simplify and flatten the instances XQuery XML Query Language for procedural XML processing Several XQuery implementations are avaliable, refer to W3C XQuery home page (over 50 listed)

21. SerializationUsing a template set message ={ <patientPerson> <id root="2.16.578.1.34.1000.1" extension=“$PAT_ID"/> <name use="L"> <given> $PAT_FIRSTNAME</given> <given> $PAT_MIDDLE</given> <family> $PAT_FAMILY</family> </name> <administrativeGenderCode code=“$PAT_GENDER" codeSystem="2.16.840.1.113883.5.1"/> <birthTime value=“$PAT_BIRTHDATE"/> </patientPerson> } • Simply fill in the blanks to create message • Use XPATH for inbound models • Ignorant of V3 data model and XML

22. SerializationUsing a template • Use only when variability is low, when a few messages/documents need to be supported • Beware of exceptions: • nullFlavor instead of code • Variable has no value: • <name></name> is valid XML, but it isn’t valid in a V3 XML instance • <Act code=“” codeSystem=“1.2.3”/> isn’t valid in a V3 XML instance

23. XML Serialization XML Based conformance/validation Slide contents published under the Creative Commons / Attribute-Share Alike license Source: www.ringholm.de/download/implementation_mechanics.ppt

24. Parsing and ValidationUsing XML Techniques XML Schema Validation HL7 provides informative schemas for first-pass message validation Not sufficient for full validation Schematron, RELAX NG Better than XSD as validating messages, but still not widely used no HL7-provided schematron (although could be generated from MIF) May be provided by the author of an implementation guide Validating Stylesheet Produces “human readable” errors

25. Schematron is a … • Rules-based validation language • A way to test XML documents • A way to specify and test assertions about patterns in XML documents • A cool report generator

26. A Few Schematron Use Cases • Validation • direct checks beyond what schemas can express • produce reports for complicated checking by humans • Find patterns in documents • Check elements against a controlled vocabulary (from external XML file)

27. Reasons to Use Schematron • Business/operating rules that other constraint languages can’t enforce • Different requirements for different stages of the document lifecycle • Local or temporary constraints (not in base schema) • Unusual (but not illegal) variation • No schema • Ad hoc querying and discovery

28. What Schematron Does • Validate/report on documentstructure • presence/absence of elements • sequenceof elements • presence/absence of attributes • Validate/report on documentcontent • Validate/report on attributecontent • Check co-occurrenceconstraints • (If @type="other", thenelementmusthavecontent)

29. A Short Example Schematron • ...in a CDA instanceSchematron <typeId extension="POCD_HD000040" root="2.16.840.1.113883.1.3"/> <rule context="hl7:typeId"><assert role="error“ test="@extension='POCD_HD000040'"> ClinicalDocument.typeId (2.16.840.1.113883.2.4.6.10.35.3) @extension SHALL have value POCD_HD000040 static </assert> <assert role="error" test="@root='2.16.840.1.113883.1.3'"> ClinicalDocument.typeId (2.16.840.1.113883.2.4.6.10.35.3) @root SHALL have value 2.16.840.1.113883.1.3 static </assert></rule>

30. Schematron - Example

31. XML Serialization Data Types Slide contents published under the Creative Commons / Attribute-Share Alike license Source: www.ringholm.de/download/implementation_mechanics.ppt

32. Caution: Names/Addresses DT R1 • In XML: Mixed content • Order of the elements is of importance, special parsing software may be required – relying on XPath expressions may not be sufficient. • Example: <name> <family qualifier=‘SP'>Aragon</family> <prefix qualifier=‘VV'>de </prefix> <prefix qualifier=‘VV'>la </prefix> <family qualifier='BR'>Fuentes</family> <given>Maria</given> </name>

33. Entity/Person Name mixed content Order SHALL be as one would display/print the name Attributes: data: content/values part type: given, family prefix, suffix,delimiter qualifier: title, birth, spouse, nobility .. Implementation Note: Lots of differences (custom, law, name order,…) Always requires a detailed profile Data Type: Names (EN, PN) DT R1 <name> <prefix qualifier='AC'>Dr. phil.</prefix> <given>Regina</given> <given>Maria</given> <prefix qualifier='NB'>Gräfin </prefix> <family qualifier='BR'>Hochheim</family> <delimiter>-</delimiter> <family qualifier='SP'>Weilenfels</family> <suffix qualifier='PR'>NCFSA</suffix> </name>

34. XML Serialization AAS Tree project Slide contents published under the Creative Commons / Attribute-Share Alike license Source: www.ringholm.de/download/implementation_mechanics.ppt

35. AAS XML Techniques • On the assumption that it only needs to support a few serializations: • Use XML schema and published Schematron to validate inbound messages • Transform v3 XML into an internal XML format using XSLT, process XML • Outbound: transform internal XML format into v3 XML

36. XML Serialization Implementation Experiences Slide contents published under the Creative Commons / Attribute-Share Alike license Source: www.ringholm.de/download/implementation_mechanics.ppt

37. Study related to „Valid“ CDA Documents • Validates against the published CDA XML Schema • XML Schema based validation tool • Validates against the abstract CDA model specification • Use a MIF (specification of the abstract model) based validation tool • Validates against requirements as specified in implementation guides • XML Schematron based validation tool • Validates against templates as specified in a document instance • MIF or Schema based validation tools

38. CDA Validation options 26% Failed this validation TEST (1) CDA R-MIM XML Schema CDA Document (instance) 81% Failed this validation TEST (1,2) HL7v3 Model Repository CDA R-MIM MIF Business Rules XML Schematron Template MIF CDA Implementation Guide (textual) Template XML Schema (1) Study of 23 CDA projects worldwide, paper published at IHIC 2008. (2) Tool is aware of CDA constraints not present in MIF.

39. Recommendation • Use pure XML techniques (DOM/SAX, XSLT, Schematron) if one only has to support a few serialized models • It just gets “too painful” .. • Use ‘Templated’ approach is one has to mainly send serialized models (e.g. CDA), combine with XPath to process inbound serializations. • Won’t really work for non-trivial projects ..

40. Any Questions ? • Or: post your question/suggestions via • HL7 Wiki: http://bit.ly/d7tSsL • E-mail v3impl@ringholm.com