This page was generated
January  28,  2016
4:05  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: JSON

This is the JSON module used for customized tranformation from XML to and from JSON.

To use the JSON module as part of your own XQuery module, include the following line in your XQuery prolog:

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

The JSON module employs a concept of 'strategies'. Strategies are different methods of transforming XML to JSON or JSON to XML. Different strategies tackle different use cases.

The basic strategy is used by the REST API and handles the use case of transforming arbitrary JSON into a fixed XML structure which is designed to be efficiently stored and indexed in MarkLogic. The basic strategy is semantically roundtrippable from JSON to XML back to JSON. The basic strategy is used when no configuration object is specified.

The full strategy targets the opposite use case as the default (basic) strategy. The full strategy takes arbitrary XML and produces a fixed JSON structure which preserves most of the semantics of the XML document.

The custom strategy allows customization of the JSON and XML transformation and produces more reasonable looking XML or JSON at the expense of supporting a smaller subset of XML document structures.

Function Summary
json:check-config This function checks a json configuration object and returns a report.
json:config This function creates a configuration object for a specified strategy.
json:transform-from-json This function transforms a JSON document to XML using the default ("basic") strategy.
json:transform-to-json This function transforms an XML document to JSON using the default ("basic") strategy if none is supplied.
json:transform-to-json-object This function transforms an XML document to JSON and returns an object.
json:transform-to-json-xml This function transforms an XML document to JSON and returns an xml element.
Function Detail
json:check-config(
[$config as map:map]
)  as   element(json:report)*
Summary:

This function checks a json configuration object and returns a report.

Parameters:
$config (optional): The configuration object representing the strategy.

Usage Notes:

The supplied configuration object (a map:map) is checked for validity and any errors found returned.


json:config(
$strategy as xs:string
)  as   map:map
Summary:

This function creates a configuration object for a specified strategy.

Parameters:
$strategy : The name of the strategy. One of basic (simple default JSON conversion, starting from JSON), full (starting from XML), or custom.

Usage Notes:

Use this function to when you want to use a custom strategy. Supported strategies are basic, full, custom. The basic strategy is used if you supply no parameters and has no user customizable properties. The following properties are user customizable to configure the behavior of the transformation.

full strategy properties

Property

Description

Default value

json-attributes

The member named used to contain attributes

_attributes

json-children

The member named used to contain the children array

_children

whitespace

How to treat whitespace in XML text values when converting to JSON. If ignore then skip the value otherwise include it.

empty string

custom strategy properties

Property

Description

Direction

Type

Default value

array-element-names

A list of XML element names which will be treated as an Array in JSON. These can be xs:QName or xs:string. If an xs:string is used then the default namespace is used to construct the QName.

XML to JSON

(xs:QName | xs:string)*

()

ignore-element-names

A list of XML element names which will be ignored when transformed to JSON. These can be xs:QName or xs:string. If an xs:string is used then the default namespace is used to construct the QName.

XML to JSON

(xs:QName | xs:string)*

()

ignore-attribute-names

A list of XML attribute names which will be ignored when transformed to JSON. These can be xs:QName or xs:string. If an xs:string is used then the default namespace is used to construct the QName.

XML to JSON

(xs:QName | xs:string)*

()

text-value

The JSON member name to use for text when an element contains both attributes and text.

BOTH

xs:string

"_value"

attribute-names

A list of JSON names which are converted to XML attribute.

JSON to XML

xs:string*

()

camel-case

A boolean value indicating if camel case transformation is applied to all element and attribute names when translating to and from JSON.

BOTH

xs:boolean

fn:false()

element-namespace

The default namespace for elements

JSON to XML

xs:string

()

element-namespace-prefix

The default prefix for elements

JSON to XML

xs:string

()

attribute-namespace

The default namespace for attributes

JSON to XML

xs:string

()

atribute-namespace-prefix

The default prefix for attributes

JSON to XML

xs:string

()

attribute-prefix

If specified then when converting to JSON attributes are prefixed with this string. When converting to XML all names starting with this prefix are converted to attributes with the prefix removed.

BOTH

xs:string

()

full-element-names

A list of XML element names which will be treated as an full expansion in JSON similar to the full strategy. These can be xs:QName or xs:string. If an xs:string is used then the default namespace is used to construct the QName.

BOTH

(xs:QName | xs:string)*

()

json-attributes

The member named used to contain attributes when using the full-element-names expansion.

xs:string

"_attributes"

json-children

The member named used to contain the children array when using the full-element-names expansion

xs:string

"_children"

whitespace

