LIXI2 Conventions for JSON Schemas

LIXI has announced the upcoming support for JSON schema, in addition to our existing XML Schema, for each LIXI2 transaction release.

This page describes the JSON conventions that have been proposed in order for LIXI to support JSON schemas in future releases of our LIXI2 transaction standards.

The structural conventions describe the way in which the XML elements and attributes are structured in an equivalent JSON format.

The data type conventions describe the way in which the various data types in the XML message are treated in an equivalent JSON format.

Note that these conventions do not cover all XML specifications, but only those that have been applied in the LIXI2 Transaction Schema. These conventions are therefore sufficient for the LIXI2 Transaction Schemas but not for all possible Schemas.

Structural Conventions

  • XML elements are represented in JSON as an object named with the XML element tag name.

  • XML element text content is represented in JSON by a property with the key “$”.

  • XML attributes are represented in JSON as properties with names prefixed by the @ symbol.

  • Non-repeatable elements, or repeatable elements that are not repeated, will be represented as a single object (a key-value pair)

  • Repeatable elements that are repeated will be represented as an array (a key-value pair where the value is an array i.e. surrounded with square brackets). Note that the order of repeated elements is not meaningful in XML or JSON.

Data Type Conventions

In a LIXI XML message, all data types a represented the same way: as a string. Using JSON however, data can be represented in a way that implicitly tells us the data type. For example, a four-digit number can be surrounded with double quotes to indicate that it is a string (e.g. "@CustomerSince": "1980") or alternatively without double quotes to indicate that its data type is integer (e.g. "@NumberOfDirectors": 12).

The data type of each attribute is defined in the XML schema as a simple type. These simple types can be further categorised as either: an enumerated list (there are 197 of these); a pattern (12 of these), or a type (11 of these). For each of the 220 simple types we have defined the JSON data type will be used in a LIXI JSON message.

  • Enumerated Lists
  • All attributes that implement an enumerated list type are represented in the JSON message as a string type.

    e.g. poolTypeList

  • Patterns
  • All attributes that implement patterns are represented in the JSON message as a string type.

    e.g. abnPattern

  • Types
  • Each of the LIXI types map to an XML base type. We have mapped each of the LIXI types to a JSON type. These mappings are shown in the table below. An example of the implementation of each of the types in both XML and JSON is also shown below.

    LIXI Type XML Type JSON Type
    base64BinaryType xs:base64Binary string
    currencyType xs:decimal number
    dateTimeType xs:dateTime string
    dateType xs:date string
    decimalType xs:decimal number
    gYearType xs:gYear string
    integerType xs:integer integer
    percentType xs:decimal number
    referenceType xs:IDREF string
    stringType xs:string string
    uniqueIDType xs:ID string

     

    • base64BinaryType

    • currencyType

    • dateTimeType

    • dateType

    • gYearType

    • integerType
    • percentType
    • referenceType
    • stringType
    • uniqueIDType

     

Message Conversion Tool
LIXI has prepared a demonstration tool (available to registered users) that allows testing of bi-directional message conversions based on the proposed structural and data type conventions.
Sequences & Choices
Sequences
The XML Schema "sequence" Element has no logical equivalent in JSON - Objects and Properties within JSON are unordered. Therefore, there is no (simple) way to enforce the order of objects in the JSON schema as can be done in XML Schema.

The LIXI JSON -> XML converter is aware of the XML Schema and orders any sequenced elements into the correct order within the resulting XML message.

Choices
The XML Schema "choice" Element does have a logical equivalent in JSON, but only if the value of maxOccurs in the XML Schema is set to 1 (which is the default value). The "oneOf" keyword allows the inclusion of a maximum of one object from a selection.

The LIXI2 Transaction Schemas have only used choices where a maximum of one is allowed, and as a result we are able to use the oneOf keyword in the JSON Schema to mirror the XML Schema.

Why JSON?
JSON is a data format that was designed to encode object data derived from Javascript (JSON is an abbreviation for JavaScript Object Notation). It is now very widely used as a data exchange format on the internet, and in particular for providing data to APIs.

More details about the JSON data format can be found at json.org.

Updated: 1st August 2017