XPath/XQuery resolve-uri function

Summary

Resolves a relative IRI reference against an absolute IRI.

Signatures

fn:resolve-uri(
$relative as xs:string?
) as xs:anyURI?
fn:resolve-uri(
$relative as xs:string?,
$base as xs:string
) as xs:anyURI?

Properties

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

Rules

The function is defined to operate on IRI references as defined in , and the implementation must permit all arguments that are valid according to that specification. In addition, the implementation may accept some or all strings that conform to the rules for (absolute or relative) Legacy Extended IRI references as defined in . For the purposes of this section, the terms IRI and IRI reference include these extensions, insofar as the implementation chooses to support them.

The following rules apply in order:

  1. If $relative is the empty sequence, the function returns the empty sequence.

  2. If $relative is an absolute IRI (as defined above), then it is returned unchanged.

  3. If the $base argument is not supplied, then:

    If the static base URI in the static context is not absent, it is used as the effective value of $base.

    Otherwise, a dynamic error is raised: .

  4. The function resolves the relative IRI reference $relative against the base IRI $base using the algorithm defined in , adapted by treating any character that would not be valid in an RFC3986 URI or relative reference in the same way that RFC3986 treats unreserved characters. No percent-encoding takes place.

Error Conditions

The first form of this function resolves $relative against the value of the base-uri property from the static context. A dynamic error is raised if the base-uri property is not initialized in the static context.

A dynamic error is raised if $relative is not a valid IRI according to the rules of RFC3987, extended with an implementation-defined subset of the extensions permitted in LEIRI, or if it is not a suitable relative reference to use as input to the RFC3986 resolution algorithm extended to handle additional unreserved characters.

A dynamic error is raised if $base is not a valid IRI according to the rules of RFC3987, extended with an implementation-defined subset of the extensions permitted in LEIRI, or if it is not a suitable IRI to use as input to the chosen resolution algorithm (for example, if it is a relative IRI reference, if it is a non-hierarchic URI, or if it contains a fragment identifier).

A dynamic error is raised if the chosen resolution algorithm fails for any other reason.

Notes

Resolving a URI does not dereference it. This is merely a syntactic operation on two strings.

The algorithms in the cited RFCs include some variations that are optional or recommended rather than mandatory; they also describe some common practices that are not recommended, but which are permitted for backwards compatibility. Where the cited RFCs permit variations in behavior, so does this specification.

Throughout this family of specifications, the phrase "resolving a relative URI (or IRI) reference" should be understood as using the rules of this function, unless otherwise stated.

RFC3986 defines an algorithm for resolving relative references in the context of the URI syntax defined in that RFC. RFC3987 describes a modification to that algorithm to make it applicable to IRIs (specifically: additional characters permitted in an IRI are handled the same way that RFC3986 handles unreserved characters). The LEIRI specification does not explicitly define a resolution algorithm, but suggests that it should not be done by converting the LEIRI to a URI, and should not involve percent-encoding. This specification fills this gap by defining resolution for LEIRIs in the same way that RFC3987 defines resolution for IRIs, that is by specifying that additional characters are handled as unreserved characters.