2nd DSTU Draft For Comment
This page is part of the FHIR Specification (v0.4.0: DSTU 2 Draft). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions 
. Page versions: R5 R4B R4 R3 R2
The JSON representation for a resource is described using this format:
todo - develop this
In the current absence of a specific json description, the JSON representation is described relative to the XML representation:
There are differences too:
The JSON format for the resources follows the standard XML format closely to make interconversion easy, and so that XPath queries can easily be mapped to query the JSON structures. However the differences - particularly the repeating element one, which cannot be avoided - mean that generic XML --> JSON converters are not able to perform correctly. The reference platforms provide XML <--> JSON conversion functionality that accommodates these FHIR-specific characteristics.
The formal mime type for this format is application/json+fhir.
An element that has a maximum cardinality of >1 (e.g. x..* in the definitions) may occur more than once in the instance. In XML, this is simply done by repeating the XML element multiple times. In JSON, this is done by using an array type. Note that:
<coding> <system value="http://snomed.info/sct"/> <code value="104934005"/> </coding/> <coding> <system value="http://loinc.org"/> <code value="2947-0"/> </coding/>
is represented in JSON like this:
"coding": [
{
"system" : "http://snomed.info/sct",
"code" : "104934005"
},
{
"system" : "http://loinc.org",
"code" : "2947-0"
}
]
FHIR elements with primitive values are represented in two parts:
The FHIR types integer and decimal are represented as a JSON number, the FHIR type boolean as a JSON boolean, and all other types are represented as a JSON string which has the same content as that specified for the relevant data type. Whitespace is always significant (i.e. no leading and trailing spaces for non-strings).
<code value="abc"/> <!-- code --> <date value="1972-11-30"/> <!-- dateTime --> <deceased value="false" /> <!-- boolean --> <count value="23" /> <!-- integer -->
is represented in JSON as
"code" : "abc", "date" : "1972-11-30", "deceased" : false, "count" : 23
When using a JavaScript JSON.parse() implementation, keep in mind that JavaScript natively supports only one numeric datatype, which is a floating point number. This can cause loss of precision for FHIR numbers. You may want to use a custom parser and big number library (e.g. https://github.com/jtobey/javascript-bignum) if this is a concern.
If the value has an id attribute, or extensions, then this is represented as follows:
<dob id="314159" value="1970-03-30" >
<extension url="http://example.org/fhir/ExtensionDefinition/text">
<valueString value="Easter 1970"/>
</extension>
</dob>
is represented in JSON as:
"dob": "1972-11-30",
"_dob": {
"id": "314159",
"extension" : [ {
"url" : "http://example.org/fhir/ExtensionDefinition/text",
"valueString" : "Easter 1970"
}]
}
Note: If the primitive has an id attribute or extension, but no value, only the property with the "_" is rendered.
In the case where the primitive element may repeat, it is represented in two arrays. JSON null values are used to fill out both arrays so that the id and/or extension are aligned with the matching value in the first array, as demonstrated in this example:
<code value="au"/>
<code value="nz">
<extension url="http://hl7.org/fhir/ExtensionDefinition/display">
<valueString value="New Zealand a.k.a Kiwiland"/>
</extension>
</code>
is represented in JSON as:
"code": [ "au", "nz" ],
"_code": [
null,
{
"extension" : [ {
"url" : "http://hl7.org/fhir/ExtensionDefinition/display",
"valueString" : "New Zealand a.k.a Kiwiland"
}]
}
]
}
Note: when one of the repeating elements has no value, it is represented in the first array using a null. When an element has a value but no extension/id, the second array will have a null at the position of that element.
Design Note: The representation of primitive data types has been split into two parts like this in order to simplify the representation of simple primitive values without id or extensions. This does have the cost of making the representation of the id attribute and extensions more ungainly, but these are both rarely used with primitive data types.
Elements, and complex datatypes (types that contain named elements of other types) are represented using a JSON object, containing a member for each element in the datatype. Composites can have id attributes, which are converted to JSON member values, in the same manner as described for primitives. For example:
<person>
<text>
<status value="generated" />
<div xmlns="http://www.w3.org/1999/xhtml"><p>...</p></div>
</text>
<name>
<use value="official" />
<given value="Karen" />
<family id="a2" value="Van" />
</name>
</person>
is represented in JSON as:
{
"person" : {
"name" : [{
"use" : "official" ,
"given" : [ "Karen" ],
"family" : [ "Van" ]
"_family" : [ {"id" : "a2"} ]
}],
"text" : {
"status" : "generated" ,
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>...</p></div>"
}
}
Things to note here are:
A resource is a JSON object with a property "resourceType" which informs the parser which resource type this is:
{
"resourceType" : "Patient",
"text" : {
"status" : "generated" ,
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>...</p></div>"
}
etc...
}
Note that parsers cannot assume that the resourceType property will come first.
Design Note: This is a problem for several JSON -> Object serialisers that assume that the resourceType property does come first, including Json.NET. However some JSON generators do not give the authoring application control of the order of the property values, and so these implementations cannot inter-operate with implementations that make assumptions about order. Given that JSON says that the property values are an unordered map of name/value pairs, this specification cannot require that properties come in any particular order, though implementers may choose to fix the property order if they are able (and the reference platforms provided with this specification do so).
There is a sample file with many edge cases to help test JSON parsers.
todo
© HL7.org 2011+. FHIR DSTU (v0.4.0-4167) generated on Mon, Feb 23, 2015 09:24+1100.
Links: What's a DSTU? |
Version History |
Compare to DSTU1 |
|
Propose a change