HL7 hData Record Format 2.0
1
9
10
7
8
5
6
2
3
4
Contributors:
Muhammad Asim, Philips Healthcare, muhammad.asim@philips.com
Gerald Beuchelt, gerald@beuchelt.com
David Hay, david.hay25@gmail.com
Paul Knapp, pknapp@pknapp.com
Mark Kramer, The MITRE Corporation, mkramer@mitre.org
Ken Rubin, Hewlett-Packard, ken.rubin@hp.com
Samuel Sayer, The MITRE Corporation, ssayer@mitre.org
© 2009-2013 The MITRE Corporation. All rights reserved.
23
24
25
26
19
20
21
22
11
12
13
14
15
16
17
18
27
28
29
30
31
HL7 is working to improve the quality of health care by assuring the interoperability of health information.
Standard representations of patient status, such as the Clinical Document Architecture (CDA) [1], and standard message formats, including Health Level 7 (HL7) Version 2.x and Version 3 Messages, are important aspects of realizing that vision. However, the goal of easily accessing and integrating information from multiple, independent health care providers has not yet been realized. For example, creating a patient-centric virtual lifetime health record by dynamically federating multiple data sources requires new information architectures that are highly scalable and capable of operating in loosely coupled environments. hData seeks to simplify the exchange of information found in Electronic Health Records (EHR) systems by leveraging common web technologies such as Representational State Transfer (REST) architectures and the
Atom Syndication Protocol [2], resulting in rapid development and lightweight web-enabled applications. Using mainstream technologies brings a host of advantages, including proven scalability, a rich tool ecosystem, rapid innovation, and a large community of web developers. The medical information community also needs to move in this direction to exploit mobile platforms, which unquestionably will be primary endpoints for clinicians and patients alike. With bandwidth and processing limitations, there will be a premium placed on web-enabled, efficient, incremental data exchange. hData is designed to facilitate information interoperability by establishing a standard presentation of resources at a web interface, and a standard set of REST web services interact with those resources. By design, hData is content agnostic. Rather than being limited to a particular set of schemas, hData can equally be used for medical documents such as CDAs or Continuity of Care Records (CCRs), images, MS-Word documents, spreadsheets, or Fast Health Interoperable Resources (FHIR) [3], with almost no limitations on the type of
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
40
47
48
49
50
51
52
41
42
43
44
45
46
53
54
63
64
65
66
67
68
55
56
57
58
59
60
61
62
32
33
34
35
36
37
38
39
HL7 hData Record Format 2.0 content that can be represented and transported. In this sense, hData is not an alternative nor a competitor to
FHIR (which also defines REST transport), but a complement to FHIR that enables exchanges involving a heterogenous mix of FHIR and non-FHIR resources.
The resource hierarchy is fundamental idea in hData. The resource hierarchy represents a logical arrangement of information from a data repository, formatted for exchange, and mapped to URLs. In a typical realization, an hData-enabled web server will respond to external requests by reading or writing to a clinical data repository, delivering data in one or more declared wire formats. hData represents an interface to a clinical data repository, not the repository itself. hData is comprised of two related standards:
1.
hData Record Format (HRF). The subject of this specification, the HRF defines the presentation of data at a web interface as a resource hierarchy, including the URL location of data, security considerations associated with the data, links to formal data definitions, as well as provenance and other critical information. Resources can be any type, either XML documents (such as CDA documents, H7v3 messages, or FHIR resources, etc.) or other content types such as MS Word documents or DICOM files.
While the HRF is mostly discussed here in terms of an EHR, it is fully extensible and can be adapted to many other situations where data is to be organized and shared.
2.
hData RESTful Transport (HRT) [4]. While the resources in the HRF can be accessed by any appropriate transport, the HRT defines a simple set of web operations (HTTP requests) indicating actions to be performed on the resources identified in the HRF. These operations include GET (to obtain a copy of the resource), POST (to upload a resource), and OPTIONS (to access information about allowable operations on the resource). The HRT was created as a REST implementation of the HL7/OMG SOA
Retrieve, Locate, Update, Service (RLUS) model [5].
The HRF and HRT together define a framework for creating data exchanges. However, hData does not define specific payloads or resource hierarchies. These choices fall to implementers of hData. hData implementers can either create their own implementation, follow an existing hData implementation guide (called an hData
Content Profiles (HCP)), or work together with information exchange partners to create their own HCP. HCPs are typically created by organizations to enable consistent use of hData in a given domain, making exchange of information easier and more predictable. HCPs can themselves be the subject of standardization processes.
guidelines for creating HCPs.
shows that the HRF specification provides a framework for packaging and organization, while the HCP provides domain-specific types of logical resources to be exchanged, and specific organization of these resources.
Transformation of logical resources into wire formats, often expressed as XML or JSON, is governed by the
Implementable Technology Specification (ITS) working group in HL7. Finally, the HRT provides the HTTP semantics for the network exchange.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
HL7 hData Record Format 2.0
Domain Experts
Legend
Consensus
Requirements
Influence design/ determine collaborate uses
Determine instance content realizes is contained in hData speci fication
or construct (also
HL7 product)
HL7 products
Business
Analysts
Standards
Modeling
Experts
Generalized
Structure
Designs
HL7 RIM &
Vocab
HL7 Subject Matter
Experts
Standards aware
Architects
Domain
Speci fic
Analysts
Standards aware
Technical
Architects
Domain Speci fic
Structure
Designs
HL7
Templates
HL7 ITS
Domain speci fic hData Content
Pro file
(format speci fied in
HRF)
Technical
Implementers
Interfacing
Technical
Components HL7
Package and
Service
HL7
RLUS
Service
Functional
Model
HL7 hData Record
Format
(Package organization and meta data)
69
70
71
72
73
74
75
76
77
78
79
80
81
82
On the wire instances
OMG
RLUS
Platform
Speci fic
Model
OMG hData
RESTful Transport
(Service access and network transport)
Figure 1. hData in the context of HL7 concepts
Version 2.0 of HRF introduces several nomenclature changes. These nomenclature changes are intended to use terminology in a more standard way and make the specification more accessible. These changes are primarily of concern to those familiar with the previous version of the HRF, and readers of the HRT Version 1.0:
We now refer to resources instead of section documents, to better align with common REST vocabulary and FHIR, and to remove the unintended reference to the HL7 Clinical Document Architecture (CDA).
The term resource type is now used instead of extension, to better align with use of the term resource, and also to make it clear it we are not referring to a file extension, nor an extension to an XML schema.
This document uses the following namespaces. This specification uses a number of namespace prefixes throughout; they are listed in Table 1. Note that the choice of any namespace prefix is arbitrary and not semantically significant. Note that namespace identifiers are not necessarily resolvable links.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
HL7 hData Record Format 2.0
Namespace
Prefix
Namespace Universal Resource Identifier (URI) hrf hrf-md xs ds
Description http://hl7.org/schemas/hdata/2013/08/hrf
Namespace for elements in this document http://www.hl7.org/schemas/hdata/2009/11/metadata
Namespace for metadata extensions appearing in Atom feeds http://www.w3.org/2001/XMLSchema http://www.w3.org/2000/09/xmldsig#
XML Schema namespace
Namespace for XML Digital Signature atom http://www.w3.org/2005/Atom
Namespace for the Atom syndication format
83
97
98
99
100
92
93
94
95
96
88
89
90
91
84
85
86
87
101
102
103
104
105
106
Table 1. Namespaces referenced in the hData Specification
HL7 hData Record Format (HRF) - The subject of this specification, the HRF defines the hierarchical presentation of data at a web interface, security considerations associated with the data, links to formal data definitions, as well as provenance and other critical information.
hData Record (HDR) - A specific instance of an hData service endpoint, consisting of a specific virtual hierarchical organization of exchangeable resources, including a root file that declares the structure and the type of resources associated with each position in the hierarchy. The HDR optionally declares the conformance to one or more hData Content Profiles (HCPs).
hData RESTful Transport (HRT) [4]- The HRT is an specification of the Object Management Group (OMG) defining how an abstract hierarchical organization defined within the HRF specification can be accessed and modified through a REST approach, using HTTP as the access protocol. It creates a unique mapping of the HDR to a URL structure, and defines how HTTP verbs such as GET, POST, DELETE, etc. affect the underlying information.
hData Content Profile (HCP) - An hData implementation guide that profiles a purpose-specific use of hData. An
HCP stipulates a particular resource hierarchy, resource types, business rules, and other information needed to implement information exchanges in a domain using hData.
Include other terms such as REST, FHIR, CDA, etc?
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [6].
When describing XML schemas, this specification uses the following notational conventions. Element names do not include the namespace prefix if the namespace is mentioned in close proximity in the text. Attributes are denoted with the @ sign. If present, the pair in parenthesis after the element name contains the data type and
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
107
108
109
110
111
HL7 hData Record Format 2.0 the cardinality, or just the cardinality if the element takes no value. Cardinality is indicated as 0..1, 1, 1..*, or
0..*.
schema description within the main body of this document are informational only.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
HL7 hData Record Format 2.0
112
127
128
129
130
131
132
133
121
122
123
124
125
126
134
135
136
137
113
114
115
116
117
118
119
120
The basic approach of the hData Record Format is to represent medical information through linked resources, organized through an abstract hierarchy, similar to the folder-file paradigm of many computer file systems. As mentioned earlier, the hierarchy is typically not an actual data repository, but rather an abstract arrangement of information derived from a repository, whose form we do not specify.
To draw a distinction from an actual file system, we use the word “section” instead “folder” and “resource” instead of “file” (unless the resource is an actual file). At the top of the hierarchy is a special resource called the
“root file”, which describes many of the properties of the hierarchy (see 2.2).
The root of the hierarchy represents all the information from the repository meant to be shared. This can correspond to virtually any collection of data, such as patient records, pharmacy or lab information, billing data, image data, benefits information, consent forms, etc. Because of the flexibility of hData, it is also possible to set up one HDR for a large data pool, or many separate HDRs, each corresponding to a single patient. hData can also represent the resource hierarchy used in FHIR (one level deep, one section per resource type). hData puts no constraints on the hierarchy structure.
Each section (node in the hierarchy) contains a set of subsections and/or resources. Resources are grouped into sections, with each section having at most one resource type, which is declared in the root document. For example, a section may contain laboratory results. Sections can also contain other sections, for example, there may be a section for radiology under laboratory results. It is RECOMMENDED that the semantics and rationale
concurrently, multiple groupings MAY be established in parallel. As a result, the same resource MAY exist in more than one place in the hierarchy.
Typically, the hierarchy is static, and only the contents of each section are dynamic. However, HRT Version 1.0 defines operations to dynamically create and delete sections and subsections. Under the requirements of the
HRT, changes to the hierarchy must be concurrently registered in the root document by the server. Therefore, a client can always depend on the root document accurately describing the entire hierarchy.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
HL7 hData Record Format 2.0 hData Record
Abstract root of the record
Root Document
Manifest for the overall record, containing the sectional structure and the associated semantic signi fiers.
Section content feed
(IETF Atom feed)
Section
Container for Section Documents and child Sections
Section content feed
(IETF Atom feed)
Section Document
Section Document
Section Document document - XML or
- actual medical data document type) media type
Section
Section
Section
Section
Section
Section
138
139
140
141
142
143
144
145
Figure 2. Abstract information hierarchy defined by hData Record Format
The root file is a resource is located at the top of the hierarchy that describes certain properties of the
description that provides a visual sense of what the end resource instances will look like in XML is shown in
Figure 4. For more information about the pseudo-XML syntax, refer to the FHIR documentation [3].
TO DO: Add JSON representation
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
HL7 hData Record Format 2.0
146
147 Figure 3. UML Diagram of Root File
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
HL7 hData Record Format 2.0
148
149
159
160
161
162
163
164
165
166
167
150
151
152
153
154
155
156
157
158
Figure 4. Pseudo-XML Representation of Root File
In the following, we give the normative definitions of each element of the root file. The namespace of all elements in the root file is “hrf” unless otherwise noted. Attributes are denoted with the at sign (@). Following the name of each element in parentheses are the data type and the cardinality, or only the cardinality if the element takes no value. The top-level element is <Root>. The root file contains the following elements
(REQUIRED if not marked otherwise):
Elements and Attributes of <Root>:
id (xs:string, 1) - This element uniquely identifies the root document and the hData Record itself. This element has no specific semantics or meaning. A possible implementation could be a textual representation of a UUID.
version (xs:integer, 1)- The version of the HRF used within the root file. The version number for records complying with this version of the specification is 2.
created (xs:dateTime, 1)- Creation time of the root file. This data SHOULD be significant to at least the second.
lastModified (xs:dateTime, 1)- Last modification of the root document. This data SHOULD be significant to at least the second.
profile (0..*) – This element represents a content profile implemented in this HDR. If the HDR conforms to an HCP, it SHOULD be listed here. HDRs are not required to follow any HCP, however, without an
HCP, it may be difficult to standardize information exchange among multiple partners.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
173
174
175
176
177
196
197
198
199
200
201
202
168
169
170
171
172
HL7 hData Record Format 2.0
resourceType (1..*) – This element represents a resource type used by this HDR. Each type of resource used in this HDR MUST have a resourceType element.
section (1..*) - This element represents a section in the HDR hierarchy. Each HDR section except the top level section (the root of the hierarchy) of the hierarchy MUST have a corresponding section element.
Elements of <profile> :
id (xs:string, 1) - This attribute contains a local identifier for the profile. The id MUST be unique within the root document.
reference(xs:string, 1) – A reference to the HCP defining this content profile. It is RECOMMENDED to use a URL resolving to the HCP. Every profile MUST have a reference to its defining document.
Elements of <section>:
section (section, 0..*) – The subsections belonging to the current section.
path (xs:string, 1) - This text attribute is a path segment, consisting of a literal or a template. The path is
Unreserved Characters in URI Generic Syntax [7], specifically, [a-z][A-Z][0-9] and hyphen, period, underscore, and tilde. A path MUST NOT begin with any resourcePrefix used in the HDR. Template paths use the same character set as literals, except templates are delimited by braces (curly brackets).
It is RECOMMENDED that organizations creating HCPs use a unique identifier such as their domain name in the first path segment (such as e.g. org.hl7) to avoid namespace collisions in the full path name.
resourceTypeID (xs:string, 0..1) - The value of this element MUST be equal to the id attribute of a
<resourceType> element. Only resources whose type matches the resourceTypeID element can appear in the section. If no resourceTypeID is given, the section may not contain resources, only other sections. The top level section (the root of the hierarchy) has no resourceType, and cannot contain resources.
resourcePrefix(xs:boolean, 0..1) - Indicates whether to use an “@” sign before the resource id in the path associated with a resource . If this element is omitted, the value of resourcePrefix is inherited from the section’s parent sections. If the element does not occur in any parent, the “@” sign is used by default. If resourcePrefix is false, path templates MUST NOT be used.
profileID(xs:string, 0..*) - Indicates the hData Content Profile(s) defining this section. The profileID is inherited from its parent sections, and hence usually only specified in top-level sections.
Elements of <resourceType>:
id (xs:string,1) - This attribute contains a local identifier for the resourceType. It MUST be unique within the root document. It is RECOMMENDED to use a human-readable class or type name for the id. A section MAY have a resource type of “Root”, indicating the client will find another root file in this section that defines additional levels of the hierarchy.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
203
204
205
206
207
208
209
210
211
212
213
214
225
226
227
228
229
230
231
232
233
234
235
236
237
215
216
217
218
219
220
221
222
223
224
HL7 hData Record Format 2.0
reference(xs:string, 1) – A reference to the definition of the resource type. The reference MUST be a globally unique identifier. It is RECOMMENDED to use a URL resolving to version-controlled documentation of the resource detailing the semantics of the resource.
representation (0..*) - This element represents a physical representation of the resource, used for “on the wire” communication. If more than one representation is given, the first one listed is the default. If no representation is given, the mediaType is assumed to be “application/xml”. It is RECOMMENDED to provide an explicit representation to enable validation of the content.
Elements and Attributes of <representation>:
mediaType (xs:string, 1..1) - Contains the media type of the resource.
validator(xs:string, 0..*) - An optional reference to a validator for this representation, such as an XML
Schema Definition (XSD) or Schematron. It is RECOMMENDED to use a URL resolving to the validator.
The root document schema MAY be extended to support additional features.
Section and Resource Paths
The full path to any section is obtained by starting with a forward slash (“/”), and concatenating the path segments, separated by forward slashes.
The full path to any resource is obtained by starting with the full section path, adding a forward slash, and appending the resourcePrefix (an ”@” sign) concatenated with the resource identifier. The “@” sign prevents the server from interpreting a resource as a section. It is RECOMMENDED that implementers use the resource
resourcePrefix MUST be used in that branch. If the implementer chooses to omit the “@”, they must declare resourcePrefix=”false” in the section or a parent section. The resourcePrefix is true by default.
To prevent interpreting a section as a resource, path segment names MUST NOT begin with the “@” sign.
The following inheritance rule applies to the resourcePrefix and profileID: If either of these elements are not given in a section, the value of the element is determined by traversing up the hierarchy to parent sections.
Thus, it is only necessary to declare these inherited elements in top-level sections.
Path Templates
Path segments may be specified by templates. Templates are denoted by curly brackets and contain a text, for example, {Patient.id}. There is no intrinsic meaning to the bracketed text. The semantics of substitution
SHOULD be defined in the corresponding HCP. Furthermore, it is RECOMMENDED that the implementer choose the bracketed text to hint at the proper substitutions, as follows:
If the substitution is a resource id or property, use the resource id and dot notation to indicate an element or attribute that resolves to a string, for example, {Patient.id}
For dates and times, use an ISO 8601 [8] symbol or string , such as YYYY, MM, DD, or YYYY-MM-DD
If neither of the above applies, any descriptive text can be used
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
258
259
260
261
252
253
254
255
256
257
262
263
264
265
266
267
238
239
240
241
242
243
244
245
246
247
248
249
250
251
HL7 hData Record Format 2.0
Templates allow the implementer to create "dependent resources" that are owned by an existing resource. A
"dependent resource" typically has an implicit life-cycle dependency on its parent. When a parent resource is deleted, the dependent resources are typically also deleted (however this behavior is application-dependent and should be documented in an HCP).
It is RECOMMENDED to use the following section pattern for dependent resources:
../[resourceType]/{resource.id}/../[dependentResourceType]/{dependentResource.id}
Consider the following example. In the DICOM logical model [9], an imaging study such as an MRI is composed of a number of series, and each series has a number of images. Based on the dependent resource URI pattern, the path to an image resource could be 1 :
../Patients/1234/Radiology/Studies/567/Series/2/Images/@4
Including the Radiology section in this example does not break the dependent resource pattern, but might be included by the implementer to make it clear that the studies are radiology studies, or to provide a place in the hierarchy below which other radiology-related resources might be added. The corresponding templated path is:
../Patients/{Patient.id}/Radiology/Studies/{Study.id}/Series/{Series.id}/Images
Now suppose that the Studies section has been defined to contain resources of resourceType “Study”, defined at the behavior level in an HCP to contain all radiology studies associated with the patient, and the Series section has been defined to contain resources of resourceType “Series”, and defined at the behavioral level in an HCP to contain all Series associated with a given Study. Suppose as well that the templated sections are defined without a resourceType (i.e., they may not contain resources).
In this case, to obtain the list of Series in a Study 567 as an Atom feed, the user would do a read operation (in
HRT, an HTTP GET) on the path:
../Patients/1234/Radiology/Studies/567/Series (Read returns Atom feed of all Series in Study 567)
To get the resource representing Study 567, the read operation must include the resourcePrefix:
../Patients/1234/Radiology/Studies/@567 (Read returns Study 567)
The “@” sign helps clarify to the server that it should not treat “567” as a section name. The disambiguation sections and resources is the rationale for requiring the resourcePrefix in paths that involve templates.
Contrast the previous example with this one:
../Patients/1234/Radiology/Studies/567 (Read returns an empty list; no resources in section 567)
Another potential use of templates is to list resources by date 2 , for example:
1 Using “@” as the resourcePrefix for clarity
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
293
294
295
296
297
298
299
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
268
269
270
271
272
273
274
275
276
HL7 hData Record Format 2.0
../Patients/{Patient.id}/Radiology/Studies/{YYYY}/{MM}/{DD}
Given this pattern and appropriate behavioral description, the path ../Patients/1234/Radiology/Studies/2012 is a section whose contents are Studies from the year 2012. Similarly, reading from
../Patients/1234/Radiology/Studies/2012/11 would return a list of Studies from November 2012. In contrast, reading the following path would either return a Study whose id is 2012, or generate an error if that resource did not exist:
../Patients/1234/Radiology/Studies/@2012 (Read returns Study 2012 or no such resource error)
It is valid in hData to have the same resource in multiple sections. In the example, the same Study resource can appear in each of the following sections:
../Patients/1234/Radiology/Studies
../Patients/1234/Radiology/Studies/2012
../Radiology/Studies/2012 where the latter section provides access radiology studies in a patient-independent manner. Despite the fact that a resource can be accessed through multiple sections, there is still only one underlying resource, and any updates would be applied to the underlying resource.
Templates are used in the root file to define the HDR, but templates MUST NOT appear in requests to the server. Upon receiving a request, the server will find the appropriate section by matching the section path. If the URL does not match any template, the HRT will signal an error (for REST transport, HTTP 404). The creator of the HDR SHOULD be certain that the matching process will result in a unique section without consideration of the template variable value. An example of bad practice, which does not follow the dependent resource pattern, is the following:
../{Patient.id}/{Study.id}/{Series.id} (or ../1234/567/2) (Bad practice)
While not forbidden by this standard, this section structure would lead to unreadable paths, potentially indeterminate for the server trying to determine the correct section by matching a given specific path to multiple templates.
A resource is a logical entity that may have multiple physical (“on the wire”) representations [10]. The resourceType refers to the class or category of the entity, for example, Condition, Procedure, Allergy, or Visit.
Sections MUST NOT contain more than one type of resource. The resources in a section MUST correspond by type with the resourceTypeID registered in the root document under the section.
Sometimes, an implementer might want to have a section that groups multiple types, for example, to group all items related to an office visit (observations, labs, medications, etc.). In this case, we recommend that the
2 In this case the YYYY hint is preferred to {Study.date}, because the latter would suggest that the user substitute an xs:date, not just the year associated with the Study.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
300
301
302
303
304
305
306
307
308
309
HL7 hData Record Format 2.0 implementer define a resource type to represent the group, for example, an office visit resource. This resource should have the capability of including related items as links. In this way, the section can have one consistent resourceType, but still provide access to a heterogeneous group of items.
Each resourceType MUST have at least one representation. The representation denotes a representation of the resource suitable for exchange, i.e., a wire format for the resource. Each representation MUST have a media type; if not stated, the media type is assumed to be “application/xml”. Each representation may include validators, used to by client and/or server to confirm that an exchanged resource conforms to the given type specfication. It is RECOMMENDED that the validator be a URL that resolves to directly the XSD file, the
Schematron, or similar validator.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
321
322
330
331
332
333
334
335
336
337
338
339
340
323
324
325
326
327
328
329
341
342
343
344
310
311
312
313
314
315
316
317
318
319
320
345
346
HL7 hData Record Format 2.0
Each section has an associated Atom feed that lists each resource in the section, and contains metadata pertaining to each resource. In the HRT REST implementation, the Atom feed is returned via an HTTP GET on the section URL. Atom feeds MUST conform to the Atom 1.0 Syndication Format [2].
Alternate JSON implementation?
Atom feed for subsections?
In this section, we profile the use of Atom in hData. This profile provides hData-specific semantics for Atom elements. Elements not specifically mentioned here MUST be used in accordance with the Atom 1.0
Syndication Format. For example, the atom specification states that <atom:author> MUST exist at either the feed level or the level of individual entries, but is not required on entries if given for the feed.
The Atom feed MAY be extended to support additional features.
The namespace for the following elements is atom, unless otherwise stated:
title(xs:string, 1) - This REQUIRED element SHOULD provide a human-readable text description of the feed.
id(xs:anyURI, 1) - This REQUIRED element MUST provide a unique identifier for the feed. It is
RECOMMENDED to use a URI in the urn:uuid schema.
updated(xs:dateTime, 1) - This REQUIRED element MUST provide the time accurate to the second when the section or any of its child elements were last modified. Modifications could be new, updated, or deleted resources or sections, or changes to the metadata.
link rel=”self” (0..1) - This element is REQUIRED for transports (such as HTTP) that identify sections by web resource identifiers (see [2], Section 4.2.7). In this case, the @href attribute MUST have the preferred URI for retrieving this Atom feed, i.e., the full URL path to the section including additional
search parameters. The @type attribute MUST be ”application/atom+xml”. link ref=”next” (0..1) - Since feeds can contain a large number of entries, a server may return a partial list of entries (see [11], Section 10.1). If so, the list MUST contain a link element with ref=”next”, whose
"href" value is the URI of the next partial list. The feed MAY provide a link elements with “rel” attribute values of “previous”, “first”, and “last”, that can be used to navigate through the complete set of entries. The first such partial list returned MUST contain the most recently edited member resources, next partial list will contain the next most recently edited set of resources, and so on [11].
link ref=”previous” (0..1) - see above
link rel=”first” (0..1) - see above
link ref=”last” (0..1) - see above
entry(0..*) - This element contains represents an individual resource, acting as a container for metadata and data associated with the resource.
The namespace for the following elements is atom, unless otherwise stated:
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
352
353
354
355
356
357
358
359
347
348
349
350
351
360
361
362
363
364
365
366
367
377
378
379
380
381
382
383
368
369
370
371
372
373
374
375
376
384
385
HL7 hData Record Format 2.0
title(xs:string, 1) - This REQUIRED element contains a human-readable text short description of the resource.
id(xs:string, 1) - This REQUIRED element is a version-independent reference to the resource. It is
RECOMMENDED to use a URL whose tail element is the logical id of the resource.
link(0..1) - This element is REQUIRED if the entry contains no content element. The @href attribute of the link MUST have a globally unique URI that resolves to the specific version of the resource referred to by the entry (if versioning is not supported, then the href MUST resolve to the resource). The @type
published(xs:dateTime, 0..1) - This OPTIONAL element contains the time the resource was initially created or first available. If the resource was derived from another origin, this element contains the time of derivation.
updated(xs:dateTime, 1) - This REQUIRED element contains the last modified time of the resource. If the resource has never been updated, this element MUST use the published time.
content(0..1) - This OPTIONAL element MAY contain a representation of the resource under the following conditions: o The representation of the resource matches the representation of the Atom feed (e.g., XML with XML, or JSON with JSON), o There is no privacy or authorization concern releasing the resource to all users that can access the Atom feed. If there are any privacy or security concerns, the resource MUST NOT be included in the feed, and o There is no performance concern regarding having the additional material in the feed.
Although the HRF is content agnostic, the HRF provides optional metadata augmentation for content models that do not natively support the data necessary for understanding the source, history, and other context information associated with the resource. Extension is unnecessary for some content models that include context information as part of the content model. For example, FHIR defines a Provenance resource that tracks information about the entities, activities, and people involved in producing a resource. In this case,
Provenance is integral to the logical model, not metadata that lives somewhere outside the model. However, there are other resource types, such as jpg images and pdf documents, where context cannot be easily added to the resource.
In the following, all elements and attributes are from the hrf-md namespace, unless otherwise specified.
confidentiality (0..1, xs:string) – This optional element contains controls for confidentiality. It is
RECOMMENDED to use a clinical document confidentiality code from CDA R2 [12]
pedigree(0..*) - This OPTIONAL element represents the activities, parties, and additional information involved in producing, modifying, or distributing a resource. It is RECOMMENDED to include one pedigree element for each significant lifecycle event affecting the resource (see below).
Elements of <pedigree>:
eventType (xs:string, 1) - It is RECOMMENDED to use one of the following event types, derived from the HL7 EHR Lifecycle Model [13]:
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
420
421
422
423
424
425
426
427
413
414
415
416
417
418
419
403
404
405
406
407
408
409
410
411
412
395
396
397
398
399
400
401
402
386
387
388
389
390
391
392
393
394
HL7 hData Record Format 2.0 o originate - initial event of creating the resource o receive - initial or update event of receiving this resource from an external party o amend - information in the resource was updated (use if no more specific action applies) o translate - language translation was provided o verify - a party has reviewed and verified the resource o attestComplete - a party has confirmed the resource is complete o attestAccurate - a party has confirmed the resource is correct o view - the resource is accessed or viewed o transmit - a copy of the resource has been provided to a third party o deidentify - removing identifying information from the resource o reidentify - adding identifying information to the resource o converge - information from other sources has been merged into this resource o archive - resource was copied to an archive o destroy - resource was marked as deleted o deprecate - record is marked as deprecated
recorded(xs:dateTime,1) - The time the event was recorded
subject(xs:anyURI,0..1) - A identifier of the resource produced as a result of the event, which may be a version-specific URI of the resource. If not provided, it is assumed the subject is the logical resource described by the entry.
description(xs:string,0..1) - An OPTIONAL description of the event
party(1..*) – This REQUIRED element identifies the persons, organizations, and information sources involved in the event
signature (0..*) - This OPTIONAL element contains the signature information on the resource or this metadata. This signature MUST conform to the W3C XML Signature Syntax and Processing (Second
Edition) [14] specification.
Elements and attributes of <party>:
type(xs:string,1) - Identifies the type of party. It is RECOMMENDED to use the following value set: o practioner - the participant was a healthcare provider o patient - the participant was the patient or a person acting on behalf of the patient o organization - the participant was an organization o software - the participant was a software process o resource - the participant was a resource o document - the participant is an external document
role (xs:string, 1) - This attribute indicates the specific role of the party. It is RECOMMENDED to use the following list of roles, which if used MUST semantically correspond to the authoritative list of participant roles in HL7 CDA R2 header: o authenticator - provided legal attestation o author - originated the resource o custodian - acted on the resource as an information maintainer o enterer - entered the information o informant - human who provided information that contributed to the resource
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
448
449
450
451
452
453
454
455
456
439
440
441
442
443
444
445
446
447
433
434
435
436
437
438
428
429
430
431
432
HL7 hData Record Format 2.0 o participant - participated in some other role besides ones mentioned here o performer - performed the activity o source - non-human information source from which the resource is derived o target - received information o verifier - validated the completeness or accuracy of the record
identifier (xs:string, 1) –An identifier of the party, such as a name or URI.
description(xs:string, 0..1) - Human-readable description of the party
pedigree(pedigree, 0..*) - If the party is an information source (the type is resource or document and the role is source), pedigree elements can be used recursively to give the pedigree of that information source. In this way, the metadata can provide a complete trace of all information sources, back to origin.
Elements and attributes of <signature>:
method (xs:string, 0..1) - This optional attribute indicates what method was used to transform binary resource media types into XML files for signature. Currently the only permitted methods are xml and base64. “xml” is the default XML signature over XML documents. “base64” uses the Base64 Transform from [14], 6.6.2 on the binary octet stream.
ds:Signature (ds:Signature, 1) - An XML Signature. This Signature MUST contain:
1.
A valid Reference to either the metadata or the resource
2.
The ds:KeyInfo for the signer (optional with DSig - required here)
The metadata for a resource is only valid for the system that currently hosts the resource. If an HDR is copied in portions or in its entirety, the system to which it is copied MUST recompute the metadata according to the following rules:
1.
The <atom:id> MUST be kept unchanged.
2.
The pedigree MUST be updated by adding a new pedigree element.
3.
Confidentiality SHOULD be copied verbatim.
If a specific hData Content Profile requires additional or special metadata processing instructions, these processing instructions MUST be specified in the content profile.
457
458
459
460
461
462
463
An hData Content Profile (HCP) is an implementation guide for hData. HCPs are needed because hData does not stipulate the specific layout, purpose, or behavior of an HDR. An HCP can be created by any person or organization who wishes to standardize the use of hData for a particular purpose or business domain. By creating, sharing, and conforming to HCPs, information exchange partners can align and standardize their information services. Clients can read the root file and determine which content profiles are implemented, then reference the documentation of those HCPs to learn more about the HDR.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
472
473
474
475
482
483
484
485
486
487
488
489
476
477
478
479
480
481
490
491
492
493
494
495
496
497
464
465
466
467
468
469
470
471
HL7 hData Record Format 2.0
HCPs are not required to use hData. A HDR can be created without conforming to any external documentation.
However, this approach naturally tends to limit the use of the HDR to small teams that share a common understanding of the HDR. The main purpose of an HCP is to enhance the scalability of information exchange beyond small, highly-connected groups by encouraging uniform use.
Note that a single HDR can be compliant with multiple HCPs. In this case, the implementer should copy and combine the information in the example root files from each HCP to create a single root file, creating a combined list of profiles, sections, and resourceTypes. Any conflicts in resourceTypeIDs that occur as a result of this process must be manually resolved.
Although the content and format of an hData Content Profile is not specified by this document, and is not part of the hData standard, there is certain information that implementers and clients will need to create or use an hData Record that conforms to an HCP, including:
An explanation of the purpose and applicable business requirements for the HCP
A list of the required and optional sections and their paths relative to the base URL, establishing the hierarchical structure of the HDR
A list of all the resource types and documentation, or reference to source documentation, explaining the syntax and semantics of the resource. If the HCP contains XML resources, a complete list or reference to all XML schemas should be included.
A sample root file for the HCP that can be copied by an implementer wanting to create a compliant
HDR.
If the domain for the HCP must adhere to a behavioral model or a set of business rules, these should be documented with applicable UML diagrams or similar documentation, including the lifecycle of resources, if any.
Security requirements, such as privacy policy, patient consent, and access control that apply to the data stored in the overall record, as well as each section.
Documentation of additional testing or conformance requirements, if any.
A version-aware URL for identification that should resolve to a publicly accessible HTML resource that contains links to all documents needed for the HCP. This is needed for any root file conforming to the
HCP.
If there are multiple versions of the HCP, a change log to help users track changes between versions.
Any suitable technical document format can be used for an HCP. For example, if the HCP is to be used in the US realm by US Federal Government, authors could adopt the U.S. National Information Exchange (NIEM)
Information Exchange Package Documentation (IEPD) format.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
498
499
500
501
502
503
504
505
506
HL7 hData Record Format 2.0
This specification does not specify how patient consent, privacy policy, and access controls are to be implemented. Any underlying transport mechanism MUST be able to provide a system for providing functionality to limit access to the overall record or portions thereof. Requirements for access to the overall record, as well as individual sections MUST be documented in detail in the hData Content Profile (see Section
hData Content Profile.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
507
508
509
510
HL7 hData Record Format 2.0
MUST validate against this schema definition.
511 TO DO: ROOT SCHEMA
512
513
514
515
documents MUST validate against this schema definition.
516 TO DO: METADATA SCHEMA
517
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
HL7 hData Record Format 2.0
518
519
520
521
522
This section outlines a simple hData Record that contains HL7 Continuity of Care Documents (CCD), simplified documents containing information about allergies, medications, and vital signs, and radiology imagery. The following figure illustrates the high-level structure of the example record. hData Record root.xml
Supports CCD, allergies, medication, vital signs, DICOM
X-Ray org.hl7.ccd
Contains CCD documents for the patient.
Holds the hData metadata for the
CCDs org.hl7.patientid
Contains patient identi fier information for the patient.
Holds the hData metadata for the images com.provider.face
Contains PNG facial image for the patient.
Holds the hData metadata for the images org.hl7.simpli
fied
Document
Document
CCDs
Document
Document
XML
Document
Document
PNGs allergies
Contains simpli fied allergy documents for the patient.
Holds the hData metadata for the allergy documents
Document
Document allergies medications
Document
Document medications vital signs
Document
Document vital signs
523
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
542
543
544
545
546
537
538
539
540
541
529
530
531
532
533
534
535
536
524
525
526
527
528
HL7 hData Record Format 2.0
record outlined above, the root.xml document looks like this:
This root document contains some basic metadata about itself: an identifier, the version of the hData Record
Format that it conforms to, as well as its created and modified date.
The root document also contains a list of resourceTypes. ResourceTypes identify the formats of resources. The record format only requires that a globally unique string is used to identify an resourceType. It is recommended, but not necessary, that the string be a URL where information can be found about the resourceType. Note that the use of URLs with the domain part of the author guarantees global uniqueness. If the resourceType is describing XML documents, it is again recommended that the URL resolve to a RDDL document that provide a machine-resolvable link to the XML Schema for the documents that this resourceType is describing. For non-XML content, a description of the content type (such as e.g. PNG documentation) should be provided at the URL used for identifying the resourceType.
The sections identify their default content by referencing the resourceTypeId attributes of the resourceType nodes. They also contain the path segment that is used to construct the full path to the section. It should be noted that sections can be nested. In this example, the results folder contains an empty folder that cannot contain documents since its has no resourceTypeID. However, it will still have an Atom feed which will provide links to the nested sections.
sample feed for the /org.hl7.simplified/allergies section. Other sections will have very similar feeds, that describe contained resources and nested sections.
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
547
HL7 hData Record Format 2.0
548
549
[1] Health Level 7 International, "Clinical Document Architecture Release 2," May 2005. [Online]. Available: http://www.hl7.org/implement/standards/product_brief.cfm?product_id=7. [Accessed July 2013].
[2] IETF Network Working Group, "The Atom Syndication Format," December 2005. [Online]. Available: http://www.ietf.org/rfc/rfc4287. [Accessed 1 July 2013].
[3] G. Grieve, E. Kramer and L. Mckenzie, "FHIR v0.09," 2013. [Online]. Available: http://hl7.org/implement/standards/fhir/. [Accessed 1 July 2013].
[4] G. Beuchelt and et al., "hData RESTful Transport v 1.0," 2012. [Online]. Available: http://www.omg.org/spec/HData/1.0/Beta2.
[5] Health Level Seven International, "HL7 Resource Location and Updating Service," 2006.
[6] IETF Network Working Group, "Key words for use in RFCs to Indicate Requirement Levels," March 1997.
[Online]. Available: http://www.ietf.org/rfc/rfc2119.txt. [Accessed 1 July 2013].
[7] IETF, "URI Generic Syntax," January 2005. [Online]. Available: http://tools.ietf.org/html/rfc3986. [Accessed
July 2013].
[8] International Organization for Standarization (ISO), "Date and Time Format - ISO 8601," December 2004.
[Online]. Available: http://www.iso.org/iso/home/standards/iso8601.htm. [Accessed 1 July 2013].
[9] National Electrical Manufactureres Association (NEMA), "Digital Imaging and Communications in Medicine
(DICOM)," Medial Imaging & Technology Alliance, August 2011. [Online]. Available: http://medical.nema.org/standard.html. [Accessed 1 July 2013].
[10] R. Fielding, "Architectural Styles and the Design of Network-based Software Architectures," Irvine, 2000.
[11] IETF Network Working Group, "The Atom Publishing Protocol," October 2007. [Online]. Available: http://www.ietf.org/rfc/rfc5023. [Accessed July 2013].
[12] Health Level Seven International, "CDA Relase 2," [Online]. Available: http://www.hl7.org/implement/standards/product_brief.cfm?product_id=7.
[13] Health Level Seven International, "HL7 EHR System Functional Model, R1.1," July 2012. [Online]. Available: http://www.hl7.org/implement/standards/product_brief.cfm?product_id=269. [Accessed July 2013].
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511
550
551
HL7 hData Record Format 2.0
[14] W3C Consortium, "W3C XML Signature Syntax and Processing (Second Edition)," June 2008. [Online].
Available: http://www.w3.org/TR/xmldsig-core. [Accessed July 2013].
©2009-13 The MITRE Corporation. Unlimited distribution. Public Release Approval 09-4511