JSON Functions

This module contains functions to parse and serialize JSON data JSON (JavaScript Object Notation) is a popular data exchange format for applications written in JavaScript. As there are notable differences between JSON and XML, or XQuery data types, no mapping exists that guarantees a lossless, bidirectional conversion between JSON and XML. For this reason, we offer various mappings, all of which are suited to different use cases.

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/json namespace, which is statically bound to the json prefix.

Conversion Formats

Direct

The direct conversion format allows a lossless conversion from JSON to XML and back. The transformation is based on the following rules:

• The resulting document has a json root node.
• Object pairs are represented via elements. The name of a pair is encoded, as described for the Conversion Functions, and used as element name.
• Array entries are also represented via elements, with _ as element name.
• Object and array values are stored in text nodes.
• The types of values are represented via type attributes:
  • The existing types are string, number, boolean, null, object, and array.
  • As most values are strings, the string type is by default omitted.

Attributes

The attributes format is lossless, too. The transformation based on the following rules:

• The resulting document has a json root node.
• Object pairs are represented via pair elements. The name of a pair is stored in a name attribute.
• Array entries are represented via item elements.
• Object and array values are stored in text nodes.
• The types of values are represented via type attributes:
  • The existing types are string, number, boolean, null, object, and array.
  • As most values are strings, the string type is by default omitted.

Basic

The basic format is another lossless format. It converts a JSON document to an XML node and vice versa. The conversion rules are the same as for fn:json-to-xml.

JsonML

The jsonml format is designed to convert XML to JSON and back, using the JsonML dialect. JsonML allows the transformation of arbitrary XML documents, but namespaces, comments and processing instructions will be discarded in the transformation process. More details are found in the official JsonML documentation.

XQuery

The xquery format is lossless, too. It converts JSON data to an XQuery value (a map, array, string, number, boolean, or empty sequence) and vice versa. The conversion rules are the same as for fn:parse-json.

The resulting representation consumes less memory than XML-based formats, and values can be directly accessed without conversion. Thus, it is recommendable for very large inputs and for efficient ad-hoc processing.

Options

The following options are available (the Direction column indicates if an option applies to parsing, serialization, or both operations):

Functions

json:doc

json:doc(
  $source   as xs:string,
  $options  as map(*)?    := {}
) as item()?

json:parse

json:parse(
  $value    as xs:string?,
  $options  as map(*)?     := {}
) as item()?

json:serialize

json:serialize(
  $input    as item()?,
  $options  as map(*)?  := {}
) as xs:string

Examples

BaseX Format

let $database := "database"
for $name in file:list('.', false(), '*.json')
let $file := file:read-text($name)
let $json := json:parse($file)
return db:add($database, $json, $name)

json:parse('{}')

<json type="object"/>

(: serialize result as plain text :)
declare option output:method 'text';
json:serialize(<json type="object"/>)

{ }

json:parse('{
  "title": "Talk On Travel Pool",
  "link": "http://www.flickr.com/groups/talkontravel/pool/",
  "description": "Travel and vacation photos from around the world.",
  "modified": "2014-02-02T11:10:27Z",
  "generator": "http://www.flickr.com/"
}')

<json type="object">
  <title>Talk On Travel Pool</title>
  <link>http://www.flickr.com/groups/talkontravel/pool/</link>
  <description>Travel and vacation photos from around the world.</description>
  <modified>2014-02-02T11:10:27Z</modified>
  <generator>http://www.flickr.com/</generator>
</json>

let $options := { 'merge': true() }
return json:parse('{
  "first_name": "John",
  "last_name": "Smith",
  "age": 25,
  "address": {
    "street": "21 2nd Street",
    "city": "New York",
    "code": 10021
  },
  "phone": [
    {
      "type": "home",
      "number": "212 555-1234"
    },
    {
      "type": "mobile",
      "number": 1327724623
    }
  ]
}', $options)

<json numbers="age code" arrays="phone" objects="json address value">
  <first__name>John</first__name>
  <last__name>Smith</last__name>
  <age>25</age>
  <address>
    <street>21 2nd Street</street>
    <city>New York</city>
    `10021`
  </address>
  <phone>
    <_>
      <type>home</type>
      <number>212 555-1234</number>
    </_>
    <_>
      <type>mobile</type>
      <number type="number">1327724623</number>
    </_>
  </phone>
</json>

JsonML Format

for $doc in collection('json')
let $name := document-uri($doc)
let $json := json:serialize($doc, { 'format': 'jsonml' })
return file:write($name, $json)

json:serialize(doc('flickr.xml'), { 'format': 'jsonml' })

<flickr>
  <title>Talk On Travel Pool</title>
  <link>http://www.flickr.com/groups/talkontravel/pool/</link>
  <description>Travel and vacation photos from around the world.</description>
  <modified>2014-02-02T11:10:27Z</modified>
  <generator>http://www.flickr.com/</generator>
</flickr>

["flickr",
  ["title",
    "Talk On Travel Pool"],
  ["link",
    "http://www.flickr.com/groups/talkontravel/pool/"],
  ["description",
    "Travel and vacation photos from around the world."],
  ["modified",
    "2014-02-02T11:10:27Z"],
  ["generator",
    "http://www.flickr.com/"]]

json:serialize(doc('input.xml'), { 'format': 'jsonml' })

<address id='1'>
  <!-- comments will be discarded -->
  <last_name>Smith</last_name>
  <age>25</age>
  <address xmlns='will be dropped as well'>
    <street>21 2nd Street</street>
    <city>New York</city>
    `10021`
  </address>
  <phone type='home'>212 555-1234</phone>
</address>

["address", {"id":"1"},
  ["last_name",
    "Smith"],
  ["age",
    "25"],
  ["address",
    ["street",
      "21 2nd Street"],
    ["city",
      "New York"],
    ["code",
      "10021"]],
  ["phone", {"type":"home"},
    "212 555-1234"]]

XQuery Format

let $input := '{
  "Title": "Drinks",
  "Author": [ "Jim Daniels", "Jack Beam" ]
}'
let $data := json:parse($input, { 'format': 'xquery' })
return map:for-each($data, fn($key, $value) {
  $key || ': ' || string-join($value, ', ')
})

Author: Jim Daniels, Jack Beam
Title: Drinks

for $item in (
  true(),
  'ABC',
  array { 1 to 5 },
  { "Key": "Value" }
)
return json:serialize(
  $item,
  { 'format': 'xquery', 'indent': 'no' }
)

true
"ABC"
[1,2,3,4,5]
{"Key":"Value"}

Errors

Changelog

• Added: New number-parser, fallback, duplicates and null options (derived from fn:parse-json).

• Updated: indent: Default changed from yes to no.

• Added: json:doc

• Updated: json:parse can be called with empty sequence.

• Updated: map format renamed to xquery.
• Updated: error codes updated; errors now use the module namespace

• Updated: unescape changed to escape.

• Added: Conversion format basic.

• Added: liberal option.
• Updated: Serialization aligned with the json output method of the official specification.
• Removed: spec option.

• Updated: json:parse now returns a document node instead of an element, or an XQuery map if format is set to .map.
• Removed: json:parse-ml, json:serialize-ml.

• Updated: $options argument added to json:parse and json:serialize.
• Updated: json:parse-ml, json:serialize-ml are now deprecated.

• Added: New module added.