If $source is the empty sequence, the result is an empty sequence.
If $source is a relative URI reference, it is resolved relative to the value of the static base URI property from the static context. The resulting absolute URI is cast to an xs:string.
If the available documents described in Section 2.1.2 Dynamic Context XP31 provides a mapping from this string to a document node, the function returns that document node.
The URI may include a fragment identifier.
The $options argument, if present and non-empty, defines the detailed behavior of the function. The option parameter conventions apply. The options available are as follows:
record( |
dtd-validation? | as xs:boolean, |
allow-external-entities? | as xs:boolean, |
entity-expansion-limit? | as xs:integer?, |
stable? | as xs:boolean, |
strip-space? | as xs:boolean?, |
xinclude? | as xs:boolean, |
xsd-validation? | as xs:string, |
xsi-schema-location? | as xs:boolean |
) |
| Key | Value | Meaning |
|---|
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. |
allow-external-entities?
| Determines whether references to external entities (including a DTD entity) are permitted. Type: xs:boolean Default: true()
|
true | References to external entities are permitted, and are resolved relative to the base URI. |
false | References to external entities (including an external DTD) are not permitted, and result in the call on parse-xml failing with a dynamic error if present. |
entity-expansion-limit?
| Places a limit on the maximum number of entity references that may be expanded, or on the size of the expanded entities. The limit applies both to internal and external entities, but not to built-in entity references, nor to character references. Type: xs:integer? Default: ()
|
() | The limit (if any) is implementation-dependent. |
integer | The processor should impose a limit on the number of entity references that are expanded, or on the size of the expanded entities, depending on the options available in the underlying XML parser; the limit should be commensurate with the value requested, but the precise effect may be . implementation-dependent. If the XML parser does not offer the ability to impose a limit, or if the value is zero, then entity expansion should if possible be disabled entirely, leading to a dynamic error if the input contains any entity references. A negative value should be interpreted as placing no limits on entity expansion. |
stable?
| Determines whether two calls on the doc 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 deterministic. |
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. The default is defined by the host language or by the implementation. (Note: in XSLT, the xsl:strip-space and xsl:preserve-space declarations provide detailed control based on the parent element name.) Type: xs:boolean? Default: ()
|
true | All whitespace-only text nodes are stripped, unless either (a) they are within the scope of the attribute xml:space="preserve", or (b) XSD validation identifies that the parent element has a simple type or a complex type with simple content. |
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. Type: xs:string Default: "skip"
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 doc function without validation, and then applying an XQuery validate expression to the result, with corresponding options. Type: xs:string Default: "skip"
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 doc function without validation, and then applying an XQuery validate expression to the result, with corresponding options. 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 static context, that has the given URI and local name. |
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 Section 4.1.2 Schema ConsistencyDM. |
false | Any xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes in the document are ignored. |
By default, this function is deterministic. Two calls on this function return the same document node if the same URI Reference (after resolution to an absolute URI Reference) is supplied to both calls. Thus, the following expression (if it does not raise an error) will always return true:
doc("foo.xml") is doc("foo.xml")Note:
This equivalence applies only because the two calls on the fn:doc function have the same options and the same static and dynamic context, to the extent this is relevant. If two calls on fn:doc have different dynamic contexts, then the mapping from URIs to document nodes in the two contexts may differ, which means that different document nodes may be returned for the same URI. This can happen, for example, if the two calls appear in different XSLT packages with different validation options or whitespace-stripping options; one call might produce a schema-validated document, the other an untyped document.
The requirement to deliver a deterministic result has performance implications, and for this reason implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is implementation-defined. If the user has not selected such an option, a call of the function must either return a deterministic result or must raise a dynamic error [err:FODC0003].
Note:
If the $source URI is obtained from a source document, it is generally appropriate to resolve it relative to the base URI property of the relevant node in the source document. This can be achieved by calling the fn:resolve-uri function, and passing the resulting absolute URI as an argument to the fn:doc function.
If two calls to this function supply different absolute URI References as arguments, the same document node may be returned if the implementation can determine that the two arguments refer to the same resource.
By defining the semantics of this function in terms of a string-to-document-node mapping in the dynamic context, the specification is acknowledging that the results of this function are outside the purview of the language specification itself, and depend entirely on the run-time environment in which the expression is evaluated. This run-time environment includes not only an unpredictable collection of resources (“the web”), but configurable machinery for locating resources and turning their contents into document nodes within the XPath data model. Both the set of resources that are reachable, and the mechanisms by which those resources are parsed and validated, are implementation-dependent.
One possible processing model for this function is as follows. The resource identified by the URI Reference is retrieved. If the resource cannot be retrieved, a dynamic error is raised [err:FODC0002]. The data resulting from the retrieval action is then parsed as an XML document and a tree is constructed in accordance with the [XQuery and XPath Data Model (XDM) 3.0]. If the top-level media type is known and is "text", the content is parsed in the same way as if the media type were text/xml; otherwise, it is parsed in the same way as if the media type were application/xml. If the contents cannot be parsed successfully, a dynamic error is raised [err:FODC0002]. Otherwise, the result of the function is the document node at the root of the resulting tree. This tree is then optionally validated against a schema.
Various aspects of this processing are implementation-defined. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:
The set of URI schemes that the implementation recognizes is implementation-defined. Implementations may allow the mapping of URIs to resources to be configured by the user, using mechanisms such as catalogs or user-written URI handlers.
The handling of non-XML media types is implementation-defined. Implementations may allow instances of the data model to be constructed from non-XML resources, under user control.
It is implementation-defined whether DTD validation and/or schema validation is applied to the source document.
Implementations may provide user-defined error handling options that allow processing to continue following an error in retrieving a resource, or in parsing and validating its content. When errors have been handled in this way, the function may return either an empty sequence, or a fallback document provided by the error handler.
Implementations may provide user options that relax the requirement for the function to return deterministic results.
The effect of a fragment identifier in the supplied URI is implementation-defined. One possible interpretation is to treat the fragment identifier as an ID attribute value, and to return a document node having the element with the selected ID value as its only child.
A dynamic error may be raised [err:FODC0005] if $source is not a valid URI reference.
A dynamic error is raised [err:FODC0002] if a relative URI reference is supplied, and the base-URI property in the static context is absent.
A dynamic error is raised [err:FODC0002] if the available documents provides no mapping for the absolutized URI.
A dynamic error is raised [err:FODC0002] if the resource cannot be retrieved or cannot be parsed successfully as XML using the selected options.
A dynamic error is raised [err:FODC0003] if the implementation is not able to guarantee that the result of the function will be deterministic, and the user has not indicated that an unstable result is acceptable.