fn:doc

fn:doc($uri as xs:string?) as document-node()?

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

If $uri is the empty sequence, the result is an empty sequence.

If $uri 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 promoted to an xs:string.

If the available documents described in Dynamic Context provides a mapping from this string to a document node, the function returns that document node.

The URI may include a fragment identifier.

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 be true:

doc("foo.xml") is doc("foo.xml")

However, for performance reasons, 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 [ERRFODC0003].

If $uri is read 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 [ERRFODC0002]. The data resulting from the retrieval action is then parsed as an XML document and a tree is constructed in accordance with the [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 [ERRFODC0002]. 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 [ERRFODC0005] if $uri is not a valid URI reference.

A dynamic error is raised [ERRFODC0002] if a relative URI reference is supplied, and the base-URI property in the static context is absent.

A dynamic error is raised [ERRFODC0002] if the available documents provides no mapping for the absolutized URI.

A dynamic error is raised [ERRFODC0002] if the resource cannot be retrieved or cannot be parsed successfully as XML.

A dynamic error is raised [ERRFODC0003] 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.