http://jsoniq.org/functions

View as XML or JSON.

This module provides the functions defined by the JSONiq specification, sections 1.7 (Functions) and 1.10 (Update Primitives). JSONiq extends the XQuery specification to also deal with JSON data natively. See http://jsoniq.org/ for details.

Function Summary

decode-from-roundtrip ($items as item()*) as item()* external

This function decodes non-JSON types previously encoded with jn:encode-for-roundtrip.

decode-from-roundtrip ($items as item()*, $options as object()) as item()* external

This function decodes non-JSON types previously encoded with jn:encode-for-roundtrip.

encode-for-roundtrip ($items as item()*) as item()* external

This function recursively encodes non-JSON types in such a way that they can be serialized as JSON while keeping roundtrip capability.

encode-for-roundtrip ($items as item()*, $options as object()) as item()* external

This function recursively encodes non-JSON types in such a way that they can be serialized as JSON while keeping roundtrip capability.

flatten ($items as item()*) as item()* external

For each item in the given sequence, this function returns the item itself, if it is not an array, or a sequence of items "flattened-out" from the array.

keys ($o as item()*) as string* external

Returns the set of keys belonging to the objects found inside a given sequence of items.

members ($a as item()*) as item()* external

Returns the items belonging to the arrays found inside a given sequence of items.

null () as js:null external

Returns the JSON null.

parse-json ($j as string?) as json-item()* external

This function parses a given string as JSON and returns a sequence of Objects or Arrays.

parse-json ($j as string?, $o as object()) as json-item()* external

This function parses a given string as JSON and returns a sequence of Objects or Arrays.

project ($items as item()*, $keys as string*) as item()* external

For each item in the given sequence, this function returns the item itself, if it is not an object, or its "projected" copy if it is an object.

size ($a as array()?) as integer? external

Returns the size of a JSON array, or the empty sequence if no array is given.

trim ($items as item()*, $keys as string*) as item()* external

For each item in the given sequence, this function returns the item itself, if it is not an object, or its "trimmed" copy, if it is an object.

Functions

decode-from-roundtrip#1

declare  function jn:decode-from-roundtrip($items as item()*) as item()* external
This function decodes non-JSON types previously encoded with jn:encode-for-roundtrip. Calling this version of the function is equivalent to calling the 2 argument version of the function with the second argument { "prefix" : "Q{http://jsoniq.org/roundtrip}" }

Parameters

items as item()
the items to be decoded.

Returns

item()*
the decoded items.

decode-from-roundtrip#2

declare  function jn:decode-from-roundtrip($items as item()*, $options as object()) as item()* external
This function decodes non-JSON types previously encoded with jn:encode-for-roundtrip. The $options parameter contains options for the decoding process. Currently the only supported option is "prefix". It specifies the prefix that determines if this function decodes an item. Example: jn:decode-from-roundtrip( { "nan" : { "pre-type" : "xs:double", "pre-value" : "NaN" } }, { "prefix" : "pre-" } ) returns the same instance that would be constructed by { "nan" : xs:double("NaN") } So let $decoded := jn:decode-from-roundtrip( { "nan" : { "pre-type" : "xs:double", "pre-value" : "NaN" } }, { "prefix" : "pre-" } ) let $nan := $decoded("nan") return ($nan instance of xs:double, $nan) returns true NaN

Parameters

items as item()
the items to be decoded.
options as object()
the decoding options.

Returns

item()*
the decoded items.

encode-for-roundtrip#1

declare  function jn:encode-for-roundtrip($items as item()*) as item()* external
This function recursively encodes non-JSON types in such a way that they can be serialized as JSON while keeping roundtrip capability. Calling this version of the function is equivalent to calling the 2 argument version of the function with the second argument { "prefix" : "Q{http://jsoniq.org/roundtrip}" "serialization-parameters" : } Note: The computations are made with respect to the static context of the caller, so that the schema type definitions are available.

Parameters

items as item()
the items to be encoded.

Returns

item()*
the encoded items.

encode-for-roundtrip#2

