XSL Transformations (XSLT) Version 4.0

20.1 fn:document

Summary

Provides access to XML documents identified by a URI.

Signature

fn:document(
$uri-sequence	as item()*,
$base-node$options$base-nodeoptions	as node()?as (map(*)|node())?as (map(*)|node())?	:= ():= map{}:= ()map{}
) as node()*

Properties

The one-argument form of this function is deterministic^FO, focus-independent^FO, and context-dependent^FO. It depends on static base URI.

The two-argument form of this function is deterministic^FO, focus-independent^FO, and context-independent^FO.

Rules

The document function allows access to XML documents identified by a URI.

The first argument contains a sequence of URI references. The second argument, if present, is a node whose base URI is used to resolve any relative URI references contained in the first argument.

The first argument contains a sequence of URI references. These are resolved as described below.

The second argument, if present, may be either a node, or an options map. Supplying a node is allowed for backwards compatibility: the effect of supplying a node $N is the same as supplying the map {"base-uri": fn:base-uri($N)}. The effect is that the base URI of the node is used to resolve any relative URI references contained in the first argument.

If the second argument is supplied as a map, then the option parameter conventions^FO apply. The options available are as follows, and apply to each of the documents constructed by the function:

<record>$base-uri as xs:anyURI, $trusted as xs:boolean, $dtd-validation as xs:boolean, $stable as xs:boolean, $strip-space as xs:boolean?, $xinclude as xs:boolean, $xsd-validation as xs:string, $use-xsi-schema-location as xs:boolean, $schema as xs:NCName</record>

Key	Value	Meaning
base-uri?	Determines the base URI used to resolve any relative URI supplied in the first argument. This in turn affects the base URI of the constructed document. Type: xs:anyURI Default: Where the first argument supplies a node, the base URI property of that node is used to resolve the URI. Where the first argument supplies an atomic value, the static base URI of the function call is used.
trusted?	Indicates whether processing the document may cause other external resources to be fetched (including, for example, external entities, an external DTD, or documents referenced using xsi:schemaLocation or XInclude elements). Type: xs:boolean Default: false
	true	The document may include references to other external resources.
	false	The document must not include references to other external resources unless access to these resources has been explicitly enabled.
dtd-validation?	Determines whether DTD validation takes place. Type: xs:boolean Default: false
	true	The input is parsed using a validating XML parser. The input must contain a DOCTYPE declaration to identify the DTD to be used for validation. The DTD may be internal or external.
	false	DTD validation does not take place. However, if a DOCTYPE declaration is present, then it is read, for example to perform entity expansion.
stable?	Determines whether two calls on the document function, with the same URI, the same options, and the same context, are guaranteed to return the same document node. The default value is true, but this may be overridden by implementation-defined configuration options. Type: xs:boolean Default: true
	true	Given the same explicit and implicit arguments, multiple calls return the same document node: that is, the function is .
	false	Multiple calls with the same explicit and implicit arguments may return the same document node or different document nodes at the discretion of the implementation.
strip-space?	Determines whether whitespace-only text nodes are removed from the resulting document. Type: xs:boolean? Default: true
	true	Whitespace stripping is to take place according to the xsl:strip-space and xsl:preserve-space declarations of the containing package: see 4.2.2 Stripping Whitespace from a Source Tree.
	false	All whitespace-only text nodes are preserved, unless either (a) DTD validation marks them as ignorable, or (b) XSD validation recognizes the containing element as having element-only or empty content.
xinclude?	Determines whether any xi:include elements in the input are to be processed using an XInclude processor. Type: xs:boolean Default: false
	true	Any xi:include elements are expanded. If there are xi:include elements and no XInclude processor is available then a dynamic error is raised.
	false	Any xi:include elements are handled as ordinary elements without expansion.
xsd-validation?	Determines whether XSD validation takes place, using the schema definitions present in the static context. The effect of requesting validation is the same as invoking the document function without validation, and then applying the instruction xsl:copy-of to the result, with corresponding validation and type options, using the schema identified in the schema option if specified. Type: xs:string Default: skip
	strict	Strict XSD validation takes place
	lax	Lax XSD validation takes place
	skip	No XSD validation takes place
	type Q{uri}local	XSD validation takes place against the schema-defined type, present in the selected schema, that has the given URI and local name.
use-xsi-schema-location?	When XSD validation takes place, determines whether schema components referenced using xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes within the source document are to be used. The option is ignored if XSD validation does not take place. Type: xs:boolean Default: false
	true	XSD validation uses the schema components referenced using xsi:schemaLocation or xsi:noNamespaceSchemaLocation attributes in addition to the schema components present in the static context; these components must be compatible as described in [XDM 4.0] section 4.1.2 Schema Consistency.
	false	Any xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes in the document are ignored.
schema?	When XSD validation takes place, identifies the schema to be used for validation. If supplied, the value must match the role attribute of an xsl:import-schema declaration in the containing package. A zero-length string refers to the schema imported using an xsl:import-schema declaration with no role attribute. Type: xs:NCName Default: The schema in the static context of the fn:document function call (determined by the innermost element with an [xsl:]schema-role attribute if present).

A sequence of absolute URI references is obtained as follows.

