Working with JSON

By default JSON data received from backend systems is handled as text content and passed to the client unchanged. However, FIT has two tools for working with JSON on the server:

  • the JSON converter builds a DOM from the JSON structure
  • the JSON dumper serializes the JSON DOM representation back to JSON

Using the Converter

The JSON converter can be activated via URL Marks or the configuration.

When requesting FIT, add the URL Mark m=json to the FIT URL. The main content will then be treated as JSON.

http://fit.example.com/;m=json/json-api/foo

URL Marks can either be defined with Rewrite Options on the server or with the JavaScript URL API on the client.

Alternatively, you may activate the JSON converter for a range of requests in the sources configuration. The following example shows how to configure the converter for all requests to http://backend.example.com/json-api and sub paths.

conf/sources.xml:

<sources>
  <source host="backend.example.com" path="/json-api">
    <parser value="json" />
  </source>
</sources>

If the json-parser option in config.xml is enabled, each resource identified as being JSON (either by MIME type or via content sniffing) will be automatically converted into the corresponding DOM:

<config>
  <content-handling>
    <json-parser />
  </content-handling>
</config>

If you access a JSON resource via the XPath function fit-document it will be transparently converted to a DOM with the document element json-document (see below). For example in the flow.xml:

<flow><request content="api" url="http://backend.example.com/json-api" />
  <!-- { "error": "An error occured. } -->
  <dump if="fit-document('fit://request/content/api')/json-document/error" /></flow>

In XSLT this works with the document function, too:

<!-- { "version": 2, "settings": { "api-key": "…", "language": "de", … }, … } -->
<xsl:variable name="settings" select="document('fit://site/conf/my-settings.json')/json-document/settings"/>
<xsl:variable name="language" select="$settings/language/@value"/>

JSON DOM Structure

Example of JSON with all supported data types:

{
  "Nick": "superuser",
  "Person": {
    "Full name": "John Doe",
    "Age": 33,
    "Religion": null,
    "Married": true,
    "Children": false,
    "Hobby": "Football",
    "Balance": -1234.56,
    "Cars": ["BMW","AUDI"]
  }
}

The JSON converter translates the above JSON data into this XML structure:

<?xml version="1.0" encoding="UTF-8"?>
<json-document type="object">
  <Nick type="string" value="superuser"/>
  <Person type="object">
    <json-element type="string" name="Full name" value="John Doe"/>
    <Age type="number" value="33"/>
    <Religion type="null"/>
    <Married type="boolean" value="true"/>
    <Children type="boolean" value="false"/>
    <Hobby type="string" value="Football"/>
    <Balance type="number" value="-1234.56"/>
    <Cars type="array">
      <json-element type="string" value="BMW"/>
      <json-element type="string" value="AUDI"/>
    </Cars>
  </Person>
</json-document>

The json-document may also be of type array to generate a […] structure.

If the type attribute of json-document is omitted, object is used by default.

Restrictions

If a JSON member is not a valid XML element name, the converter creates a <json-element name="…" … />. The original name is kept in the name attribute. For example, see the Full name JSON member and its XML representation above:

<json-element type="string" name="Full name" value="John Doe"/>

JSON Dumper

The JSON dumper is triggered automatically if the root element of the main content is json-document. Instead of serializing the DOM directly, the data will be translated back into JSON. The JSON string is sent to the client with the content type application/json.

This behavior can also be used to create JSON rather than manipulating existing JSON data. For example, you have a Web site with product data written in plain HTML. In your FIT site you can use XSLT to translate the HTML into the JSON DOM structure as defined above. FIT will recognize the root element and send the product information as JSON. This could be used to create a data feed needed for a mobile catalog app.

FIDJ Filter ‘json2xml’

This filter enables you to load your JSON source as an XML structure (see Converter) for any FIDJ resource even if it is not part of the main request. It is a handy alternative to setting the parser for the specific files in the sources.xml. The filter is activated by appending ‘;filter=json2xml’ to the URL.

Example:

<xsl:variable name="jsondata" select="document('fit://site/public/json/data.json;filter=json2xml)"/>

FIDJ Filter ‘xml2json’

This filter converts a document in JSON XML notation (either an XML string or a DOM object) into JSON text.

Example:

<request url="http://example.com">
  <body src="fit://site/conf/json.xml;filter=xml2json" />
</request>

As the result of the filter is a text, it cannot be used in XPath or XSLT functions such as fit-document.