ItineraryStep - Json

The JSON assembler is a system artifact in Link. Its purpose is to convert XML documents to JSON files prior to sending them to a recipient.

Configuration

The JSON assembler configuration looks like this. Note that some fields are only shown if certain other fields are chosen:

Xml schema

Use XML schema

Choose whether or not to use XML schemas. If false - the XML will be assembled to JSON using the attributes from the http://bizbrains.com/json namespace. If true - an XML schema must be chosen.

Xml schema

Choose the XML schema that should be used for assembling the JSON.

Fail on unknown elements

A value indicating whether the assembler will fail if it encounters an XML element that can't be found in the XML schema. If this is set to false the unknown element(s) will be ignored and not written to the JSON output.

Settings

Include XML root rode

By default the XML root node is omitted. Set this checkbox to include it in the generated JSON.

Include XML namespaces

By default XML namespace declarations are omitted. Set this checkbox to include them in the generated JSON.

Use indentation

By default the JSON structure will be generated as a one line string with no spaces or line breaks. Set this checkbox to generate more human readable JSON with line breaks and indentations.

Include attributes

A value indicating whether or not XML attributes should be included in the assembled JSON. Default value is true. (namespace declaration will be excluded, unless 'Include XML namespaces' is true).

Attribute prefix

The prefix for properties that are representing attributes in the XML. This is only relevant, if the "IncludeAttributes" is set to true. Default value is '@'.

Write empty elements

Write null values for empty (self-enclosing) elements. Default is true.

Advanced

Buffer size

A value indicating the size in bytes of the internal buffer in the JSON writer. Default value is 16384 bytes.

Json encoder

Gets or sets the JSON encoder that will be used, when assembling the JSON. The default encoder will use "unicode escape sequences" for special characters. Eg. quotation marks will be encoded as \u0022 rather than \". The UnsafeRelaxedJsonEscaping encoder instance does not escape HTML-sensitive characters such as <, >, &. As a result, it must be used cautiously; for example, it can be used if the output data is within a response whose content-type is known with a charset set to UTF-8.

Data annotations

By default all values from the input XML will be treated as string values when converted to JSON.
However it is possible to use a type attribute on a XML tag to tell the assembler how to represent the value in JSON.

The following types are supported:

• json:type=”integer” - 32bit integer. Maps to the JSON number type.

• json:type=”long” - 64bit integer. Maps to the JSON number type.

• json:type=”float” - Floating point number (decimal). Maps to the JSON number type.

• json:type=”boolean” - Boolean value (true/false). Maps to the JSON boolean type.

The reason for having 3 different types that map to the same JSON type is that the assembler also supports using XML schemas instead of the type attribute, and in XML those three data types are separate. This saves us from having multiple different versions of the data type logic that need to be maintained separately.

Important: Remember to declare the namespace used for the type and array attributes. The namespace must be “http://bizbrains.com/json“ The namespace prefix used in the example is “json” but can be anything.

Arrays

• 2024-01-19: Obsolete in future relases:

  • XML tags with the same name will by default be parsed as elements of an array. To be sure also a single XML tag wil be parsed as an array with one element, use the type=”array” attribute on the XML tag.

• For releases after 2024-01-19

  • XML tags with the same name will by default be parsed as elements of an array. To be sure also a single XML tag wil be parsed as an array with one element, use the array=”true” attribute on the XML tag.

Example

XML:

<BrandCatalog xmlns="http://company.com" xmlns:json="http://bizbrains.com/json">
	<Brands>
		<BrandId json:type="integer">1</BrandId>
		<Name>Mercedes-Benz</Name>
		<MultiBrand json:type="boolean">false</MultiBrand>
		<Value json:type="float">123.4</Value>
		<AltNames json:array="true">
			<Id json:type="integer">1</Id>
			<name>MB</name>
		</AltNames>
	</Brands>
	<Brands>
		<BrandId json:type="integer">2</BrandId>
		<Name>Volkswagen</Name>
		<MultiBrand json:type="boolean">true</MultiBrand>
		<Value json:type="float">234.5</Value>
		<AltNames>
			<Id json:type="integer">1</Id>
			<name>VW</name>
		</AltNames>
		<AltNames>
			<Id json:type="integer">2</Id>
			<name>VAG</name>
		</AltNames>
	</Brands>
</BrandCatalog>

JSON:

{
  "BrandCatalog": {
    "Brands": [
      {
        "BrandId": 1,
        "Name": "Mercedes-Benz",
        "MultiBrand": false,
        "Value": 123.4,
        "AltNames": [
          {
            "Id": 1,
            "name": "MB"
          }
        ]
      },
      {
        "BrandId": 2,
        "Name": "Volkswagen",
        "MultiBrand": true,
        "Value": 234.5,
        "AltNames": [
          {
            "Id": 1,
            "name": "VW"
          },
          {
            "Id": 2,
            "name": "VAG"
          }
        ]
      }
    ]
  }
}