This page is part of the FHIR Specification (v0.0.82: DSTU 1). 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 1.12.5.2 Representing Resources in JSON Though the FHIR resources are described using a representation based on XML, this specification 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/json+fhir. Clients are free to choose whether to implement in XML or JSON. Servers SHALL support XML, and can choose to support JSON. Note that systems SHALL declare which format(s) they support in their Conformance Statement . The JSON representation is described relative to the XML representation: 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 never have empty values; omit a value 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: There are no namespaces in the JSON representation The type of the resource is represented differently in JSON 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) are handled differently JSON has a notation for arrays, which are 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 still conform to the rules described for the Narrative 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. 1.12.5.2.1 JSON Representation for repeating elements An element that has a maximum cardinality of x..* 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 <> < value="http://snomed.info/sct"/> < value="104934005"/> <//> <> < value="http://loinc.org"/> < value="2947-0"/> <//> 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 JSON representation of primitive elements FHIR elements with primitive values 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 and/or extensions 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). < value="abc"/> <!-- code --> < value="1972-11-30"/> <!-- dateTime --> < value="false" /> <!-- boolean --> < 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: < id="314159" value="1970-03-30" > <extension url="http://example.org/fhir/extensions#text"> <valueString value="Easter 1970"/> </extension> </> is represented in JSON as: "dob": "1972-11-30", "_dob": { "id": "314159", "extension": [{ "url" : "http://example.org/fhir/extensions#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: < value="au"/> < value="nz"> <extension url="http://hl7.org/fhir/Profile/tools-extensions#display"> <valueString value="New Zealand a.k.a Kiwiland"/> </extension> </> 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" }] } ] } 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 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" /> <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', the 'id' is added represented in _family as described above 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 1.12.5.2.4 JSON representation of Resources 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. 1.12.5.2.5 JSON Bundle Representation 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. For convenience, a bundle has a "resourceType" property with the value of "Bundle" ("resourceType" is used for consistency with resources, even though a bundle is not a resource, but a container of resources). Here 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 are not pluralized for consistency of overall approach (as described above). The mime type for a JSON bundle is also application/json+fhir. 1.12.5.2.5.1 Bundling versions - deletion 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 SHALL be provided, and a link may 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 it would be specified in HTTP, like this: { "resourceType" : "Binary", "contentType" : "[mime type]", "content" : "[base64 of data]" } 1.12.5.2.5.3 Signatures If a bundle has a signature, the signature has a JSON property "signature", whose property value is an XML string that is a valid XML signature element. { "resourceType" : "Bundle", ... metadata and entries as described above.... "signature" : "<signature xmlns=\"http://www.w3.org/2000/09/xmldsig\">...</signature>" } © HL7.org 2011+. FHIR DSTU (v0.0.82.2943) generated on Tue, Sep 30, 2014 18:10+1000. Links: What's a DSTU? | Version History | | Propose a change var disqus_shortname = 'fhirdstu';(function() {var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); })(); Please enable JavaScript to view the comments powered by Disqus. comments powered by Disqus var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-676355-1']); _gaq.push(['_setDomainName', '.hl7.org']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })();