This page is part of the FHIR Specification (v5.0.0: R5 - STU). This is the current published version. For a full list of available versions, see the Directory of published versions

• Definitions
• Formats
• UML
• XML
• JSON
• ND-JSON
• RDF

2.1.6.2 Resource Formats

FHIR Infrastructure Work Group

Maturity Level: Normative

Standards Status: Normative

2.1.6.2.0.1 Serialization Format Representations

This specification defines the following ways to represent resources when they are exchanged:

• JSON
• XML
• RDF (Turtle)

Additional Bulk Data Formats are also undergoing exploration. Other representations are allowed, but are not described by this specification.

Systems SHALL declare which format(s) they support in their Capability Statement. If a server receives a request for its Capability Statement in a format it does not otherwise support, it SHALL return a 406 Not Acceptable. Note: 406 is the appropriate response when the Accept header requests a format that the server does not support, and 415 Unsupported Media Type when the client posts a format that is not supported to the server.

Clients and servers can choose what syntax(s) to implement. In the interests of interoperability, servers SHOULD support both the XML and JSON formats, which have the same functionality, for different technical stacks. The RDF format has quite different benefits - primarily around data analysis rather than exchange.

2.1.6.2.0.2 Comparison between JSON and XML

The JSON format is similar to the XML 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 objects and arrays are never empty, and properties never have null values (except for a special case documented below). Omit a property if it is empty
• JSON and XML whitespace (whitespace introduced for rendering purposes - aka "pretty printing") 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 following HL7's signature guidance and using the defined canonicalization mechanisms will ignore formatting whitespace

There are differences between XML and JSON:

• 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 (e.g. id, value) are handled differently (see below)
• JSON has the array notation, which 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 SHALL still conform to the rules described for the Narrative
• For strings, leading and trailing whitespace is expected to be preserved in JSON. This difference is driven by XML Schema behavior
• Leading zeros are allowed for numbers in JSON but not XML
• Comments are possible in XML but not possible in JSON (the format is not JSON with comments)

Implementers should be aware of the difference in this serialization behavior when converting between the syntaxes, including its ramifications on digital signature canonicalizations. The XML format for the resources follows the JSON 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.

2.1.6.2.0.2.1 String handling

String handling is slightly different between XML and JSON