How to treat whitespace in XML text values when converting to JSON. If ignore then skip the value otherwise include it.

xs:string

""


Example:
xquery version "1.0-ml";
import module namespace json="http://marklogic.com/xdmp/json"
 at "/MarkLogic/json/json.xqy";

let $c := json:config("full"), 
return json:transform-to-json( fn:doc("sample.xml") , $c )
Example:
xquery version "1.0-ml";
import module namespace search = "http://marklogic.com/appservices/search"
     at "/MarkLogic/appservices/search/search.xqy";
import module namespace json="http://marklogic.com/xdmp/json"
     at "/MarkLogic/json/json.xqy";

let $custom :=
 let $config := json:config("custom")
 return 
   (map:put($config, "array-element-names",
             ("text","point","value","operator-state",
              "annotation","uri","qtext")),
    map:put($config, "element-namespace", 
             "http://marklogic.com/appservices/search"),
    map:put($config, "element-namespace-prefix", "search"),
    map:put($config, "attribute-names",("warning","name")),
    map:put($config, "full-element-names",
             ("query","and-query","near-query","or-query")),
    map:put($config, "json-children","queries"), 
    $config) 
let $struct := search:parse("hello world", (), "search:query")    
return (   
json:transform-to-json($struct, $custom),
$struct )
(: returns the json and corresponding XML for the structured query :)
=>
{"query":{"queries":
  [{"and-query":{"queries":
     [{"term-query":{"text":["hello"]}},
     {"term-query":{"text":["world"]}}]}
  }]
}}
<search:query xmlns:search="http://marklogic.com/appservices/search">
  <search:and-query>
    <search:term-query>
      <search:text>hello</search:text>
    </search:term-query>
    <search:term-query>
      <search:text>world</search:text>
    </search:term-query>
  </search:and-query>
</search:query>


json:transform-from-json(
$json as item(),
[$config as map:map]
)  as   item()*
Summary:

This function transforms a JSON document to XML using the default ("basic") strategy.

Parameters:
$json : The JSON document (typically a string) to transform.
$config (optional): The configuration object

Usage Notes:

The supplied JSON document (as a string, element, object or array) is transformed to XML using the default (basic) strategy and returned as an element.

Example:
xquery version "1.0-ml";
import module namespace json="http://marklogic.com/xdmp/json"
 at "/MarkLogic/json/json.xqy";
 
 declare variable $j :=  '{
    "first Key":"first value",
    "secondKey":["first item","second item",null,"third item",false],
    "thirdKey":3,
    "fourthKey":{"subKey":"sub value", "boolKey" : true, "empty" : null }
    ,"fifthKey": null,
    "sixthKey" : []
    }'  ;
 json:transform-from-json( $j)
 
     ==>

<json type="object" xmlns="http://marklogic.com/xdmp/json/basic">
  <first_20_Key type="string">first value</first_20_Key>
  <secondKey type="array">
    <item type="string">first item</item>
    <item type="string">second item</item>
    <item type="null"/>
    <item type="string">third item</item>
    <item type="boolean">false</item>
  </secondKey>
  <thirdKey type="number">3</thirdKey>
  <fourthKey type="object">
    <subKey type="string">sub value</subKey>
    <boolKey type="boolean">true</boolKey>
    <empty type="null"/>
  </fourthKey>
  <fifthKey type="null"/>
  <sixthKey type="array"/>
</json>
Example:
xquery version "1.0-ml";
import module namespace json="http://marklogic.com/xdmp/json"
 at "/MarkLogic/json/json.xqy";
 
 declare variable $j :=  '{
   "object" : {
    "firstKey":"first value",
    "secondKey":["first item","second item","","third item",false],
    "thirdKey":3,
    "fourthKey":{"subKey":"sub value", "boolKey" : true, "empty" : null }
    ,"fifthKey": null,
    "sixthKey" : []
     }}'  ;

 let $config := json:config("custom") ,
          $cx := map:put( $config, "attribute-names" , ("subKey" , "boolKey" , "empty" ) )
 return 

json:transform-from-json( $j, $config )

    ==>
<object>
  <firstKey>first value</firstKey>
  <secondKey>first item</secondKey>
  <secondKey>second item</secondKey>
  <secondKey/>
  <secondKey>third item</secondKey>
  <secondKey>false</secondKey>
  <thirdKey>3</thirdKey>
  <fourthKey subKey="sub value" boolKey="true" empty=""/>
  <fifthKey/>
</object>

json:transform-to-json(
$node as node(),
[$config as map:map]
)  as   xs:string
Summary:

