XProc 3.0: XQuery

Editor's Draft

This Version:
https://xproc.github.io/3.0-specification/revert-362-fix-361/head/xquery/
Latest Version:
http://spec.xproc.org/master/head/xquery/
Editors:
Achim Berndzen
Gerrit Imsieke
Erik Siegel
Norman Walsh
Repository:
This specification on GitHub
Report an issue
Changes:
Commits for this specification

This document is also available in these non-normative formats: XML.


Abstract

This specification describes the p:xquery step for XProc 3.0: An XML Pipeline Language.

Status of this Document

This document is an editor's draft that has no official standing.

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

This document is derived from XProc: An XML Pipeline Language published by the W3C.


1 Introduction

This specification describes the p:xquery XProc step. A machine-readable description of these steps may be found in steps.xpl.

Familarity with the general nature of [XProc 3.0] steps is assumed; for background details, see [XProc 3.0 Steps].

2 p:xquery

The p:xquery step applies an [XQuery 1.0] query to the sequence of documents provided on the source port.

<p:declare-step type="p:xquery">
     <p:input port="source" content-types="application/xml text/xml */*+xml" sequence="true" primary="true"/>
     <p:input port="query" content-types="application/xml */*+xml text/*"/>
     <p:output port="result" sequence="true" content-types="*/*"/>
     <p:option name="parameters" as="map(xs:QName,item())"/>       
     <p:option name="version" as="xs:string"/>                     
</p:declare-step>

If a sequence of documents is provided on the source port, the first document is used as the initial context item. The whole sequence is also the default collection. If no documents are provided on the source port, the initial context item is undefined and the default collection is empty.

The query port must receive a single document:

  • If the document root element is c:query, the text descendants of this element are considered the query.

    <c:query>
        string
    </c:query>

  • If the document root element is in the XQueryX namespace, the document is treated as an XQueryX-encoded query. Support for XQueryX is implementation-defined.

  • If the query document has an XML media type, then the string value of the document must be treated as the query. If the media type has a “text” type, then it must be interpreted as the query.

  • Otherwise, the interpretation of the query is implementation-defined.

If the step specifies a version, then that version of XQuery must be used to process the transformation. It is a dynamic error (err:XC0038) if the specified version is not available. If the step does not specify a version, the implementation may use any version it has available and may use any means to determine what version to use, including, but not limited to, examining the version of the query.

The result of the p:xquery step must be a sequence of documents. It is a dynamic error (err:XC0057) if the sequence that results from evaluating the XQuery contains items other than documents and elements. Any elements that appear in the result sequence will be treated as documents with the element as their document element.

For example:


<c:query>
declare namespace atom="http://www.w3.org/2005/Atom";
/atom:feed/atom:entry
</c:query>

The output of this step may include PSVI annotations.

The static context of the XQuery processor is augmented in the following way:

Statically known default collection type

document()*

Statically known namespaces:

Unchanged from the implementation defaults. No namespace declarations in the XProc pipeline are automatically exposed in the static context.

The dynamic context of the XQuery processor is augmented in the following way:

Context item

The first document that appears on the source port.

Context position

1

Context size

1

Variable values

Any parameters passed in the parameters option augment any implementation-defined variable bindings known to the XQuery processor.

Function implementations

The function implementations provided by the XQuery processor.

Current dateTime

The point in time returned as the current dateTime is implementation-defined.

Implicit timezone

The implicit timezone is implementation-defined.

Available documents

The set of available documents (those that may be retrieved with a URI) is implementation-dependent.

Available collections

The set of available collections is implementation-dependent.

Default collection

The sequence of documents provided on the source port.

2.1 Example

The following pipeline applies XInclude processing and schema validation before using XQuery:

Example 1. A Sample Pipeline Document
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
                version="3.0">
<p:input port="source"/>
<p:output port="result"/>

<p:xinclude/>

<p:validate-with-xml-schema name="validate">
  <p:with-input port="schema" href="http://example.com/path/to/schema.xsd"/>
</p:validate-with-xml-schema>

<p:xquery>
   <p:with-input port="query" href="countp.xq"/>
</p:xquery>

</p:declare-step>

Where countp.xq might contain:

<count>{count(.//p)}</count>

2.2 Document properties

No document properties are preserved.

3 Step Errors

This step can raise dynamic errors.

[Definition: A dynamic error is one which occurs while a pipeline is being evaluated.] Examples of dynamic errors include references to URIs that cannot be resolved, steps which fail, and pipelines that exhaust the capacity of an implementation (such as memory or disk space). For a more complete discussion of dynamic errors, see Dynamic Errors in XProc 3.0: An XML Pipeline Language.

If a step fails due to a dynamic error, failure propagates upwards until either a p:try is encountered or the entire pipeline fails. In other words, outside of a p:try, step failure causes the entire pipeline to fail.

The following errors can be raised by this step:

err:XC0038

It is a dynamic error if the specified version is not available.

See: p:xquery

err:XC0057

It is a dynamic error if the sequence that results from evaluating the XQuery contains items other than documents and elements.

See: p:xquery

A Conformance

Conformant processors must implement all of the features described in this specification except those that are explicitly identified as optional.

Some aspects of processor behavior are not completely specified; those features are either implementation-dependent or implementation-defined.

[Definition: An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.]

[Definition: An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.]

A.1 Implementation-defined features

The following features are implementation-defined:

  1. Support for XQueryX is implementation-defined. See Section 2, “p:xquery”.
  2. Otherwise, the interpretation of the query is implementation-defined. See Section 2, “p:xquery”.
  3. The point in time returned as the current dateTime is implementation-defined. See Section 2, “p:xquery”.
  4. The implicit timezone is implementation-defined. See Section 2, “p:xquery”.

A.2 Implementation-dependent features

The following features are implementation-dependent:

  1. The set of available documents (those that may be retrieved with a URI) is implementation-dependent. See Section 2, “p:xquery”.
  2. The set of available collections is implementation-dependent. See Section 2, “p:xquery”.

B References

[XProc 3.0] XProc 3.0: An XML Pipeline Language. Achim Berndzen, Gerrit Imsieke, Erik Siegel and Norman Walsh, editors.

[XProc 3.0 Steps] XProc 3.0 Steps: An Introduction. Achim Berndzen, Gerrit Imsieke, Erik Siegel and Norman Walsh, editors.

[XQuery 1.0] XQuery 1.0: An XML Query Language. Scott Boag, Don Chamberlin, Mary Fernández, et. al., editors. W3C Recommendation. 23 January 2007.

C Glossary

dynamic error

A dynamic error is one which occurs while a pipeline is being evaluated.

implementation-defined

An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.

implementation-dependent

An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.