fn:json-doc

Reads an external resource containing JSON, and returns the result of parsing the resource as JSON.

Signatures

fn:json-doc($href as xs:string?) as item()?
fn:json-doc(
    $href as xs:string?, 
    $options as map(*)
) as item()?

Properties

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

Rules

The effect of the single-argument call fn:json-doc($H) is the same as the effect of the two-argument call fn:json-doc($H, map{}) where an empty map is supplied as the second argument.

The effect of the two-argument function call fn:json-doc($H, $M)is equivalent to the function composition fn:unparsed-text($H) => fn:parse-json($M); except that:

  1. The function may accept a resource in any encoding. [RFC 7159] requires UTF-8, UTF-16, or UTF-32 to be accepted, but it is not an error if a different encoding is used. Unless external encoding information is available, the function must assume that the encoding is one of UTF-8, UTF-16, or UTF-32, and must distinguish these cases by examination of the initial octets of the resource.

  2. If the resource contains characters that are not valid in the version of XML used by the processor, then rather than raising an error as fn:unparsed-text#1 does, the function replaces such characters by the equivalent JSON escape sequence prior to parsing.

    Equivalently, the implementation can use some other internal representation of strings that allows non-XML characters to be manipulated.

If the value of $href is the empty sequence, the function returns the empty sequence.

Error Conditions

The function may raise any error defined for the fn:unparsed-text or fn:parse-json functions.

Notes

If the input cannot be decoded (that is, converted into a sequence of Unicode codepoints, which may or may not represent characters), then a dynamic error occurs as with the fn:unparsed-text function.

If the input can be decoded, then the possibility still arises that the resulting sequence of codepoints includes codepoints that do not represent characters that are valid in the version of XML that the processor supports. Such codepoints are translated into JSON escape sequences (for example, \uFFFF), and the JSON escape sequence is then passed to the fallback function specified in the $options argument, which in turn defaults to a function that returns the Unicode REPLACEMENT CHARACTER (xFFFD).