This function transforms an XML document to JSON using the default ("basic") strategy if none is supplied.

Parameters:
$node : The node to transform. The node must be a node that was transformed from JSON (for example, as the result of a json:transform-from-json call with the basic strategy or from JSON that was loaded using the REST API).
$config (optional): The configuration object representing the strategy.

Usage Notes:

The supplied document (element or document node) is transformed to JSON using the default ("basic") strategy and returned as a string.

When the default "basic" strategy is used, the XML node must be in the http://marklogic.com/xdmp/json/basic namespace.


Example:
  xquery version "1.0-ml";
    import module namespace json="http://marklogic.com/xdmp/json"
     at "/MarkLogic/json/json.xqy";
     
 
    json:transform-to-json( fn:doc("sample.xml") )
  
Example:
xquery version "1.0-ml";
import module namespace json="http://marklogic.com/xdmp/json"
 at "/MarkLogic/json/json.xqy";
 
let $config := json:config("full") ,
    $cx := map:put( $config, "whitespace"     , "ignore" )
return 
  json:transform-to-json( fn:doc("sample.xml") , $config )

json:transform-to-json-object(
$node as node(),
[$config as map:map]
)  as   item()
Summary:

This function transforms an XML document to JSON and returns an object.

Parameters:
$node : The node to transform. The node must be a node that was transformed from JSON (for example, as the result of a json:transform-from-json call with the basic strategy or from JSON that was loaded using the REST API).
$config (optional): The configuration object representing the strategy.

Usage Notes:

The supplied document (element or document node) is transformed to JSON using the default (basic) strategy and returned as an object. The object will be either a json:object or json:array.

When the default "basic" strategy is used, the XML node must be in the http://marklogic.com/xdmp/json/basic namespace.


Example:
xquery version '1.0-ml';
import module namespace json = "http://marklogic.com/xdmp/json"
    at "/MarkLogic/json/json.xqy";

json:transform-to-json-object(
  <root>
    <key>value</key>
  </root>, 
  json:config("full"))

=> the following JSON object:

json:object(<json:object xmlns:xs="http://www.w3.org/2001/XMLSchema" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:json="http://marklogic.com/xdmp/json">
  <entry key="root">
    <json:value>
      <json:object>
        <json:entry key="_children">
          <json:value>
            <json:array>
              <json:value>
                <json:object>
                  <json:entry key="key">
                    <json:value>
                      <json:object>
                        <json:entry key="_children">
                          <json:value>
                            <json:array>
                              <json:value 
                                xsi:type="xs:string">value</json:value>
                             </json:array>
                          </json:value>
                        </json:entry>
                      </json:object>
                    </json:value>
                  </json:entry>
                </json:object>
              </json:value>
            </json:array>
          </json:value>
        </json:entry>
      </json:object>
    </json:value>
  </entry>
</json:object>)
   

json:transform-to-json-xml(
$node as node(),
[$config as map:map]
)  as   element()
Summary:

This function transforms an XML document to JSON and returns an xml element.

Parameters:
$node : The node to transform. The node must be a node that was transformed from JSON (for example, as the result of a json:transform-from-json call with the basic strategy or from JSON that was loaded using the REST API).
$config (optional): The configuration object representing the strategy.

Usage Notes:

The supplied document (element or document node) is transformed to JSON using the default (basic) strategy and returned as an element. The element will be either a json:object or json:array element.

When the default "basic" strategy is used, the XML node must be in the http://marklogic.com/xdmp/json/basic namespace.


Example:
xquery version '1.0-ml';
import module namespace json = "http://marklogic.com/xdmp/json"
    at "/MarkLogic/json/json.xqy";

json:transform-to-json-xml(
  <root>
    <key>value</key>
  </root>, 
  json:config("full"))

=> 
<json:object xmlns:json="http://marklogic.com/xdmp/json" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <json:entry key="root">
    <json:value>
      <json:object>
	<json:entry key="_children">
	  <json:value>
	    <json:array>
	      <json:value>
		<json:object>
		  <json:entry key="key">
		    <json:value>
		      <json:object>
			<json:entry key="_children">
			  <json:value>
			    <json:array>
			     <json:value xsi:type="xs:string">value
			     </json:value>
			    </json:array>
			  </json:value>
			</json:entry>
		      </json:object>
		    </json:value>
		  </json:entry>
		</json:object>
	      </json:value>
	    </json:array>
	  </json:value>
	</json:entry>
      </json:object>
    </json:value>
  </json:entry>
</json:object>