This page is part of the FHIR Specification (v0.0.82: (v1.0.2: DSTU 1). 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

• Formats
• XML
• JSON
• RDF

1.12.5.2 1.18.2 Representing Resources in JSON Representation of Resources

Implementable Technology Specifications Work Group

Maturity Level : 5

Ballot Status : DSTU 2

Though the FHIR resources are The JSON representation for a resource is described using a representation based on XML, this specification also defines format:

{

  "resourceType" : "Element",
  // from Source: element #1
  "property1" : "<[primitive]>", // short description
  "property2" : { [Data Type] }, // short description
  "property3" : { // Short Description
    "propertyA" : { CodeableConcept }, // Short Description (Example)
  },
  "property4" : [{ // Short Description
    "propertyB" : { Reference(ResourceType) } // R!  Short Description
  }]
}

Using this format:

• To build a valid JSON representation instance of a resource, replace the resources. The JSON format contents of the property values with valid content as described by the type rules and content description found in the property value for each element
• In this example:
  1. property1 has a primitive data type; the value of the property will be as described for the resources follows stated type
  2. property2 has a complex data type; the standard XML format very closely value of the property is an object that has the content as described for the stated type
  3. property3 is an object property that contains additional properties (e.g. propertyA; the allowable properties are listed (but also include extensions as appropriate)
  4. property4 is an array property that contains items which are objects themselves. The items may have any of the types already encountered in points 1-3
  5. propertyA has a binding to make interconversion easy, and so a value set - the Short description is a link to the value set. In addition, the binding strength is shown
  6. propertyB is a reference to a particular kind of resource
• Property names are case-sensitive (though duplicates that XPath queries differ only in case are never defined)
• Properties can easily appear in any order
• XHTML is represented as an escaped string
• Objects are never empty. If an element is present in the resource, it SHALL have properties as defined for its type, or 1 or more extensions
• String property values can never be mapped to query empty. Either the property is absent, or it is present with at least one character of content
• The R! denotes that an element is mandatory - it must be present (or in an array, at least one item must be present)
• In this format, // is used for comments but these can't be in the JSON structures. instances
• The formal mime type character encoding is always UTF-8
• The MIME-type for this format is application/json+fhir. application/json+fhir .

Clients are free Given the way extensions work, applications reading JSON resources will never enocunter unknown properties. However once an application starts trading with other appplications that conform to later versions of this specification, unknown properties may be encountered. Applications MAY choose whether to implement ignore unknown properties in XML or JSON. Servers SHALL support XML, and can choose order to support JSON. Note that systems SHALL declare which format(s) they support foster forwards compatibility in this regard, but may also choose not to. Applications declare their Conformance Statement behavior with regard to unknown elements using Conformance.acceptUnknown .

1.18.2.1 Comparison with XML

The JSON representation format is described relative similar to the XML representation: format:

• The names for the JSON object members are the same as the names of the elements and attributes in XML, including elements that may repeat. Property names are case sensitive
• Just as in XML, JSON property attributes objects and arrays are never empty, and properties never have empty values; omit null values (except for a value special case documented below). Omit a property if it is empty
• JSON whitespace is not part of the contents of a resource. Applications MAY preserve the whitespace when handling resources, but are not required to do so. Note that digital signatures may depend on the whitespace

There are differences too: to XML:

• There are no namespaces in the JSON representation
• The type of the resource is represented differently in JSON - instead of being the name of the base object (there is none in JSON), it is carried as the property resourceType
• The order of properties of an object is not significant in the JSON representation, though order within an array SHALL be maintained
• JSON does not have a notion of attributes versus elements, so attributes (xml:id, value) (e.g. id , value ) are handled differently (see below)
• JSON has a notation for arrays, the array notation, which are is used to represent repeating elements. Note that arrays are used when the item might repeat, even if it does not repeat in a specific instance
• The XHTML <div> element in the Narrative datatype is represented as a single escaped string of XHTML. This is to avoid problems in JSON with mixed content, etc. The XHTML S SHALL still conform to the rules described for the Narrative
• There is no inherent support in JSON for a comment syntax. As a convention, content that would be comments in an XML representation is represented in a property with the name fhir_comments , which is an array of strings, which can appear on any JSON object. This is heavily used in example instances, e.g. in this specification, but not usually used in production systems (and production systems may choose to reject resources with comments in them)

These 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.

1.12.5.2.1 1.18.2.2 JSON Representation for repeating elements

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:

• The name of the array is singular - the same as the XML element
• An item that may repeat is represented as an array even in the case that it doesn't repeat so that the process of parsing the resource is the same either way

 <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"
   }
 ]

1.12.5.2.2 1.18.2.3 JSON representation of primitive elements

FHIR elements with primitive values data types are represented in two parts:

• A JSON property with the name of the element, which has a JSON type of number, boolean, or string
• a JSON property with "_" _ prepended to the name of the element, which, if present, contains the value's xml:id id and/or extensions (and comments, if there are any)

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

