Reads an external resource containing JSON, and returns the result of parsing the resource as JSON.
fn:json-doc
( $href
as xs:string?
item()?
fn:json-doc
( $href
as xs:string?
,$options
as map(*)
item()?
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:
The function may accept a resource in any encoding. 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.
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.
The function may raise any error defined for the fn:unparsed-text
or fn:parse-json
functions.
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
).