Changes

This [[Module Library|XQuery Module]] contains functions to parse and serialize JSON documents. data [httphttps://www.json.org/ 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.

All functions and errors in this module are assigned to the {{Code|<code><nowiki>http://basex.org/modules/json}} </nowiki></code> namespace, which is statically bound to the {{Code|json}} prefix.<br/>All errors are assigned to the {{Code|http://basex.org/errors}} namespace, which is statically bound to the {{Code|bxerr}} prefix.

The '''A little advice''': in the Database Creation dialog of the GUI, if you select JSON Parsing and switch to the ''Parsing'' tab, you can see the effects of some of the conversion rules have been updated with {{Version|7options.8}}:

# * The resulting document has a {{Code|<json>}} root node. # * Object pairs are represented via elements. The name of a pair is rewritten to an element name:## Empty names are represented by a single underscore ({{Code|_}})encoded, existing underscores are rewritten to two underscores ({{Code|__}}), and characters that are not valid as described in element names are rewritten to an underscore and the character’s four-digit Unicode.[[Conversion Module## If the {{Code|lax}} option is set to {{CodeKeys|false}}Conversion Module]], invalid characters are simply replaced with underscores. The resulting names are better readable, but may not be losslessly converted back to their original formand used as element name.# * Array entries are also represented via elements. , with {{Code|<_>}} is used as element name ({{Code|value}} was used before {{Version|7.8}}).# * Object and array values are stored in text nodes.# * The types of values are represented via {{Code|type}} attributes:## ** The existing types are ''string'', ''number'', ''boolean'', ''null'', ''object'', and ''array''.## ** As most values are strings, the ''string is the default, it '' type is by default omitted.

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

===MapBasic===

The {{Code|mapbasic}} format is another losslessformat. It converts a JSON document to an XML node and vice versa. The conversion rules for are specified in the same as for [[XSLT XQuery 3.01#fn:json-to-xml|httpfn://www.w3.org/TR/xslt-30/#funcjson-parseto-json specificationxml]].

The {{Code|jsonml}} format can be used is designed to transform 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 [http://jsonml.org/XML JsonML documentation]. ===XQuery=== The {{Code|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 [[XQuery 3.1#fn:parse-json|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.

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

| {{Code|direct}}, {{Code|attributes}}, {{Code|jsonml}}, {{Code|mapxquery}}

| Determines if minor deviations from [https://www.rfc-editor.org/rfc/rfc7159.txt RFC 7159] will be ignored.| {{Code|yes}}, {{Code|no}}| {{Code|no}}| ''parse'', ''serialize''

* If a name has the same type throughout the documentdata, the {{Code|type}} attribute will be omitted. Instead, the name will be listed in additional, type-specific attributes in the root node.

| {{Code|yesno}}

| {{Code|unescapeescape}}

|{{Func|json:parse|$input string as xs:string?|elementitem(json)?}}<br/>{{Func|json:parse|$input string as xs:string?, $options as itemmap(*)?|elementitem(json)?}}

|Converts the JSON document specified by {{Code|$inputstring}} to XML, and returns an XQuery value. If the result as {{Code|element(json)}} instance. The converted XML document is both well readable and lossless, i.e.input can be successfully parsed, the converted document it can be serialized back to the original JSON representation.<br/>The {{Code|$options}} argument can be used to control the way the input is converted. The following options are available (they bear resemblance to the ones specified in [http://www.w3.org/TR/xslt-30/#json XSLT 3.0]):* {{Code|spec}} determines the used JSON specification. Allowed values are {{Code|RFC4627}}, {{Code|ECMA-262}}, and {{Code|liberal}}; the default is ({{Code|RFC4627}}).* {{Code|unescape}} determines whether escape sequences (marked by a backslash) in the input are expanded. The default is {{Code|true}}.* {{Code|format}} determines the conversion format. Allowed values are {{Code|json}}, {{Code|jsonml}}, and {{Code|map}}; the default is {{Code|json}}.Options can either be specified<br />* as children of an {{Code|<json:options/>}} element; e.g.:<pre class="brush:xml"><json:options> <json:format value='jsonml'/> ...</json:options></pre>* or as map, which contains all key/value pairs:<pre class="brush:xquery">{ 'format' : 'jsonml', ... }</pre>

|{{Error|BXJS0001parse|#Errors}} the specified input cannot be parsed as JSON document.<br/>{{Error|BXJS0003options|#Errors}} a the specified option cannot be parsedoptions are conflicting.

==json:serializedoc==

{{VersionMark|7Introduced with BaseX 9.7.2}}4: {{Code|$options}} argument added

|{{Func|json:serializedoc|$input uri as node()|xs:string|item()?}}<br/>{{Func|json:serializedoc|$input uri as node()xs:string, $options as map(*)?|item()|xs:string?}}<br />

|Serializes Fetches the node specified by {{Code|$input}} as JSON, and returns the result as {{Code|xs:string}} instance. The serialized node must conform document referred to the syntax specified by the [[#json:parse|json:parse()]] function.<br />XML documents can also be serialized as JSON if the [[Serialization|Serialization Option]] given {{Code|method$uri}} is set and converts it to {{Code|json}}an XQuery value.<br/>The {{Code|$options}} argument can be used to control the way the input is serialized. The following options are available (they bear resemblance to the ones specified in [http://www.w3.org/TR/xslt-30/#json XSLT 3.0]):* {{Code|spec}} determines the used JSON specification. Allowed values are {{Code|RFC4627}}, {{Code|ECMA-262}}, and {{Code|liberal}}; the default is ({{Code|RFC4627}}).* {{Code|unescape}} determines whether escape sequences (marked by a backslash) in the input are expanded. The default is {{Code|true}}.* {{Code|format}} determines the conversion format. Allowed values are {{Code|json}} and {{Code|jsonml}}; the default is {{Code|json}}converted.Options can either be specified<br />* as children of an {{Code|<json:options/>}} element; e.g.:<pre class="brush:xml"><json:options> <json:format value='jsonml'/> ...</json:options></pre>* or as map, which contains all key/value pairs:<pre class="brush:xquery">{ 'format' : 'jsonml', ... }</pre>

|{{Error|BXJS0002parse|#Errors}} the specified node input cannot be serialized parsed as JSON document.<br/>{{Error|options|#Errors}} the specified options are conflicting.

==json:serialize-ml== {{Version|7.7.2}}: deprecated; please use [[#json:serialize|json:serialize]] instead.

|{{Func|json:serialize-ml|$input as nodeitem()?|xs:string}}<br/>{{Func|json:serialize|$input as item()?, $options as map(*)?|xs:string}}

|Serializes the node specified by {{Code|$input}} as JSON, using the specified {{Code|$options}}, and returns the result as {{Codestring:* The input is expected to conform to the results that are created by [[#json:parse|xsjson:string}} instanceparse()]].<br />XML documents can also * Non-conforming items will be output serialized as specified in the JsonML format by setting the [[XQuery 3.1#JSON Serialization|json output method]] of the official recommendation.Values can also be serialized as JSON with the standard [[Serialization Option]] feature of XQuery:* The parameter {{Code|method}} needs to be set to {{Code|json}}, and* the options presented in this article need to be assigned to the {{Code|jsonmljson}}parameter.

|{{Error|BXJS0002serialize|#Errors}} the specified value node cannot be serialized.|} ==json:parse-ml== {{Version|7.7.2}}: deprecated; please use [[#json:parse|json:parse]] instead. {| width='100%'|-| width='120' | '''Signatures'''|{{Func|json:parse-ml|$input as xs:string|element()}}|-| '''Summary'''|Converts the [http://jsonml.org JsonML] JSON document specified by {{Code|$input}} to XML, and returns the result as {{Code|element()}} instance. The JSON input must conform to the JsonML specification to be successfully converted.|-| '''Errors'''|{{Error|BXJS0001|#Errors}} the specified input cannot be parsed as JsonML instance.

<pre classsyntaxhighlight lang="brush:xquery">

return db:add($database, document { $json }, $name) </presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xquery">

</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml"><json objectstype="jsonobject"/></presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xquery">

json:serialize(<json objectstype="jsonobject"/>)</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xquery">

</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xquery">

"modified": "20092014-02-02T11:10:27Z",

</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml"><json objectstype="jsonobject">

<modified>20092014-02-02T11:10:27Z</modified>

</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xquery">let $options := map { 'merge': true() }return json:parse('{

}', $options)</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml">

<value_>

</value_> <value_>

</value_>

</presyntaxhighlight>

'''Example 1: Converts all XML documents in a database to the JsonML format and writes them to disk'''

<pre classsyntaxhighlight lang="brush:xquery">

let $json := json:serialize($doc, map { 'format': 'jsonml' })

</presyntaxhighlight>

'''Example 2: Converts a simple an XML fragment to the JsonML formatdocument with elements and text'''

<pre classsyntaxhighlight lang="brush:xquery">json:serialize(<xml/>, { 'format': 'jsonml' })</pre> '''Result:'''<pre>["xml"]</pre> '''Example 3: Converts an XML document with elements and text''' '''Query:'''<pre class="brush:xquery">json:serialize(doc('flickr.xml'), map { 'format': 'jsonml' })</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml">

<modified>20092014-02-02T11:10:27Z</modified>

</presyntaxhighlight>

<presyntaxhighlight lang="json">

"http:\/\/www.flickr.com\/groups\/talkontravel\/pool\/"],

"20092014-02-02T11:10:27Z"],

"http:\/\/www.flickr.com\/"]]</presyntaxhighlight>

'''Example 43: Converts a document with nested elements and attributesto JsonML'''

<pre classsyntaxhighlight lang="brush:xquery">json:serialize(doc('input.xml'), map { 'format': 'jsonml' })</presyntaxhighlight>

<pre classsyntaxhighlight lang="brush:xml">

</presyntaxhighlight>

<presyntaxhighlight lang="json">

</presyntaxhighlight> ==XQuery Format== '''Example 1: Converts a JSON string to XQuery''' '''Query:'''<syntaxhighlight lang="xquery">let $input := '{ "Title": "Drinks", "Author": [ "Jim Daniels", "Jack Beam" ]}'let $data := json:parse($input, map { 'format': 'xquery' })return map:for-each($data, function($k, $v) { $k || ': ' || string-join($v, ', ')})</syntaxhighlight> '''Result:'''<syntaxhighlight lang="json">Author: Jim Daniels, Jack BeamTitle: Drinks</syntaxhighlight> '''Example 2: Converts XQuery data to JSON''' '''Query:'''<syntaxhighlight lang="xquery">for $item in ( true(), 'ABC', array { 1 to 5 }, map { "Key": "Value" })return json:serialize( $item, map { 'format': 'xquery', 'indent': 'no' })</syntaxhighlight> '''Result:'''<syntaxhighlight lang="json">true"ABC"[1,2,3,4,5]{"Key":"Value"}</syntaxhighlight>

|{{Code|BXJS0001options}}|The specified options are conflicting.|-|{{Code|parse}}

|{{Code|BXJS0002serialize}}

* Updated: {{Code|$options}} argument added to [[#json:parse|json:parse]] and [[#json:serialize|json:serialize]].* Updated: [[#json:parse-ml|json:parse-ml]] and [[#json:serialize-ml|json:serialize-ml]] are now ''deprecated''.