Introduction
JSON representations for exchange standards are widely used in today’s architectures. In RESTful web services, JSON is often the preferred format for the service response, due to its compactness and ease of use in mobile applications. Other standards used in healthcare, such as HL7-FHIR, support JSON as well as XML, together with other formats such as RDF.
JSON and XML are not 1:1 interoperable, as they are based on different principles. For example, JSON does not have a native mechanism for namespaces (as it wants to remain "lightweight"). Also JSON does not have an equivalent for XML "text content". In JSON, "text content" is treated in the same way as "attribute pairs" of XML.
In order to make XML and JSON representations of the same standard interconvertible without any information loss, a set of principles, usually named "conversion conventions" have been developed and are publicly available. See http://wiki.open311.org/JSON_and_XML_Conversion/
This document explains the principles of the JSON representation, and the conventions used. These are based on the "Flickr conventions" for JSON (https://www.flickr.com/services/api/response.json.html).
Main principles
For the ODM JSON implementation, the following main principles apply:
- Like XML, JSON is case-sensitive.
- JSON is based on sets of name-value pairs. Name and Value are embedded in double quotes and separated by a colon. Example: "OID": "MyStudy"
- XML elements are represented as JSON objects.
- A JSON object is an unordered set of name-value pairs. An object begins with a left brace ("{") and ends with right brace ("}"), preceded by the object name (in double quotes). Each name is followed by colon and the name/value pairs are separated by a comma.
- Arrays of objects or name-value pairs are represented by and embedded in square brackets. For example: ["a","b","c"] represents a list of the objects with name "a", "b", and "c".
Protocol element in JSON example:
"Protocol": {
"StudyEventRef": [{
"Mandatory": "Yes",
"OrderNumber": 1,
"StudyEventOID": "BASELINE"
}]
}
This example shows the JSON serialization of the XML element Protocol with an array of child StudyEventRef elements. The StudyEventRef element is a JSON object (shown in curly brackets) with values for the Mandatory, OrderNumber, and StudyEventOID attributes. The StudyEventRef element is defined as an array (with brackets) so as many as needed can be included.
Very complex and/or large JSON or XML files my have a single line. Tools for reviewing or hand-authoring of JSON or XML may use line breaks and indentation so that the text is easier to read. Line breaks within Value strings have meaning and must be represented with \n. Indentation or line breaks can be used outside of quoted value strings but have no meaning.
- XML text content is treated as a name-value pair with the name being "_content".
Example: ODM-10 - Getting issue details... STATUS
"ReasonForChange": {"_content": "Investigator typing error"}
and combined with the parent element "AuditRecord":
"AuditRecord": {
"UserRef": {"UserOID": "USR.001"},
"LocationRef": {"LocationOID": "LOC.007"},
"DateTimeStamp": {"_content": "2022-07-03"},
"ReasonForChange": {"_content": "Investigator typing error"}
}
- Namespaces are ignored.
For ODM, this essentially means that the attribute "xml:lang" translates into "lang".
Example representing the ODM-XML Description element with child element TranslatedText, having the xml:lang attribute with the value "en" and the text content "Unique identifier for a study":
"Description": {
"TranslatedText": [{
"lang": "en",
"_content": "Unique identifier for a study."
}]
}
- As usual in JSON, the root element is not explicitly named.
Example representing the ODM element with attributes CreationDateTime, Description, FileOID, FileType, Granularity, ODMVersion, and Originator:
{
"CreationDateTime": "2011-10-24T10:05:00",
"Description": "JSON test",
"FileOID": "JSON_Test_2020",
"FileType": "Snapshot",
"Granularity": "Metadata",
"ODMVersion": "2.0",
"Originator": "MySystem",
...
...
}