If the value has an id attribute, or extensions, then this is represented as follows:

 < id="314159" value="1970-03-30" >
   <extension url="http://example.org/fhir/extensions#text">
     <valueString value="Easter 1970"/>     

 <birthDate id="314159" value="1970-03-30" >
   <extension url="http://example.org/fhir/StructureDefinition/text">
     <valueString value="Easter 1970"/>

   </extension>
 </>

 </birthDate>

is represented in JSON as:

 "dob": "1972-11-30",
 "_dob": { 
   "id": "314159", 
   "extension": [{
      "url" : "http://example.org/fhir/extensions#text",

 "birthDate": "1970-03-30",
 "_birthDate": {
   "id": "314159",
   "extension" : [ {
      "url" : "http://example.org/fhir/StructureDefinition/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/Profile/tools-extensions#display">
     <valueString value="New Zealand a.k.a Kiwiland"/>     

   <extension url="http://hl7.org/fhir/StructureDefinition/display">
     <valueString value="New Zealand a.k.a Kiwiland"/>

   </extension>
 </code>

is represented in JSON as:

 "code": [ "au", "nz" ],
 "_code": [ 
   null, 
   { "extension": [{
      "url" : "http://example.org/fhir/extensions#text",
      "valueString" : "New Zealand a.k.a Kiwiland"
   }] }

 "_code": [
   null,
   {
     "extension" : [ {
        "url" : "http://hl7.org/fhir/StructureDefinition/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.

1.12.5.2.3 1.18.2.4 JSON representation of Elements, and Complex 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" />  

    <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:

• Both given and family are repeating XML elements, so they are serialised as an Array whether or not they repeat in this instance
• In the family part of 'name', name , the 'id' id is added represented in _family as described above
• The XHTML content in the 'div' div element which is in the Narrative element 'text' 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

1.12.5.2.4 1.18.2.5 JSON representation of Resources

A resource is a JSON object with a property "resourceType" 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.

1.12.5.2.5 1.18.2.6 Canonical JSON Bundle Representation

In JSON bundles Resources and/or Bundles may be digitally signed (see Bundle are represented using a JSON format that is tailored to and Provenance ).

This specification defines the specific needs following method for bundles. Each element canonicalizing FHIR resources, when represented as JSON:

• No whitespace other than single spaces in property values and in the XML feed definition has a JSON corresponding JSON object member with xhtml in the same name. For convenience, Narrative
• Order properties alphabetically
• Omit all properties that have a bundle has default value, if a "resourceType" default value is defined
• Omit all comments ( fhir_comments property with as defined above)

This canonicalization method is identified by the value of "Bundle" ("resourceType" URL http://hl7.org/fhir/canonicalization/json . The following additional canonicalization URLS are also defined:

http://hl7.org/fhir/canonicalization/json#data	The narrative ( Resource.text ) is used for consistency with resources, even though a bundle omitted prior to signing (note the deletion is at Resource.text , not a resource, but a container of resources). Here Resource.text.div )
http://hl7.org/fhir/canonicalization/json#static	In addition to narrative (Resource.text), the Resource.meta element is an example feed returning search results for a person query: { "resourceType" : "Bundle", "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 Term]", "label" : "[Tag Label]", "scheme" : "[Tag Scheme]" }], "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" : "[Tag Type]" }], "content" : { "resourceType" : "Patient", ...other Patient elements... }, "summary" : "<div xmlns=\"http://www.w3.org/1999/xhtml\">(text summary)</div>", }, ... other entries .... ], "signature" : "<signature xmlns=\"http://www.w3.org/2000/09/xmldsig\">...</signature>" } Note that property names for elements that can repeat removed. This makes the signature robust as the content is moved from server to server, or workflow and access tags are not pluralized for consistency of overall approach (as described above). added or removed
http://hl7.org/fhir/canonicalization/json#narrative	The mime type for a JSON bundle method only covers the Resource.id and Narrative is also application/json+fhir. 1.12.5.2.5.1 Bundling versions - deletion retained

When returning a set of versions for a resource, a version might indicate a deletion. While the XML format follows RFC 6721 , These canonicalization methods allow system the JSON format needs to use an entry item flexiibility to retain sign the logical order various portions of entries: the resource that matter for the workflow the signature serves.

.. 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 Note: One consequence of deletion signing the document is given. An id SHALL be provided, that URLs, identifiers and a link may internal references are frozen and cannot be changed. This might be provided. 1.12.5.2.5.2 Binary Resources When a binary resource is represented in a JSON bundle, it is represented as base64 encoded content along with a content-type, which is the mime-type as desired feature, but it would be specified in HTTP, like this: { "resourceType" : "Binary", "contentType" : "[mime type]", "content" : "[base64 of data]" } 1.12.5.2.5.3 Signatures may also cripple interoperability between closed ecosystems where re-identification If a bundle has a signature, the signature has a JSON property "signature", whose property value frequently occurs. For this reason, it is an XML string recommended that is a valid XML systems consider carefully the impact of any signature processes. The impact of signatures on Document bundles element. and their related processes is the most well understood use of digital signatures.

{ "resourceType" : "Bundle", ... metadata and entries as described above.... "signature" : "<signature xmlns=\"http://www.w3.org/2000/09/xmldsig\">...</signature>" }