fn:json-to-xml

fn:json-to-xml($json-text as xs:string?) as document-node()?

fn:json-to-xml(
    $json-text as xs:string?, 
    $options as map(*)
) as document-node()?

This function is nondeterministic, context-dependent, and focus-independent. It depends on static base URI.

The effect of the one-argument form of this function is the same as calling the two-argument form with an empty map as the value of the $options argument.

The first argument is a JSON-text as defined in [RFC 7159], in the form of a string. The function parses this string to return an XDM node.

If $json-text is an empty sequence, the function returns the empty sequence.

The $options argument can be used to control the way in which the parsing takes place. The option parameter conventions apply.

The entries that may appear in the $options map are as follows:

The various structures that can occur in JSON are transformed recursively to XDM values according to the rules given in XML Representation of JSON.

The function returns a document node, whose only child is the element node representing the outermost construct in the JSON text.

The function is non-deterministic with respect to node identity: that is, if the function is called twice with the same arguments, it is implementation-dependent whether the same node is returned on both occasions.

The base URI of the returned document node is taken from the static base URI of the function call.

The choice of namespace prefix (or absence of a prefix) in the names of constructed nodes is implementation-dependant.

The XDM tree returned by the function does not contain any unnecessary (albeit valid) nodes such as whitespace text nodes, comments, or processing instructions. It does not include any whitespace in the value of number or boolean element nodes, or in the value of escaped or escaped-key attribute nodes.

If the result is typed, every element named string will have an attribute named escaped whose value is either true or false, and every element having an attribute named key will also have an attribute named escaped-key whose value is either true or false.

If the result is untyped, the attributes escaped and escaped-key will either be present with the value true, or will be absent. They will never be present with the value false.

An error is raised [ERRFOJS0001] if the value of $input does not conform to the JSON grammar as defined by [RFC 7159], unless the option "liberal":true() is present and the processor chooses to accept the deviation.

An error is raised [ERRFOJS0004] if the value of the validate option is true and the processor does not support schema validation or typed data.

An error is raised [ERRFOJS0005] if the value of $options includes an entry whose key is defined in this specification, and whose value is not a permitted value for that key.

To read a JSON file, this function can be used in conjunction with the fn:unparsed-text function.

Many JSON implementations allow commas to be used after the last item in an object or array, although the specification does not permit it. The option spec="liberal" is provided to allow such deviations from the specification to be accepted. Some JSON implementations also allow constructors such as new Date("2000-12-13") to appear as values: specifying spec="liberal" allows such extensions to be accepted, but does not guarantee it. If such extensions are accepted, the resulting value is implementation-defined, and will not necessarily conform to the schema at Schema for the result of fn:json-to-xml.

If the input starts with a byte order mark, this function ignores it. The byte order mark may have been added to the data stream in order to facilitate decoding of an octet stream to a character string, but since this function takes a character string as input, the byte order mark serves no useful purpose.

The possibility of the input containing characters that are not valid in XML (for example, unpaired surrogates) arises only when such characters are expressed using JSON escape sequences. The is because the input to the function is an instance of xs:string, which by definition can only contain characters that are valid in XML.

The expression json-to-xml('{"x": 1, "y": [3,4,5]}') returns (with whitespace added for legibility):

<map xmlns="http://www.w3.org/2005/xpath-functions">
  <number key="x">1</number>
  <array key="y">
   <number>3</number>
   <number>4</number>
   <number>5</number>
  </array>
</map>

The expression json-to-xml('"abcd"', map{'liberal': false()}) returns <string xmlns="http://www.w3.org/2005/xpath-functions">abcd</string>.

The expression json-to-xml('{"x": "\\", "y": "\u0025"}') returns (with whitespace added for legibility):

<map xmlns="http://www.w3.org/2005/xpath-functions">
  <string key="x">\</string>
  <string key="y">%</string>
</map>

The expression json-to-xml('{"x": "\\", "y": "\u0025"}', map{'escape': true()}) returns (with whitespace added for legibility):

<map xmlns="http://www.w3.org/2005/xpath-functions">
  <string escaped="true" key="x">\\</string>
  <string key="y">%</string>
</map>

The following example illustrates use of the fallback function to handle characters that are invalid in XML.

 let 
   $jsonstr := unparsed-text('http://example.com/endpoint'),
   $options := map {
     'liberal': true(),
     'fallback': function($char as xs:string) as xs:string {
       let 
         $c0chars := map {
           '\u0000':'[NUL]',
           '\u0001':'[SOH]',
           '\u0002':'[STX]',
           ...
           '\u001E':'[RS]',
           '\u001F':'[US]'
         },
         $replacement := $c0chars($char)
      return 
        if (exists($replacement))
        then $replacement
        else error(xs:QName('err:invalid-char'), 
          'Error: ' || $char || ' is not a C0 control character.')
     }
   }
 return json-to-xml($jsonstr, $options)