declare  function jn:encode-for-roundtrip($items as item()*, $options as object()) as item()* external
This function recursively encodes non-JSON types in such a way that they can be serialized as JSON while keeping roundtrip capability. Note: The computations are made with respect to the static context of the caller, so that the schema type definitions are available. Example: jn:encode-for-roundtrip( { "nan" : xs:double("NaN") }, { "prefix" : "pre-" } ) returns { "nan" : { "pre-type" : "xs:double", "pre-value" : "NaN" } }

Parameters

items as item()
the items to be encoded.
options as object()
the encoding options.

Returns

item()*
the encoded items.

flatten#1

declare  function jn:flatten($items as item()*) as item()* external
For each item in the given sequence, this function returns the item itself, if it is not an array, or a sequence of items "flattened-out" from the array. Flattening an array means replacing the array with its members, and recursively flattening any arrays in the members sequence. Note: The function is equivalent to define function jn:flatten($args as item()*) { for $arg in args return if ($arg instance of array()) then for $value in $arg[] return if ($value instance of array()) then jn:flatten($value[]) else $value else $arg };

Parameters

items as item()
A sequence of items

Returns

item()*
The flattened-out items of the arrays in $items.

keys#1

declare  function jn:keys($o as item()*) as string* external
Returns the set of keys belonging to the objects found inside a given sequence of items. The keys are returned in an implementation-defined order. Duplicate keys are eliminated.

Parameters

o as item()
A sequence of items. Only object items are actually processed; items of any other kind are simply skipped.

Returns

string*
The distinct keys of the objects in the input sequence.

members#1

declare  function jn:members($a as item()*) as item()* external
Returns the items belonging to the arrays found inside a given sequence of items. The items are returned in an implementation-defined order.

Parameters

a as item()
A sequence of items. Only array items are actually processed; items of any other kind are simply skipped.

Returns

item()*
The members of the arrays in the input sequence.

null#0

declare  function jn:null() as js:null external
Returns the JSON null.

Parameters

Returns

js:null
The JSON null.

parse-json#1

declare  function jn:parse-json($j as string?) as json-item()* external
This function parses a given string as JSON and returns a sequence of Objects or Arrays. Please note that this function allows to parse sequences of whitespace separated objects and arrays.

Parameters

j as string
A string containing a valid JSON text.

Returns

json-item()*
A sequence of JSON Object or Array item.

parse-json#2

declare  function jn:parse-json($j as string?, $o as object()) as json-item()* external
This function parses a given string as JSON and returns a sequence of Objects or Arrays.

Parameters

j as string
A string containing a valid JSON text.
o as object()
A JSON object defining options to configure the parser. Allowed options are
  • jsoniq-multiple-top-level-items: allow parsing of sequences of JSON Objects and Arrays (boolean; default: true)
  • jsoniq-strip-top-level-array: if the top-level JSON item is an array, strip it and return its elements as multiple top-level items (boolean; default: false)

Returns

json-item()*
a sequence of JSON Object or Array item.

project#2

declare  function jn:project($items as item()*, $keys as string*) as item()* external
For each item in the given sequence, this function returns the item itself, if it is not an object, or its "projected" copy if it is an object. Projecting an object by a set of keys means creating a new object from the specified pairs of the source object. Specifically, for each key in $keys, if the object has a pair with that key, then a copy of that pair is included in the new object.

Parameters

items as item()
A sequence of items.
keys as string
The keys of the pairs to include from each object in $items.

Returns

item()*
The projection of the original sequence.

size#1

declare  function jn:size($a as array()?) as integer? external
Returns the size of a JSON array, or the empty sequence if no array is given. The size of an Array is the number of members contained within it.

Parameters

a as array()
rray A JSON array.

Returns

integer?
The number of items in $array, or the empty sequence if $array is empty.

trim#2

declare  function jn:trim($items as item()*, $keys as string*) as item()* external
For each item in the given sequence, this function returns the item itself, if it is not an object, or its "trimmed" copy, if it is an object. Trimming an object by a set of keys means creating a new object containing all the pairs of the source object except the ones whose key appears in the given set of keys.

Parameters

items as item()
A sequence of items.
keys as string
The keys of the pairs to exclude from each object in $items.

Returns

item()*
The trimmed version of the input sequence.