JSON Module

JSON Module

Import statement

import module namespace json="http://marklogic.com/json" at "lib/json.xqy";

API Functions

json:parse

json:parse(  
    $json as xs:string,  
    [$enableExtensions as xs:boolean]  
) as element(json:json)

Converts a JSON string into an XML document that is highly indexable by MarkLogic. The XML that is generated is intended to be treated like a black box. In other words, it isn't something that you're encouraged to use directly at this time. However, for those that are brave it is fairly reasonable to understand.

• $json - A JSON string. This string can contain a number, a string, a boolean value, an array or an object.
• $enableExtensions (optional) - Turns and off the parsing extensions. If not supplied, defaults to true.

Examples:

json:parse('3.14159')
json:parse('"Hello World')
json:parse('true')
json:parse('[1, 2, 3, 4]')
json:parse('{"foo": "bar"}')

---

json:serialize

json:serialize(
    $element as node()
) as xs:string

Converts an specially formatted XML document into a JSON string. It is HIGHLY important to understand that this function does not accept arbitrary XML. It is designed to accept the XML that is generated by the functions in this module.

• $element - A XML element that has been generated by the functions in this module

Examples:

json:serialize(json:array((1, 2, 3, 4))) -> "[1, 2, 3, 4]" 

---

json:document

json:document(
    $value as item()
) as element(json:json)

Constructs a JSON document for storage in MarkLogic.

• $value - A JSON item (see below for a description of what a JSON item can be).

A word on JSON items

The various functions in this module that accept JSON items (json:document, json:object and json:array) examine the type of the passed in item and convert it to the appropriate JSON type.

Here's how the casting works, most are obvious: * XQuery string -> JSON string * XQuery boolean -> JSON boolean * XQuery integer or decimal -> JSON number * Every other XQuery type -> JSON string

A JSON item may also be the result return value of json:array or json:object.

Examples:

json:document(3.14159)
json:document("Hello World")
json:document(true())
json:document(json:array((1, 2, 3, 4)))
json:document(json:object(("foo", "bar")))

---

json:object

json:object(
    [$keyValues as item()*]
) as element(json:item)

Constructs a JSON object in an XML format for use in json:document, json:array or json:serialize. The return value is not a string but a JSON item. For more information on JSON items, see the note in json:document.

There are also a convenience function json:o.

• $keyValues - A sequence of alternating object keys and values. The keys must be strings and the values can be JSON items. Keys must be unique.

Examples:

json:object(("foo", "bar")) -> {"foo": "bar"}
json:object(("foo", json:array((1, 2, 3, 4)))) - > {"foo": [1, 2, 3, 4]}
json:object(("foo", true(), "bar", false())) -> {"foo": true, "bar": false}

---

json:array

json:array(
    [$items as item()*]
) as element(json:item)

Constructs a JSON array in an XML format for use in json:document, json:object or json:serialize. The return value is not a string but a JSON item. For more information on JSON items, see the note in json:document.

There are also a convenience function json:a.

• $items - A sequence of JSON items to include in the array.

Examples: json:array((1, 2, 3, 4)) -> [1, 2, 3, 4] json:array((true(), false(), "foo")) -> [true, false, "foo"] json:array((json:object(("foo", "bar")), json:object(("baz", "yaz")))) -> [{"foo": "bar"}, {"baz": "yaz"}]

---

json:date

json:date(
    $value as xs:anySimpleType
) as element(json:item)

Because JSON doesn't have a date datatype, we have to do some special things. This function will accept either an xs:dateTime, xs:date or a date string. In the case of a date string, an attempt will be made to parse the string into an xs:dateTime. If the string cannot be parsed an error is thrown.

---

json:xml

json:xml(
    $value as element()
) as element(json:item)

Because JSON doesn't have an xml datatype, we have to do some special things to get it to work. When serialized out as JSON the xml will appear as a string but internally it is represented as an xml tree.

---

json:null

json:null(
) as element(json:item)

Because XQuery doesn't have a strict null value, this function allows us to construct a JSON null. This can be useful if you need objects or arrays with null values.

Examples:

json:array((1, 2, json:null(), 4)) -> [1, 2, null, 4]
json:object(("foo", json:null())) -> {"foo": null}