This page is part of the FHIR Specification (v0.06: DSTU 1 Ballot 2). 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

Community Input (wiki)

JSON Format 2.7

Informative Section: Due to a series of issues around the formal standardization of the JSON representation, the standard JSON representation for resources is only informative.

Though the formal representation of FHIR resources is in XML, many systems wish to use JSON to exchange the resources and it is useful to standardize a single JSON format for this use. The JSON format for the resources follows the standard XML format closely so XPath queries can easily be mapped to query the JSON structures:

The names for the JSON object members are the same as the names of the elements and attributes in XML, including for elements that may repeat.
In the data types, the value representations for primitive types such as string, decimal, etc. are identical between the XML and the JSON form (including instant, which is represented as plain text, not in one of the proposed JSON custom date formats)
Just as in XML, JSON property attributes never have empty values; omit a value if it is empty.

There are differences too:

There are no namespaces in the JSON representation.
JSON does not have a notion of attributes versus elements, so attributes (xml:id) are treated as JSON object members (see below for more details).
JSON has a notation for arrays, which are used to represent repeating elements. Note that this is the case, even if they do not repeat in the actual instance.
The XHTML <div> element in the Narrative datatype is represented as a single escaped string of XHTML

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 will provide XML <--> JSON conversion functionality that accommodates these FHIR-specific characteristics.

JSON representation of primitive types 2.7.1

FHIR elements with primitive values are represented as JSON object members of the same name with their value encoded as a string. Native JSON types other than "string" are never used, to guarantee equivalence of the serialized representation between XML and JSON.

Primitive elements used inside the FHIR datatypes cannot have an 'id' attribute, so they are rendered in JSON as a property and value:

 <date>1972-11-30</date>

is represented in JSON as

"date": "1972-11-30"

Primitive elements in resources can have 'id' attributes, so their JSON representation uses a JSON object with members '_id' and 'value', which contains the actual primitive value as string:

 <dob id='314159'>1972-11-30</dob>

is represented in JSON as:

"dob": { "_id": "314159", "value": "1972-11-30" }

Repeating elements 2.7.2

Repeating elements are rendered within a JSON array with the name of the element, so a repeating <dob> element in

 <dob>2011-11-30</dob>
 <dob id='314159'>1972-11-30</dob>

is represented in JSON like so:

"dob": [
	{ "value": "2011-11-30" },
	{ "_id": "314159", "value": "1972-11-30" }
  ]

JSON representation of composite datatypes 2.7.3

Resources and other composite 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>official</use>  
    <given>Karen</given>
    <family id="n1">Van</family>
  </name>
  <text>
    <status>generated</status>
    <div xmlns="http://www.w3.org/1999/xhtml">...</div>
  </text>
</Person>

is represented in JSON as:

{
  "Person" : {
    "name" : [{
      "use" : "official",
      "given" : [{
         "value" : "Karen" 
        }],
      "family" : [{
         "_id" : "n1",
         "value" : "van"
        }]
     }],
    "language" : [
      {
        "code" : { "_id" : "lang-1", "value" : "dut" },
        "use" : { "value" : "fluent" }
      },
      {
        "code" : { "value" : "cmn" },
        "use" : { "value" : "useable" }
      }],
    "text" : {
      "status" : "generated",
      "value" : "<div xmlns='http://www.w3.org/1999/xhtml'>...</div>"
    }
}

Things to note here are:

Because the primitive element 'id' is in a resource, it is serialized as a JSON object.
In the family part of 'name', the '_id' is added as the first member.
The 'code' within member 'language' is a part of the resource definition and therefore serialized as a JSON object, whereas the member 'use' within 'name' is a primitive inside a datatype and therefore serialized as a JSON string value.
The XHTML content in the 'div' element which is in the Narrative element 'text' is represented as an escaped string in the value property in JSON. The xhtml's root element needs to be a <div> in the xhtml namespace.

JSON Bundles (Atom feeds) 2.7.4

There are several initiatives to define a JSON format for Atom, all of which are suffering from having to simulate properties, namespaces and other xml-specific features. Instead, FHIR defines 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:

{
  "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"
    }],
  "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" : "Person",
          "scheme" : "http://hl7.org/fhir/resource-types"
        }],
      "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.

Bundling versions - deletion 2.7.5

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.

Binary Resources 2.7.6

There are situations where it is useful or required to represent binary resources in the bundle. These are resources that are referred to from FHIR Resources (usually via a URI), and where it is convenient to include these in the feed directly rather than leaving them by reference.

When binary resources are represented in the feed, they are enclosed as base64 encoded content along with a content-type, which is the mime-type as it would be specified in HTTP:

  ...
      "content" : {
        "Binary" : {
          "contentType" : "[mime type]",
          "content" : "[base64 of data]"
        }
      },
      "summary" : "<div xmlns=\"http://www.w3.org/1999/xhtml\">Binary Resource</div>"
  ...

The summary should be some equivalent to "Binary Resource" in an appropriate language.

This is an old version of FHIR retained for archive purposes. Do not use for anything else
Implementers are welcome to experiment with the content defined here, but should note that the contents are subject to change without prior notice.
© HL7.org 2011 - 2012. FHIR v0.06 generated on Tue, Dec 4, 2012 00:04+1100. License