LIXI2 Conventions for JSON Schemas

LIXI has published JSON schema specifications corresponding to each XSD schemas since 31st October 2017.

The JSON conventions (both structural conventions and data tye conventions) that define the way in which the JSON schemas are produced from the corresponding XSD are described on this page.

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

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

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

<Attachment></Attachment>
"Attachment": {}

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

<InlineAttachment>U2FtcGx1IEJhc2U2NA==<InlineAttachment>
"InlineAttachment": {
                 "$" : "U2FtcGxlIEJhc2U2NA==",
                    }

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

<IncomeYearToDate CompanyProfitBeforeTax="24999.99"/>
"IncomeYearToDate": {
                    "@CompanyProfitBeforeTax": 24999.99
                    }

Non-repeatable elements will be represented as a single object (a key-value pair)

<Package>
  <Publisher CompanyName="LIXI" LIXICode="ABCD1234"/>
</Package>
"Package": {
    "Publisher": {
                  "@CompanyName": "LIXI",
                  "@LIXICode": "ABCD1234"
                 }
           }

Repeatable elements will be represented as an array (a key-value pair where the value is an array i.e. surrounded with square brackets). When a repeatable element is not repeated, it will none the less be represented as an array containing only one element. Note that the order of repeated elements is not meaningful in XML or JSON.

<CompanyApplicant>
  <Shareholder PercentOwned="60" x_Shareholder="x123456"/>
  <Shareholder PercentOwned="40" x_Shareholder="x789012"/>
</CompanyApplicant>
"CompanyApplicant": {
    "Shareholder": [
         {
                 "@PercentOwned": 60,
                 "@x_Shareholder": "x123456"
         },
         {
                 "@PercentOwned": 40,
                 "@x_Shareholder": "x789012"
         }
     ]
}

Data Type Conventions

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

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

PoolType="Above Ground"
"@PoolType": "Above Ground"

Patterns

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

e.g. abnPattern

ABN="12345678901"
"@ABN": "12345678901"

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

<InlineAttachment>U2FtcGx1IEJhc2U2NA==</InlineAttachment>

"InlineAttachment": {
                          "$": "U2FtcGx1IEJhc2U2NA=="
                    }

currencyType

CompanyProfitBeforeTax="24999.99"
"@CompanyProfitBeforeTax": 24999.99

dateTimeType

DateTime="1980-03-23T08:46:40"
"DateTime": "1980-03-23T08:46:40"

dateType

GSTRegisteredDate="1980-03-23"
"@GSTRegisteredDate": "1980-03-23"

gYearType

CustomerSince="1980"
"@CustomerSince": "1980"

integerType

NumberOfDirectors="12"
"@NumberOfDirectors": 12

percentType

PercentOwned="100"
"@PercentOwned": 100

referenceType

x_Shareholder="x123456"
"@x_Shareholder": "x123456"

stringType

ContactName="JohnMatthews"
"@ContactName": "JohnMatthews"

uniqueIDType

UniqueID="x123456"
"@UniqueID": "x123456"

 

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.

First Published: 1st August 2017 | Last Updated 4th February 2020