. Page versions: R5 R4B R4 R3 R2This page is part of the FHIR Specification (v0.11: DSTU 1 Ballot 3). 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
Though the representation of FHIR resources is described in XML, FHIR also defines a JSON representation of the resources. The JSON format for the resources follows the standard XML format very closely to make interconversion easy, and so that XPath queries can easily be mapped to query the JSON structures. The formal mime type for this format is application/fhir+json.
Clients are free to choose whether to implement in XML or JSON. Servers must support XML, and can choose to support JSON. Note that systems must declare which format(s) they support. Also, the reference implementations include bi-direction conversion functionality between the two formats.
The JSON representation is described relative to the XML representation:
There are differences too:
These 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.
FHIR elements with primitive values are represented as a JSON object of the same name with a the value attribute of the element in a "value" property and (optionally) "_id" for the id attribute. JSON native types are used for boolean, integer and decimal, all other primitives are rendered as strings, and the whitespace is always significant (i.e. no leading and trailing spaces for non-strings). The JSON value "null" is never used.
<date value="1972-11-30"/> <deceased value="false" /> <count value="23" />
is represented in JSON as
"date" : { value: "1972-11-30" }
"deceased" : { value: false }
"count" : { value: 23 }
All XML elements can have an 'id' attribute, which is represented in JSON as a property of name "_id":
<dob id="314159" value="1972-11-30" />
is represented in JSON as:
"dob": {
"_id": "314159",
"value": "1972-11-30"
}
Repeating elements are rendered within a JSON array with the name of the element, so a repeating <dob> element in XML
<dob value="2011-11-30" /> <dob id="314159" value="1972-11-30" />
is represented in JSON like so:
"dob": [
{ "value": "2011-11-30" },
{ "_id": "314159", "value": "1972-11-30" }
]
Resources, elements, and 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 members values, in the same manner as described for primitives. It comes before all other members. For example:
<Person>
<name>
<use value="official" />
<given value="Karen" />
<family id="n1" value="Van" />
</name>
<text>
<status value="generated" />
<div xmlns="http://www.w3.org/1999/xhtml">...</div>
</text>
</Person>
is represented in JSON as:
{
"Person" : {
"name" : [{
"use" : { "value" : "official" },
"given" : [{
"value" : "Karen"
}],
"family" : [{
"_id" : "n1",
"value" : "van"
}]
}],
"text" : {
"status" : { "value" : "generated" },
"div" : "<div xmlns='http://www.w3.org/1999/xhtml'>...</div>"
}
}
Things to note here are:
In JSON bundles are represented using a JSON format that is tailored to the specific needs for bundles. Each element in the Xml feed definition has a JSON corresponding JSON object member with the same name. Here is an example feed returning search results for a person query:
{
"feed" : {
"title" : "Search result",
"updated" : "2012-09-20T12:04:45.6787909+00:00",
"id" : "urn:uuid:50ea3e5e-b6a7-4f55-956c-caef491bbc08",
"link" : [{
"rel" : "self",
"href" : "http://ip-0a7a5abe:16287/fhir/person?format=json"
}],
"category" : [{
"term" : "[Tag Uri]",
"label" : "[Tag Label]",
"scheme" : "http://hl7.org/fhir/tag"
}],
"totalResults" : 12,
"entry" : [{
"title" : "Resource of type Person, with id = 1 and version = 1",
"link" : [{
"rel" : "self",
"href" : "http://fhir.furore.com/fhir/person/@1/history/@1"
}],
"id" : "http://fhir.furore.com/fhir/person/@1",
"updated" : "2012-05-29T23:45:32+00:00",
"published" : "2012-09-20T12:04:47.3012429+00:00",
"author" : [{
"name" : "Grahame Grieve / HL7 publishing committee"
}],
"category" : [{
"term" : "[Tag Uri]",
"label" : "[Tag Label]",
"scheme" : "http://hl7.org/fhir/tag"
}],
"content" : {
"Person" : { ...person content in JSON... }
},
"summary" : "<div xmlns=\"http://www.w3.org/1999/xhtml\">(text summary)</div>",
},
... other entries ....
]
}
}
Note that property names for elements that can repeat are not pluralized for consistency of overall approach. The mime type for a json bundle is also application/fhir+json.
When returning a set of versions for a resource, a version might indicate a deletion. While the XML format follows RFC 6721, the JSON format needs to use an entry item to retain the logical order of entries:
.. feed ..
"entry" : [
... other entries ....,
{
"deleted" : "2012-05-29T23:45:32+00:00",
"id" : "http://fhir.furore.com/fhir/person/@1",
"link" : [{
"rel" : "self",
"href" : "http://fhir.furore.com/fhir/person/@1/history/@1"
}],
}, ... other entries ....
]
... feed ...
The entry is known to be deleted because a date of deletion is given. An id must be provided, and a link may be provided.
There are situations where it is useful or required to handle pure binary content as resources. Typically, this is when the binary content is referred to from other FHIR Resources. The resource can contain any content, whether text, image, pdf, zip archive, etc. These resources are served in their native form on the rest interface, but can also be represented in XML or JSON, such as when including these resources in a bundle (used when it is convenient to include these in the feed directly rather than leaving them by reference).
In JSON, Binary resources are represented like this:
"Binary" : {
"contentType" : "[mime type]",
"content" : "[base64 of data]"
}