• For an item in $uri-sequence that is an instance of xs:string, xs:anyURI, or xs:untypedAtomic, the value is cast to xs:anyURI. If the resulting URI reference is an absolute URI reference then it is used as is. If it is a relative URI reference, then it is resolved as follows:For an item in $uri-sequence that is an instance of xs:string, xs:anyURI, or xs:untypedAtomic, the value is cast to xs:anyURI. If the resulting URI reference is an absolute URI reference then it is used as is. If it is a relative URI reference R, then it is resolved as follows:For an item in $uri-sequence that is an instance of xs:string, xs:anyURI, or xs:untypedAtomic, the value is cast to xs:anyURI. If the resulting URI reference is an absolute URI reference then it is used as is. If it is a relative URI reference R, then it is resolved as follows:

  1. If $base-node is supplied (that is, if the argument is present and non-empty), then it is resolved against the base URI of $base-node.If the second argument $options is an XNode, then R is resolved against the base URI of that node.If the second argument $base-nodeoptions is suppliedan (that is, if the argument is present and non-empty)XNode, , then itR is resolved against the base URI of $base-that node.

  2. If $options is supplied as a map and includes a value for the base-uri option, then R is resolved against that URI.

  3. If $options is supplied as a map and includes a value for the base-uri option, then R is resolved against that URI.

  4. Otherwise it is resolved against the static base URI from the static context of the expression containing the call to the document function. In cases where the source code of the stylesheet is available at execution time, this will typically be the location of the relevant stylesheet module.Otherwise R is resolved against the static base URI from the static context of the expression containing the call to the document function. In cases where the source code of the stylesheet is available at execution time, this will typically be the location of the relevant stylesheet module.Otherwise itR is resolved against the static base URI from the static context of the expression containing the call to the document function. In cases where the source code of the stylesheet is available at execution time, this will typically be the location of the relevant stylesheet module.

• For an item in $uri-sequence that is a node, the node is atomized. The result must be a sequence whose items are all instances of xs:string, xs:anyURI, or xs:untypedAtomic. Each of these values is cast to xs:anyURI, and if the resulting URI reference is an absolute URI reference then it is used as is. If it is a relative URI reference, then it is resolved against the base URI of $base-node if supplied, or against the base URI of the node that contained it otherwise.For an item in $uri-sequence that is a node N, the node is atomized. The result must be a sequence whose items are all instances of xs:string, xs:anyURI, or xs:untypedAtomic. Each of these values is cast to xs:anyURI, and if the resulting URI reference is an absolute URI reference then it is used as is. If it is a relative URI reference R, then it is resolved as follows:For an item in $uri-sequence that is a node N, the node is atomized. The result must be a sequence whose items are all instances of xs:string, xs:anyURI, or xs:untypedAtomic. Each of these values is cast to xs:anyURI, and if the resulting URI reference is an absolute URI reference then it is used as is. If it is a relative URI reference R, then it is resolved against the base URI of as follows$base-node: if supplied, or against the base URI of the node that contained it otherwise.

  1. If the second argument $options is an XNode, then R is resolved against the base URI of that node.

  2. If $options is supplied as a map and includes a value for the base-uri option, then R is resolved against that URI.

  3. Otherwise R is resolved against the base URI of N.

• A relative URI is resolved against a base URI using the rules of the resolve-uri function. A dynamic error occurs (see below) if no base URI is available.

• If $uri-sequence (after atomizing any nodes) contains an item other than an atomic item of type xs:string, xs:anyURI, or xs:untypedAtomic then a type error is raised [ERR XPTY0004] ^XP40.

Each of these absolute URI references is then processed as follows. Any fragment identifier that is present in the URI reference is removed, and the resulting absolute URI is cast to a string and then passed to the doc function defined in [Functions and Operators 4.0]. This returns a document node. If an error occurs during evaluation of the doc function, the processor may either raise this error in the normal way, or may recover by ignoring the failure, in which case the failing URI will not contribute any nodes to the result of the document function.

If the URI reference contained no fragment identifier, then this document node is included in the sequence of nodes returned by the document function.

If the URI reference contained a fragment identifier, then the fragment identifier is interpreted according to the rules for the media type of the resource representation identified by the URI, and is used to select zero or more nodes that are descendant-or-self nodes of the returned document node. As described in 2.3 Initiating a Transformation, the media type is available as part of the evaluation context for a transformation.

The sequence of nodes returned by the function is in document order, with no duplicates. This order has no necessary relationship to the order in which URIs were supplied in the $uri-sequence argument.

Error Conditions

[ERR XTDE1160] When a URI reference contains a fragment identifier, it is a dynamic error if the media type is not one that is recognized by the processor, or if the fragment identifier does not conform to the rules for fragment identifiers for that media type, or if the fragment identifier selects something other than a sequence of nodes (for example, if it selects a range of characters within a text node).

A processor may provide an option which, if selected, causes the processor instead of raising this error, to ignore the fragment identifier and return the document node.

The set of media types recognized by a processor is implementation-defined.

[ERR XTDE1162] When a URI reference is a relative reference, it is a dynamic error if no base URI is available to resolve the relative reference. This can arise for example when the URI is contained in a node that has no base URI (for example a parentless text node), or when the second argument to the function is a node that has no base URI, or when the base URI from the static context is undefined.

Notes

One effect of these rules is that in an interpreted environment where the source code of the stylesheet is available and its base URI is known, then unless XML entities or xml:base are used, the expression document("") refers to the document node of the containing stylesheet module (the definitive rules are in [RFC3986]). The XML resource containing the stylesheet module is then processed exactly as if it were any other XML document, for example there is no special recognition of xsl:text elements, and no special treatment of comments and processing instructions.

The XPath rules for function calling ensure that it is a type error if the supplied value of the second argument is anything other than a single node. If XPath 1.0 compatibility mode is enabled, then a sequence of nodes may be supplied, and the first node in the sequence will be used.