A WebDAV Search Grammar for XML Properties
draft-godoy-webdav-xmlsearch-00

Status of This Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on July 16, 2008.

Abstract

This document specifies XS:xml-search, a search grammar for use with the Web Distributed Authoring and Versioning (WebDAV) SEARCH protocol. XS:xml-search extends the DAV:basicsearch grammar with XPath expressions which are evaluated on properties whose values are XML fragments.

The full expression power of XPath may exceed the requirement in simple use cases, therefore some provisions are made in order to reduce the cost of implementing this specification, as well as the computational cost of evaluating allowed queries.

Table of Contents

1.  Introduction
    1.1.  Notational conventions
    1.2.  Terms
    1.3.  Overview
    1.4.  XS:xml-search and the PROPFIND response
2.  XPath
    2.1.  Static and Dynamic Contexts
    2.2.  Error and warnings
        2.2.1.  Warnings
        2.2.2.  Errors (in SAP)
        2.2.3.  Errors (in DEP)
    2.3.  Numeric Predicates
3.  Discovery of the Query Grammar
    3.1.  The DASL Response Header
    3.2.  DAV:supported-query-grammar-set
    3.3.  Discovery of the XS:xml-search Query Schema
4.  The XS:xml-search Grammar
    4.1.  Accepted Role Precondition
    4.2.  Selection
    4.3.  Query criteria
        4.3.1.  DAV:prop operand
        4.3.2.  Literal Operands
        4.3.3.  Relational operators
        4.3.4.  The XS:filter operator
        4.3.5.  The XS:is-well-formed operator
    4.4.  Ordering
    4.5.  SEARCH Status Codes for responses to XS:xml-search queries
    4.6.  Status Codes for Use in 'response' Elements
    4.7.  Status Codes for Use in 'propstat' Elements
    4.8.  Precondition and postcondition Codes
        4.8.1.  XS:property-must-be-well-formed-xml
        4.8.2.  XS:acceptable-role
        4.8.3.  XS:XPath-error
        4.8.4.  DAV:search-scope-valid
        4.8.5.  XS:known-literal-type
5.  Query Schema for XS:xml-search
    5.1.  Property descriptions
    5.2.  Operator descriptions
        5.2.1.  XS:opdesc-rule and XS:operator
        5.2.2.  XS:repetition
        5.2.3.  XS:alternative
        5.2.4.  Implied operator description
        5.2.5.  Extended operator description for DAV:typed-literal Operand
6.  XML Extensibility
7.  Security Considerations
8.  IANA Considerations
9.  References
    9.1.  Normative References
    9.2.  Informative References
Appendix A.  Example XS:xml-search query
§  Index

1.  Introduction

This document specifies XS:xml-search, an OPTIONAL search grammar for use with the Web Distributed Authoring and Versioning (WebDAV) SEARCH protocol. The search grammar defined by this document is a superset of DAV:basicsearch [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.).

The intent of this document is to extend the DAV:basicsearch grammar for dealing with properties whose values are XML fragments. Since the WebDAV property namespace is flat, and resources may have at most one value for a property of a given name (Section 9.1 of [RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.)), XML documents allowing repeatable elements cannot be expressed as a set of independent WebDAV properties (i.e by mapping some elements to properties), and the DAV:basicsearch schema cannot be applied to such XML content because it deals with property values as a whole. [note-intent] (The authors' motivation for writing this specification is allowing metadata to be searchable when presented as a WebDAV property. Since it may be encoded as specified by a third-party schema, it should not be modified in order to conform WebDAV.)

XS:xml-search is proposed as a different search grammar because it defines a new element (namely XS:filter) that modify the query semantics. Had this been an extension of DAV:basicsearch, a server would have ignored the XS:filter elements (according to Section 17 of [RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.)) yielding results different from those requested by the client. [note-RFC4918-sect17] (RFC4918: "(...) servers MUST process received XML documents as if unexpected elements and attributes (and all children of unrecognized elements) were not there")

1.1.  Notational conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

This specification defines elements in the urn:ietf:params:xml:ns:webdav-xml-search XML namespace. (hereinafter referred to as the "XS namespace", though the prefix binding "XS:" is not normative). In natural language, an element like "xml-search" in this namespace is sometimes referred to as "XS:xml-search" (without quotes). [note-namespace] (Since this protocol is experimental, the authors do not suggest new elements in order to not pollute the "DAV:" namespace. Thus, an experimental implementation of this protocol will not conflict with the following requirement from RFC 4918: "(...) an XML element in the "DAV:" namespace SHOULD NOT be used in the request or response body unless that XML element is explicitly defined in an IETF RFC reviewed by a WebDAV working group.").

In element definitions, an element name prefixed with "XS:" refers to an element in the XS namespace, and un-prefixed element names refers to elements in the "DAV:" namespace.

The DTD fragments are normative up to extensibility rules defined in Section 6 (XML Extensibility). Unless noted otherwise, ordering of declared content is not significative.

Note: when an error condition is described, it is said that "the server MUST return" some indication of that error. Unless stated otherwise, if several errors occurs at the same time, any of them MAY be reported and any of them MAY be omitted as long as one of them is reported.

1.2.  Terms

This document uses the terms defined in [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.), [RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.), [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.) and this section. Some definitions of frequently used terms from [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.) are informatively included here.

Dynamic Context: (of an XPath expression) "the dynamic context of an expression is defined as information that is available at the time the expression is evaluated." (Section 2.1.2, [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.))

Dynamic Evaluation Phase (DEP): "The dynamic evaluation phase is the phase during which the value of an expression is computed. It occurs after completion of the static analysis phase." (Section 2.3.3.2, [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.))

Dynamic Error: "A dynamic error is an error that must be detected during the dynamic evaluation phase and may be detected during the static analysis phase. Numeric overflow is an example of a dynamic error." (Section 2.3.1, [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.))

Implementation-defined: "indicates an aspect that MAY differ between implementations, but MUST be specified by the implementor for each particular implementation." (Section 1, [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.))

Implementation-dependent: "indicates an aspect that MAY differ between implementations, is not specified by [this or any other] specification, and is not required to be specified by the implementor for any particular implementation." (Section 1, [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.))

Role: a context within XS:xml-search where the DAV:prop element is expected. A role is "plain" if the DAV:prop element occurs as a direct child of DAV:select, DAV:where, or DAV:order, and it is "filtered" (also referred as XPath-enabled) if the DAV:prop element occurs as a direct child of XS:XPath.

Static Analysis Phase (SAP): "The static analysis phase depends on the expression itself and on the static context. The static analysis phase does not depend on input data (other than schemas)." (Section 2.3.3.1, [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.))

Static Context: (of an XPath expression) "the static context of an expression is the information that is available during static analysis of the expression, prior to its evaluation." (Section 2.1.1, [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.))

Static Error: "A static error is an error that MUST be detected during the static analysis phase. A syntax error is an example of a static error." (Section 2.3.1, [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.))

Type Error: "A type error may be raised during the static analysis phase or the dynamic evaluation phase. During the static analysis phase, a type error occurs when the static type of an expression does not match the expected type of the context in which the expression occurs. During the dynamic evaluation phase, a type error occurs when the dynamic type of a value does not match the expected type of the context in which the value occurs." (Section 2.3.1, [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.))

1.3.  Overview

Section 1.4 (XS:xml-search and the PROPFIND response) summarizes how this query grammar matches the PROPFIND response, according to the requirement imposed by Section 2.3.2 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.).

Section 2 (XPath) describes XS:xml-search as an XPath host language, i.e., a language where XPath expressions are embedded. Some items from the XPath specification are defined in that section, while other are left to the criteria of the implementors. This section also includes design decisions in order to reduce the implementation cost of this specification, as well as the computational cost of allowed queries.

Section 3 (Discovery of the Query Grammar) describes how this grammar is advertised, according to the mechanisms for discovery of supported query grammars, defined in Section 3 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.). This include the Allow and DASL headers in OPTIONS responses (Section 3.1 (The DASL Response Header)), the DAV:supported-query-grammar-set property (Section 3.2 (DAV:supported-query-grammar-set)) and Query Schema Discovery (Section 3.3 (Discovery of the XS:xml-search Query Schema) and Section 5 (Query Schema for XS:xml-search)).

Section 4 (The XS:xml-search Grammar) describes the grammar of a XS:xml-search query. This includes extending the specification of selection (Section 4.2 (Selection)) query criteria (Section 4.3 (Query criteria)) and ordering (Section 4.4 (Ordering)) with respect to DAV:basicsearch. Additionally, some status (Section 4.5 (SEARCH Status Codes for responses to XS:xml-search queries) to Section 4.7 (Status Codes for Use in 'propstat' Elements)) and precondition/postcondition codes (Section 4.8 (Precondition and postcondition Codes)) are defined.

Section 5 (Query Schema for XS:xml-search) describes the Query Schema for advertising supported features about properties (Section 5.1 (Property descriptions)) and operators (Section 5.2 (Operator descriptions)) available in a XS:xml-search query.

Section 6 (XML Extensibility) describes the specified behaviour when unexpected elements are found, providing a common ground for allowing clients that implement arbitrary extensions to interoperate with other implementations which does not include it.

1.4.  XS:xml-search and the PROPFIND response

A XS:xml-search response describes a subset of the elements which are described by a PROPFIND response that lists the same properties on the same scope and with the same depth. If a server supports specifying several scopes in a single query, and these scopes exist, then the XS:xml-search response will describe a subset of the elements in several PROPFIND responses (one PROPFIND for each scope).

The properties included in a XS:xml-search response are those specified within the DAV:select element of the request. In that context, DAV:allprop and DAV:prop are understood as in PROPFIND, hence both methods returns the same properties. In addition, XS:xml-search introduce a new way for selecting properties: XS:filter, which "filters" elements from some property value according to an XPath expression. If XS:filter is used, the XS:xml-search response will contain a subset of elements from the filtered property, while the PROPFIND response will contain the complete value.

Queries may impose conditions about which or how many resources will be included in the response, and servers may truncate the response at their choice. Thus, a SEARCH response may not include some resources from the specified scope, while all of them have to be included when using PROPFIND.

Furthermore, XS:xml-search defines additional preconditions and postconditions codes that are not used with a PROPFIND response.

2.  XPath

There are several items in XPath that are implementation-defined. Some of them are defined in this section (as this protocol specifies an XPath host language) while other are left to the criteria of the implementors.

* Some components of the static and dynamic contexts are constrained (Section 2.1 (Static and Dynamic Contexts)).

* A way for reporting errors and warnings is specified (Section 2.2 (Error and warnings)).

* In some expressions, supporting numeric predicates is OPTIONAL (section Section 2.3 (Numeric Predicates)).

* Implementations of this protocol MUST be based on the rules of [W3C.REC‑xml11‑20060816] (Maler, E., Sperberg-McQueen, C., Cowan, J., Paoli, J., Bray, T., and F. Yergeau, “Extensible Markup Language (XML) 1.1 (Second Edition),” August 2006.) and [W3C.REC‑xml‑names11‑20060816] (Hollander, D., Layman, A., Tobin, R., and T. Bray, “Namespaces in XML 1.1 (Second Edition),” August 2006.), and apply them consistently.

* The self, child, and attribute axes MUST be supported. An implementation MAY support other axes, as described in the query schema. (Note: the abbreviated steps ".." and "//" are not supported, unless the parent and descendant-or-self axes respectively are supported.)

* Support for the "Static Typing Feature" and "Static Typing Extensions" (Appendix F.1 of [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.)) is implementation-defined.

2.1.  Static and Dynamic Contexts

This specification defines REQUIRED values for some components of the XPath static and dynamic context. Unless specified otherwise, the constant values specified below MUST NOT be overwritten. Components not listed here are "implementation-dependent".

Evaluation of an expression that relies on one or more "unassigned" components raises the static error err:XPST0001 (if the component is static) or the dynamic error err:XPDY0002 (if the component is dynamic).

REQUIRED static values

REQUIRED dynamic values

2.2.  Error and warnings

This section describes the method by which XPath errors and warnings are reported. Error conditions are defined in [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.), and warning conditions are OPTIONAL and implementation-defined.

For conformance with [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.), implementations MAY report any non-empty subset of errors. Additionally, if there is an error (other than a XPath error) that causes the request to be rejected, implementations MAY report the latter, with no mention to the XPath errors.

The idref attributes of XS:xpath-error and XS:warning MAY be used to refer to the id attribute of the XS:xpath element whose content raised the error or warning. The mechanism that implementations use to return additional information is implementation-defined.

2.2.1.  Warnings

The XS:warning element contains at least one XML element, and MUST NOT contain text or mixed content. Children of the XS:warning element represent warnings signaled during the analysis of the expression.

<!ELEMENT XS:warning ANY>
<!ATTLIST XS:warning idref NAME #IMPLIED>

The DAV:multistatus and DAV:response elements, when used in response to XS:xml-search queries, are modified to include an OPTIONAL XS:warning element. Warnings raised during SAP apply to the whole query and are reported within the XS:warning element contained by DAV:multistatus. Warnings raised during DEP only apply to a particular resource and are reported within the DAV:response for that resource.

<!ELEMENT multistatus (response*, responsedescription?,
                       XS:warning?) >

<!ELEMENT response (href, ((href*, status)|(propstat+)),
                    error?, XS:warning?,
                    responsedescription?, score?)

2.2.2.  Errors (in SAP)

Errors (either static, dynamic or type errors) detected during SAP invalidates the request. These kind of errors are reported through a XS:xpath-error element included in a response whose root element is DAV:error. The response status code is 400 (Bad Request).

<!ELEMENT XS:xpath-error ANY>
<!ATTLIST XS:xpath-error idref NAME #IMPLIED>

The XS:xpath-error element MUST contain one or more elements describing the error. For instance, if an err:XPST0003 were raised (i.e. the XPath static error 0003: "a XPath expression is not a valid instance of the grammar") the response would be:

HTTP/1.1 400 Bad Request
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx

<error xmlns="DAV:">
  <XS:XPath-error
      xmlns:XS="urn:ietf:params:xml:ns:webdav-xml-search">
    <err:XPST0003 xmlns:err="http://www.w3.org/2005/xqt-errors"/>
  </XS:XPath-error>
</error>

(Note: the use of the "err:" prefix follows the convention of [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.) but it is not normative.)

2.2.3.  Errors (in DEP)

An expression may be statically valid and raise an error under some dynamic conditions. Dynamic and type errors detected during DEP only invalidates the expression which raises them, when evaluated with the actual values of some resource property.

A server MAY ignore errors detected in DEP if:
   -The error occurs within DAV:order, but that ordering criteria is not used (because other orders take precedence, or because the query matches one or no resource).
   -The error occurs within DAV:where part, and it does not affect the result. For instance, the error in (FALSE AND ERROR) may be omitted because the result would have been FALSE anyway, and the error in (TRUE OR ERROR) may be omitted because the result would have been TRUE anyway.

If the error is not ignored, and the XPath expression was specified within the DAV:select part, it MAY be reported in the DAV:propstat element for the current property and resource. Otherwise it MAY be reported in the DAV:response element for the current resource. In both cases the status code 409 (Conflict) MUST be used.

Although errors in DEP depend on the value of the property, an error that is too frequent might have been caused by mistakes in the client's request.="I-D.reschke-webdav-search" pageno="false" formaV:response elements, all of which represent failures because of the same error, a server MAY report an error in DEP as a general failure invalidating the query itself, even if it is possible to evaluate other resources and properties. [error-DEP] (Besides, handling dynamic errors on a separate basis imposes an additional requirement, then supporting this feature is left to the criteria of implementors.)

When an error raised in DEP is reported as a general failure, the response will be marshaled as in Section 2.2.2 (Errors (in SAP)), but the response status code MUST be 409 (Conflict) instead of 400 (Bad Request).

For instance, if err:XPTY0004 were raised during DEP ("the dynamic type of a value does not match a required type"), the response would be:

HTTP/1.1 409 Conflict
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx

<error xmlns="DAV:">
  <XS:XPath-error
      xmlns:XS="urn:ietf:params:xml:ns:webdav-xml-search">
    <err:XPTY0004 xmlns:err="http://www.w3.org/2005/xqt-errors"/>
  </XS:XPath-error>
</error>

the dynamic type of a value does not match a required type

2.3.  Numeric Predicates

"A step is a part of a path expression that generates a sequence of items and then filters the sequence by zero or more predicates." (Section 3.2.1 of [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.)). A step expression may be either a FilterExpr or an AxisExpr.

"A predicate consists of an expression, called a predicate expression, enclosed in square brackets. A predicate serves to filter a sequence, retaining some items and discarding others." (Section 3.2.2 of [W3C.PR‑xpath20‑20061121] (Berglund, A., Boag, S., Chamberlin, D., Fernández, M., Kay, M., Robie, J., and J. Siméon, “XML Path Language (XPath) 2.0,” November 2006.))

Support for numeric predicates and other references to the context position -e.g. by evaluating the fn:position() function- depends on the sequence where the predicate applies.

Supporting numeric predicates in FilterExpr is OPTIONAL. If the step expression is an AxisStep, the requirement level depends on the specified axis. It is:

* NOT RECOMMENDED for the namespace and attribute axes, because the relative order of elements within these axes is implementation-dependent.
* Always REQUIRED for the parent, self, and ancestor axes.
* For the child, preceding-sibling and following-sibling axes: RECOMMENDED if the sequence order is semantically meaningful, OPTIONAL otherwise.
* Always OPTIONAL for the descendant, descendant-or-self, ancestor-or-self, preceding, and following axes.
[note-context-position] (When supporting numeric predicates and context position references there is a trade-off between expressive power and implementation costs.)

The way this feature is supported when it is not REQUIRED is implementation-dependent.

3.  Discovery of the Query Grammar

If a resource supports the SEARCH method, then the server MUST list SEARCH in the Allow header, as described in Section 3.1 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.).

3.1.  The DASL Response Header

The DASL response header indicates server support for a query grammar in the OPTIONS method. (Section 3.2 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.)) The value of this header is a URI that indicates the type of grammar supported. Servers MUST return the following header when the OPTIONS method is invoked on any arbiter that supports the XS:xml-search grammar:

   DASL:<urn:ietf:params:xml:ns:webdav-xml-search>

3.2.  DAV:supported-query-grammar-set

The WebDAV property DAV:supported-query-grammar-set is REQUIRED for any server supporting either [RFC3253] (Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. Whitehead, “Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning),” March 2002.) and/or [RFC3744] (Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, “Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol,” May 2004.) and identifies the XML based query grammars that are supported by the search arbiter resource (Section 3.3 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.)). Servers implementing DAV:supported-query-grammar-set MUST report the following grammar for each arbiter resource supporting XS:xml-search:

<DAV:grammar xmlns:DAV="DAV:">
  <XS:xml-search
    xmlns:XS="urn:ietf:params:xml:ns:webdav-xml-search"/>
</DAV:grammar>

3.3.  Discovery of the XS:xml-search Query Schema

Query Schema Discovery (QSD) is requested by means of the SEARCH method, including an entity with a DAV:query-schema-discovery root element. As specified in Section 4.1 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.), the response body takes the form of a DAV:multistatus element (Section 13 of [RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.)), where DAV:response is extended to hold the returned query grammar inside a DAV:query-schema container element.

If the DAV:query-schema-discovery element contains XS:xml-search, then the response marshaling MUST be performed as described in this section and Section 5 (Query Schema for XS:xml-search).

Since the supported query grammars may depend on the scope, the XS:xml-search element (when used for QSD) MAY contain a DAV:from element. Other content is unexpected in this context.

If several scopes are specified and the server supports multiple scopes, then the response MUST only contain those descriptions that are common to each scope.

Request:

SEARCH / HTTP/1.1
Host: host.example
Content-Type: application/xml
Content-Length: xxx

<query-schema-discovery xmlns="DAV:">
  <XS:xml-search
    xmlns:XS="urn:ietf:params:xml:ns:webdav-xml-search"/>
</query-schema-discovery>

Response:

HTTP/1.1 207 Multistatus
Content-Type: application/xml
Content-Length: xxx

<multistatus xmlns="DAV:">
  <response>
    <href>http://host.example</href>
    <status>HTTP/1.1 200 OK</status>
    <query-schema>
      <XS:xml-search-schema
        xmlns:XS="urn:ietf:params:xml:ns:webdav-xml-search"/>
        <!-- (See Section 5 for the actual contents) -->
      </XS:xml-search-schema>
    </query-schema>
  </response>
</multistatus>

4.  The XS:xml-search Grammar

The elements used in XS:xml-search conform the semantics given in [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.):A=" the DAV:basicsearch grammar, and all the operators defined in Section 5 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.) (i.e. %all_ops;) are valid in the context of a XS:xml-search query. Additionally, some elements in the "DAV:" namespace are allowed to contain specific elements from the XS:xml-search grammar.

Therefore, the semantics of a DAV:basicsearch valid query is preserved when the DAV:basicsearch content is submitted as a XS:xml-search query.

This grammar also allows the additional element XS:filter as well as optional implementation-defined operators. The XS:filter element specifies an XPath expression (rooted on a single property, i.e. the root element is the property whose name is included in the DAV:prop element). It is both a query-operator and a special construct valid within DAV:select and DAV:order elements.

<!-- "XS:xml-search" element -->
<!ELEMENT XS:xml-search (select?, from, where?, orderby?, limit?) >

<!-- "DAV:select" element -->
<!ELEMENT select     ( (allprop | prop | XS:filter)+ )>
<!ELEMENT XS:filter  (prop, XS:XPath)>
<!ELEMENT XS:XPath    #PCDATA >

<!-- "DAV:where" element -->
<!ENTITY % ext_ops "XS:filter | XS:is-well-formed" >
<!ELEMENT where       (  %all_ops;|%ext_ops;)      >

<!ELEMENT not         (  %all_ops;|%ext_ops;   )   >
<!ELEMENT and         ( (%all_ops;|%ext_ops;)+ )   >
<!ELEMENT or          ( (%all_ops;|%ext_ops;)+ )   >

<!ELEMENT XS:is-well-formed ( prop )               >

<!-- "DAV:order" element for XS:xml-search-->

<!ELEMENT order      ((prop | score | XS:filter),
                      (ascending | descending)?)

4.1.  Accepted Role Precondition

If the XS:xml-search request includes a property with a role which is not acceptable (e.g. the request specifies a filtered selection of a property which is not XPath-enabled or it specifies ordering by a non-sortable property), the server MUST reply with a 422 (Unprocessable Entity) status code. The response's DAV:error element MUST contain at least one XS:acceptable-role preconditions (Section 4.8 (Precondition and postcondition Codes)) describing the failure for each rejected property.

If the request is not accepted because of a XS:acceptable-role precondition, the server SHOULD report all the failures, so that if the client removes the conflicting properties then the modified query will succeed this test.

If a property violates the preconditions for a role in both plain and filtered forms, then the filtered form MAY be omitted in the error response. (This rule does not applies for DAV:selectable since a property may not be specified for both plain and filtered selection in the same request).

Rejections because of several reasons (e.g. because a property is neither DAV:searchable nor DAV:selectable) MAY be reported by means of a single XS:acceptable-role element. The DAV:prop element within XS:acceptable-role must contain a single property element.

If QSD is supported, a property used in a role described in the QSD response for the search scopes MUST NOT be rejected.

When a XS:filter element refers to a live property that is known not to be well-formed XML (because the XML syntax is not enforced for that property), the server SHOULD reject the request as described in this section, instead of accepting the query and reporting a 409 (Conflict) for each occurrence. (This implies that, if such property is mentioned in the QSD, its description SHOULD NOT include any XPath-enabled role.)

4.2.  Selection

DAV:select defines the result record, which is a set of properties and values (Section 5.3 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.)). The allowed children are DAV:allprop and DAV:prop (defined in Section 14 of [RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.)) and XS:filter (defined in this document).

If the DAV:select element is omitted, the successful response MUST only contain the URIs of matched resources in one or more DAV:response elements with status code 204 (No content). The response root element is DAV:multistatus. If an error occurs, it MUST be reported as described for the non-empty case.

The rest of this section describes the handling of non-empty DAV:select elements

For each resource matching the query criteria and scope, the results from all the XS:filter selection-elements (i.e all the XS:filter elements included within a DAV:select element) referred to the same property MUST be returned into a single property of the DAV:response. Because of filtering, the response is not required to be valid even if the selected property contains an XML document that is valid according to some DTD or XML schema.

For each resource matching the query criteria and scope, and for each property selected through XS:filter:

- When the actual property value does not contain a well-formed XML fragment, a DAV:propstat with 409 (Conflict) code and postcondition code XS:property-must-be-well-formed-xml MUST be returned for that resource and property (since the query semantics is not appropriate for the actual property value).

- If the actual property value contains a well-formed XML fragment, the matched elements are aggregated into the XML fragment for that property and resource.

- If no elements are matched for that property and resource, it will be reported as an empty element.

If a property does not exist, the server MUST either omit the selected property from that resource record-set or return it within a 404 (Not Found) status code DAV:propstat.[note-OPTIONAL-404] (The 404 status code for missing properties is OPTIONAL in order to avoid an extensive response if the client selects several properties that are seldom defined. Note this behaviour is different from the PROPFIND case, where the 404 status code is REQUIRED for missing properties (Section 9.1 of [RFC 4918], page 35).)

A client MUST NOT request both the plain property value and the filtered one, since it is ambiguous (or, in the best case, redundant) [note-select-prop-filter] (If the property value is not well-formed XML specifying both DAV:prop and XS:filter is ambiguous because a 409 (Conflict) status code must be returned per XS:filter and the complete property value must be returned per DAV:prop. On the other hand, if the property value were well-formed XML, one of those elements would have to be ignored.). Hence, if DAV:select contains one or more XS:filter elements referring a property that is also selected via a plain DAV:prop element, the server MUST return a 400 (Bad Request) response.

For instance, the following DAV:select element causes a 400 response:

<select xmlns="DAV:">
   <filter>
    <prop xmlns:A="http://a.example/"/>
      <A:property/>
    </prop>
    <XPath>//foo</XPath>
  </filter>
  <prop xmlns:A="http://a.example/"/>
      <A:property/>
  </prop>
</select>

If DAV:allprop is specified, it is understood as in a PROPFIND request [RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.): (i.e., properties defined in RFC 4918, at a minimum, plus dead properties MUST be returned). Hence, the set of properties selected by allprop vary from resource to resource.

If the request includes not only DAV:allprop but also one or more DAV:prop elements specifying properties which are already returned per DAV:allprop, or the request includes a property twice in DAV:prop elements, then the redundant properties MUST be ignored (i.e. a single property value will be returned). This behaviour is similar to that of the DAV:include element in a PROPFIND request (but DAV:include is not defined for XS:xml-search requests).

There is no error when a property that would be returned per DAV:allprop is also specified within a XS:filter element (since the client may not be aware of the properties that will be returned when DAV:allprop is specified). This combination MUST be addressed as follows:
    - The XS:filter elements are processed as usual. This result in properties contained in DAV:propstat; elements with status code 200, 4xx or 5xx (as appropriate).
    - Each property that would have been returned per DAV:allprop in a PROPFIND request and was not included within a XS:filter element, is selected.

4.3.  Query criteria

The DAV:where element specifies optional query criteria. Only those resources that verify the query criteria are included in the result set.

4.3.1.  DAV:prop operand

The result of the DAV:prop operand is the value of the specified property of the resource being evaluated. If the property is a live one, the result datatype SHOULD be the actual property datatype. If the property is dead, or the server chooses to ignore the live property datatype, the result MUST be of type xs:string.

Note: "A property name is a universally unique identifier that is associated with a schema that provides information about the syntax and semantics of the property." (Section 4.4 of [RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.)). Therefore, each property name SHOULD be permanently associated with at most one datatype.

4.3.2.  Literal Operands

DAV:literal and DAV:typed-literal allow literal values to be placed in an expression.

When used with the operators defined in [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.):
   - The type of a DAV:literal value MUST be the type of the other operand in the expression.
   - The type of a DAV:typed-literal value MUST be the type specified in the xsi:type attribute, or xs:string if no type was specified. The value of the other operand MUST be casted to this type.

A request with a DAV:typed-literal specifying an unknown type MUST be rejected by returning a response with status code 422 (Unprocessable Entity) and precondition code XS:known-literal-type. The xs:string type MUST NOT be unknown.

4.3.3.  Relational operators

The relational operators take a property and literal operand. XS:xml-search inherits the five relational operators defined in [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.): DAV:eq, DAV:lt, DAV:gt, DAV:lte and DAV:gte.

For each property and pair of values being compared:
   - per Section 4.2.1 of [W3C.REC‑xmlschema‑2‑20041028] (Malhotra, A. and P. Biron, “XML Schema Part 2: Datatypes Second Edition,” October 2004.) the result of DAV:eq; is always defined, then DAV:eq; MUST NOT return NULL.
   - all of DAV:lt, DAV:gt, DAV:lte and DAV:gte MUST be either undefined or consistently defined. If they are defined, they MUST also conform the result of DAV:eq (i.e., A == B iff A<=B and A>=B).

If the property type is known and it is a complex type, the result of these operations SHOULD be undefined. [note-comparison-complex-type] (This seems to be a MUST in [draft-reschke-webdav-search-14] Section 5.5.4, but is relaxed here since the property would be treated as xs:string if the type were ignored.) (Values within such properties may be compared by means of XPath predicates.)

If the property type is known and it is a simple built-in ordered type, the order relation used in the comparison SHOULD be that defined in [W3C.REC‑xmlschema‑2‑20041028] (Malhotra, A. and P. Biron, “XML Schema Part 2: Datatypes Second Edition,” October 2004.).

If the property type is known and it is a simple type, an implementation-dependent order relation MAY be used. If a partial order is used, then trying to compare two values which are not comparable yields an undefined result.

In any case, the collation algorithm is implementation-dependent.

Other operators and operands retain the behaviours defined in [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.).

4.3.4.  The XS:filter operator

When used inside a DAV:where element (or a sub-element thereof) XS:filter evaluates as:
   - TRUE if (and only if) the XPath expression matches at least one element,
   - FALSE if (and only if) no element within the property is matched,
   - NULL if (and only if) the property does not exist or its value is not a well-formed XML fragment.

4.3.5.  The XS:is-well-formed operator

The XS:is-well-formed operator takes a DAV:prop operand and returns:
   - TRUE if (and only if) the property value is a well formed XML fragment.
   - FALSE if (and only if) the property value is not a well formed XML fragment.
   - NULL if (and only if) the property does not exist.

Supporting this operator is REQUIRED for properties which are XS:searchable, and OPTIONAL for properties which are only DAV:searchable.

4.4.  Ordering

DAV:orderby specifies a lexicographical order on the set of DAV:response to be returned. Comparisons are applied as they occur in the DAV:orderby element, earlier comparisons being more significant (Section 5.6 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.)).

When used within XS:xml-search, a DAV:orderby element MUST contain one or more DAV:order elements, which are allowed to contain a DAV:prop, a DAV:score or a XS:filter elements.

When DAV:order contains a DAV:prop element, the ascending (alternatively, descending) order MUST be consistent with the comparison performed by DAV:lte (alternatively, DAV:gte):
- If A<=B (alternatively, A>=B) according to DAV:lte, then A collates before B.
- If A<=B (alternatively, A>=B) is undefined, then the collation order is implementation-dependent.

When DAV:order contains a DAV:score element, an integer comparison is performed on each DAV:score value computed for the DAV:contains operation.

When DAV:order contains a XS:filter element, result-sets will be logically partitioned in three equivalence classes, based on the evaluation of XS:filter (as defined in Section 4.3 (Query criteria)). The equivalence classes are totally ordered (in ascending order) as: NULL < false < true.

ria and the ordering criteria), the server may aing among all the responses for which the XS:filter element evaluates to the same value) is implementation-dependent. (The order specified for the item-type in the sequence returned by the xpath expression MAY be used.)

4.5.  SEARCH Status Codes for responses to XS:xml-search queries

   - 207 (Multistatus) The server accepted the request. The result set are returned within a DAV:multistatus; element.
   - 400 (Bad Request) Error in SAP, or the query includes both a plain DAV:prop and a XS:filter specifying the same property name.
   - 403 (Forbidden) The server rejected the request because the user has no privileges for performing queries under the specified arbiter resource.
   - 404 (Not found) The arbiter resource does not exist.
   - 409 (Conflict) Error in DEP (general failure) or invalid scope.
   - 422 (Unprocessable Entity)
       A property was specified in a role which is rejected for that property.
       An unknown type was specified in DAV:typed-literal.
       A required extension is not supported.

Other status codes may be returned (redirections, client errors, server errors), with the meaning defined in [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.).

The 207 status code MUST be used if and only if a result set is included in the response (an empty result set is allowed if the query does not match any resource).

If the query could not be performed because of several errors, the error which is reported is implementation-dependent.

If the client has no privileges for testing whether the arbiter exists then 403 (Forbidden) SHOULD be used instead of 404 (Not found). If the client has no privileges for accessing the specified scope then 409 (Conflict) MUST be returned

4.6.  Status Codes for Use in 'response' Elements

   - 204 (No Content) if the resource exists and no selection list was specified (i.e. the DAV:select element is empty).
   - 209 (Conflict) Error in DEP. The search was invalidated for resources identified by DAV:href elements in the response.

If a selection list was specified, the response MUST NOT contain a DAV:status element, but a DAV:propstat listing the selected properties.

If the client has no privileges for testing whether a resource exists, that resource MUST be silently omitted from the response.

5xx status codes MAY be used if a error occurs when accessing the resource.

4.7.  Status Codes for Use in 'propstat' Elements

   - 200 (OK) for each selected property, if the property exists.
   - 403 (Forbidden) if the client has no privileges for accessing the selected property.
   - 404 (Not Found) for each property selected through DAV:allprop, DAV:prop or XS:filter if the property does not exist (OPTIONAL).
   - 409 (Conflict) if a property specified in a selection XS:filter element does not contains well-formed XML. The associated postcondition MUST be XS:property-must-be-well-formed-xml.

If the client has no privileges for testing whether the property exists, the server SHOULD either omit the property or return a 404 (Not found) status code (instead of 403).

5xx status codes MAY be used if a error occurs when accessing the property value.

4.8.  Precondition and postcondition Codes

4.8.1.  XS:property-must-be-well-formed-xml

Type: postcondition

Use with: /multistatus/response/propstat/error, 409 Conflict

Purpose: the actual property value does not contain a well-formed XML fragment, and the property was specified in a XS:filter element.

<!ELEMENT XS:property-must-be-well-formed-xml EMPTY>

4.8.2.  XS:acceptable-role

Type: precondition

Use with: /error, 422 Unprocessable Entity

Purpose: the XS:xml-search request includes a property for a role where it is not acceptable.

<!ELEMENT XS:acceptable-role (prop, searchable?,
                              selectable?, sortable?)>

4.8.3.  XS:XPath-error

Type: precondition/postcondition

Use with:
   /error, 400 Bad Request (precondition)
   /error, 409 Conflict (precondition)
   /multistatus/response/error, 409 Conflict (postcondition)
   /multistatus/response/propstat/error, 409 Conflict (postcondition)

Purpose: The query includes an XPath expression that raises an error.

(see Section 2.2 (Error and warnings).)

4.8.4.  DAV:search-scope-valid

Type: precondition

Use with: /error, 409 Conflict

Defined in [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.)

4.8.5.  XS:known-literal-type

Type: precondition

Use with: /error, 422 Unprocessable Entity

Purpose: The query includes a DAV:typed-literal which specifies an unknown data-type. The data-type name is included into the element content.

<!ELEMENT XS:known-literal-type #PCDATA>

5.  Query Schema for XS:xml-search

The query schema provides information about the set of available properties and implemented operators.

The query schema is marshaled within a XS:xml-search-schema element. This element contains an unordered set of property descriptions (DAV:propdesc) and operator description rules (XS:opdesc-rule).

<!ELEMENT XS:xml-search-schema  (propdesc|XS:opdesc-rule)* ) >

5.1.  Property descriptions

The semantics of DAV:propdesc, when used within a XS:xml-search-schema is extended for describing whether a property may be used as root element of a XPath expression within a XS:filter element.

Since XS:filter may appear in three different places (the record-set definition, the query criteria and the ordering criteria), the server may allow or disallow it on a separate basis. If XS:selectable, XS:searchable or XS:sortable is present, then the server MUST allow this property to be used within a XS:filter element in the applicable context (role)

<!ELEMENT propdesc           (prop|any-other-property), datatype?,
                             (searchable | XS:searchable)?,
                             (selectable | XS:selectable)?,
                             (sortable   | XS:sortable?),
                              caseless?,   XS:axis* >


<!ELEMENT XS:selectable       EMPTY >
<!ELEMENT XS:searchable       EMPTY >
<!ELEMENT XS:sortable         EMPTY >

<!ELEMENT XS:axis EMPTY>
<!ATTLIST XS:axis name (namespace | parent  | ancestor
                  | preceding-sibling  | following-sibling
                  | descendant-or-self | ancestor-or-self
                  | preceding | following) #REQUIRED>

Properties which are XS:selectable or XS:searchable are also DAV:selectable or DAV:searchable respectively. For instance, if a property may be selected through a XPath expression then it is plainly selectable, and if a property may be used within a XS:filter query criterion then it may be used as an operand of DAV:is-defined, DAV:is-well-formed.

Properties which are XS:sortable are not DAV:sortable, because comparison of complex types is undefined. Properties MUST NOT be DAV:sortable and XS:sortable at the same time.

The server MUST allow described properties to be used in the role for which they were advertised. This hint does not assert whether the property is defined on every resource in the scope, and does not assert whether the property value is well-formed XML.

There SHOULD be one description for DAV:any-other-property. There MUST NOT be more than one description for each property, and one description for DAV:any-other-property.

The "name" attribute of the XS:axis element specifies the name of an optional axis which is supported for the property being described.

5.2.  Operator descriptions

Operators are described in a way that borrows some elements from ABNF [RFC4234] (Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” October 2005.) (namely repetitions and alternatives). This approach allows a flexible and compact description of operators. [note-opdesc] (The operator description is only intended for discovering whether the server implements an extension operator. The DAV:operators element from [I-D.reschke-webdav-search] is not adopted here, because it cannot describe the mandatory operators. On the other hand, while XML Schemas would have sufficed for this purpose, this approach would have required XS:xml-search clients to be in conformance to the XML Representation of Schemas, which is much more than necessary for achieving the above mentioned goal (given that the operators are not too complex). The chosen approach is compared to ABNF, in order to avoid further relation with features that are available in XML schemas.)

<!-- "XS:operator" element -->
<!ELEMENT XS:operator             EMPTY               >
<!ATTLIST XS:operator name        NAME   #REQUIRED    >
<!ATTLIST XS:operator namespace   CDATA
   "urn:ietf:params:xml:ns:webdav-xml-search"         >


<!-- terminal elements -->
<!ENTITY  % XS:terminal       (operand-literal|
                               operand-typed-literal|
                               operand-property|
                               XS:operand-XPath|
                               XS:operand-nested-op) >

<!ELEMENT XS:operand-XPath       EMPTY>
<!ELEMENT XS:operand-nested-op   EMPTY>

<!-- content model description-->
<!ELEMENT XS:opdesc-rule (XS:operator+,
                         (XS:alternative|XS:repetition|%terminal;)*
)>

<!ELEMENT XS:alternative (XS:repetition|%terminal;)>

<!ELEMENT XS:repetition  (XS:alternative|XS:repetition|%terminal;)* >
<!ATTLIST XS:repetition   atleast    CDATA "0" >
<!ATTLIST XS:repetition   atmost     CDATA "infinity" >

5.2.1.  XS:opdesc-rule and XS:operator

XS:operator references the name of an operator. Several operators may be defined by the same XS:opdesc-rule, and several XS:opdesc-rule may define incremental alternatives (that is, an initial rule may match one or more alternatives, with later rule definitions adding to the set of alternatives, as in the ABNF construction Rule1 =/ Rule2 defined in section 3.3 of [RFC4234] (Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” October 2005.)).

For instance,

  <opdesc-rule>
    <operator name="lt" namespace="DAV:"/>
    <operator name="gt" namespace="DAV:"/>
    <operand-property/>
    <alternative>
      <operand-literal/>
      <operand-typed-literal/>
    </alternative>
  </opdesc-rule>

is equivalent to

  <opdesc-rule>
    <operator name="lt" namespace="DAV:"/>
    <operand-property/>
    <operand-literal/>
  </opdesc-rule>

  <opdesc-rule>
    <operator name="lt" namespace="DAV:"/>
    <operand-property/>
    <operand-typed-literal/>
  </opdesc-rule>

  <opdesc-rule>
    <operator name="gt" namespace="DAV:"/>
    <operand-property/>
    <operand-literal/>
  </opdesc-rule>

  <opdesc-rule>
    <operator name="gt" namespace="DAV:"/>
    <operand-property/>
    <operand-typed-literal/>
  </opdesc-rule>

Mandatory operators SHOULD be omitted from the actual schema returned by a server (since their grammar is implied). If an operator is defined or enhanced by an extension of this protocol, the server MUST return rules (i.e. one or more XS:opdesc-rule elements) for them. If the enhanced operator is a mandatory one, then the alternative rule applies. Hence, if the response includes

  <opdesc-rule>
    <operator name="eq" namespace="DAV:"/>
    <operand-property/>
    <FOO:operand-bar xmlns:FOO="http://foo.example/"/>
  </opdesc-rule>

it means that the DAV:eq operator accepts a pair of (property, foo:bar) operands, as well as it accepts the above-defined (property, literal) and (property, typed-literal) alternatives (from the implicit grammar).

The order in which operands are described is significant, because the ordering of operands within a expression is significant.

5.2.2.  XS:repetition

The semantics of element XS:repetition is similar to the ABNF Variable Repetition (e.g: *Rule) defined in Section 3.6 of [RFC4234] (Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” October 2005.).

The optional attributes "atleast" and "atmost" indicates minimum and maximum allowed occurrences of the described content.

Default values are atleast="0" and atmost="infinity" so that <XS:repetition> allows any number of occurrences, including zero; <XS:repetition atleast="1"> requires at least one, with no upper limit; <XS:repetition atleast="3" atmost="3"> allows exactly 3 and <XS:repetition atleast="1" atmost="2"> allows one or two.

5.2.3.  XS:alternative

The semantics of element XS:alternative is similar to the ABNF Alternatives (e.g: Rule1 / Rule2) defined in Section 3.2 of [RFC4234] (Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF,” October 2005.).

For instance, <XS:alternative> <XS:operand-literal/> <XS:operand-typed-literal/> </XS:alternative> will accept either an operand-typed-literal or an operand-literal but not both.

5.2.4.  Implied operator description

The following query schema describes the operators specified in this document, as well as the operators from [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.), as they would be reported in a QSD response.

This description is implied, i.e. servers SHOULD NOT include it in the response because these operators with these signatures are mandatory.

<xsl-search-schema xmlns="DAV:"

  <XS:opdesc-rule>
    <XS:operator name="eq"  namespace="DAV:"/>
    <XS:operator name="gt"  namespace="DAV:"/>
    <XS:operator name="lt"  namespace="DAV:"/>
    <XS:operator name="lte" namespace="DAV:"/>
    <XS:operator name="gte" namespace="DAV:"/>
    <operand-property/>
    <operand-literal/>
  </XS:opdesc-rule>

  <XS:opdesc-rule>
    <XS:operator name="not" namespace="DAV:"/>
    <XS:operand-nested-op/>
  </XS:opdesc-rule>

  <XS:opdesc-rule>
    <XS:operator name="and" namespace="DAV:"/>
    <XS:operator name="or"  namespace="DAV:"/>
    <XS:repetition atleast="1">
      <XS:operand-nested-op/>
    </XS:repetition>
  </XS:opdesc-rule>

  <XS:opdesc-rule>
    <XS:operator name="filter"/>
    <operand-property/>
    <XS:operand-XPath/>
  </XS:opdesc-rule>

  <XS:opdesc-rule>
    <XS:operator name="is-defined" namespace="DAV:"/>
    <XS:operator name="is-well-formed"/>
    <operand-property/>
  </XS:opdesc-rule>

  <XS:opdesc-rule>
    <XS:operator name="is-collection" namespace="DAV:"/>
  </XS:opdesc-rule>

</xsl-search-schema>

The DAV:is-collection operator is supported because XS:xml-search extends DAV:basicsearch grammar. It can be expressed by using XS:filter as:

 <XS:filter>
  <prop><resourcetype/></prop>
  <XS:xpath>/collection</XS:xpath>
 </XS:filter>

Tests for other resource types, as well as test for no resource type may be expressed by the XS:filter operator (provided that DAV:resourcetype is XS:searchable). For instance, testing whether a resource has no resource type may be expressed as:

 <XS:filter>
  <prop><resourcetype/></prop>
  <XS:xpath>count(/*)==0</XS:xpath>
 </XS:filter>

5.2.5.  Extended operator description for DAV:typed-literal Operand

The DAV:eq, DAV:gt, DAV:lt, DAV:lte, and DAV:gte operators MAY accept a DAV:typed-literal operand, instead of DAV:literal. This alternative is not implied (i.e. if supported, it MUST be included in the QSD response). If DAV:typed-literal were supported (as defined in [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.)), the QSD response would include the following rule:

  <XS:opdesc-rule>
    <XS:operator name="eq"  namespace="DAV:"/>
    <XS:operator name="gt"  namespace="DAV:"/>
    <XS:operator name="lt"  namespace="DAV:"/>
    <XS:operator name="lte" namespace="DAV:"/>
    <XS:operator name="gte" namespace="DAV:"/>
    <operand-property/>
    <operand-typed-literal/>
  </XS:opdesc-rule>

5.2.5.1.  Description of DAV:like Operator

If the DAV:like operator is supported (as described in Section 5.2.2 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.), the following rule MUST be included in the QSD:

  <XS:opdesc-rule>
    <XS:operator name="like"  namespace="DAV:"/>
    <operand-property/>
    <operand-literal/>
  </XS:opdesc-rule>

6.  XML Extensibility

The extensibility mechanism from Section 17 of [RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.) (i.e., to process received XML documents as if unexpected elements and attributes, and all children of unrecognized elements, were not present) may be inappropriate when dealing with queries because they would not be evaluated as specified by the client (e.g. the query criteria may be loosen or the result record or may be incomplete). The omission of unexpected content might not be realized by the client.

The extension attribute provides a mean for distinguishing whether the extension was recognized or ignored, raising a precondition error in the latter case. The attribute value MUST be either "required" or "optional". For conformance with [RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.) and Section 5.2.2 of [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.), when this attribute is not specified its value defaults to "required" when the element occurs as a descendant of DAV:where, and "optional" anywhere else.

Any element allows the following attributes (where "..." represents the element type name):

<!ATTLIST ... extension (required|optional) #IMPLIED>
<!ATTLIST ... id         ID                 #IMPLIED>

When an unexpected or unknown element is present in the request, the server MUST:
   - Ignore it (and its descendants), if the value of the "extension" attribute for that element is "optional" (or the "extension" attribute is missing and the element is not a descendant of DAV:where). The request is then processed as if the element were not there.
   - Fail with status code 422 (Unprocessable Entity) and precondition code XS:unexpected-content, if the value of the "extension" attribute for that element is "required" (or if there is no "extension" attribute and the element is a descendant of DAV:where). In this case, the attrname attribute of XS:unexpected-content MUST NOT be specified. If the element has an "id" attribute, the idref attribute of the XS:unexpected-content precondition MUST be the element id, otherwise the "idref" attribute MUST NOT be specified.

When an unexpected or unknown attribute occurs within an expected element, the server MUST proceed as if the element itself were unexpected or unknown. In addition, if the element is required (as explained above), the attrname attribute of the XS:unexpected-content precondition MUST be assigned with the name of the offending attribute.

<!ELEMENT XS:unexpected-content EMPTY>
<!ATTLIST XS:unexpected-content idref    NMTOKEN #IMPLIED>
<!ATTLIST XS:unexpected-content attrname NMTOKEN #IMPLIED>

If present, the idref attribute MUST match the value of some ID attribute in the request.

7.  Security Considerations

The security considerations of WebDAV SEARCH [I‑D.reschke‑webdav‑search] (Reschke, J., “Web Distributed Authoring and Versioning (WebDAV) SEARCH,” November 2007.), and WebDAV [RFC4918] (Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV),” June 2007.), as well as those of HTTP/1.1 [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) and XML [RFC3023] (Murata, M., St. Laurent, S., and D. Kohn, “XML Media Types,” January 2001.) are applicable to the WebDAV extension described in this document.

8.  IANA Considerations

This document defines XML elements in a XML namespace described by a URN conforming the registry mechanism described in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.). The following URI assignment is requested

URI: urn:ietf:params:xml:ns:webdav-xml-search

Registrant Contact: See the "Author's Address" section of this document.

XML: None. Namespace URIs do not represent an XML specification.

Reference: The last version of this document.

9.  References

9.1. Normative References

9.2. Informative References

Editorial Comments

Appendix A.  Example XS:xml-search query

This example shows a request/response exchange for selecting the DAV:getcontentlength property and the <M:title> and first <M:author> elements of the <M:metadata> property, from resources which are directly contained in the http://host.example.com/ collection, such that the title (as described by a M:title element within the M:metadata property) starts with letter "S". The first results will have at least one M:author element present.

The response describes two resources:
   - foo.pdf, with DAV:getcontentlength = 65536, author = "John Doe" and title = "Sample Title"
   - bar.txt, with DAV:getcontentlength = 1024, title = "Sample Anonymous Resource" and no author.

Request:

SEARCH / HTTP/1.1
Host: host.example.com
Content-Type: application/xml
Content-Length: xxx

<XS:xml-search xmlns="DAV:"
   xmlns:XS="urn:ietf:params:xml:ns:webdav-xml-search"
   xmlns:M ="http://example.org/metadata">
  <select>
    <XS:filter>
      <prop><M:metadata/></prop>
      <XS:xpath>/M:author[1]|/M:title</XS:xpath>
    </XS:filter>
    <prop><getcontentlength/></prop>
  </select>
  <from>
    <scope>
      <href>http://host.example.com/</href>
      <depth>1<depth>
    </scope>
  </from>
  <where>
    <XS:filter>
      <prop><M:metadata/></prop>
      <XS:xpath>starts-with(/M:title,'S')</XS:xpath>
    </XS:filter>
  </where>
  <orderby>
    <order>
      <XS:filter>
        <prop><M:metadata/></prop>
        <XS:xpath>/M:author</XS:xpath>
      </XS:filter>
      <descending>
    </order>
  </orderby>
</XS:xml-search>

Response:

HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxx

<multistatus xmlns="DAV:"
   xmlns:XS="urn:ietf:params:xml:ns:webdav-xml-search"
   xmlns:M ="http://example.org/metadata" >
  <response>
    <href>http://host.example.com/foo.pdf</href>
    <propstat>
      <prop>
        <getcontentlength>65536</getcontentlength>
        <M:metadata>
          <M:author>John Doe</M:author>
          <M:title>Sample title</M:title>
        </M:metadata>
      </prop>
      <status>HTTP/1.1 200 OK<status>
    </propstat>
  </response>
  <response>
    <href>http://host.example.com/bar.txt</href>
    <propstat>
      <prop>
        <getcontentlength>1024</getcontentlength>
        <M:metadata>
          <M:title>Sample Anonymous Resource</M:title>
        </M:metadata>
      </prop>
      <status>HTTP/1.1 200 OK<status>
    </propstat>
  </response>
</multistatus>

Index

Authors' Addresses

Full Copyright Statement

Copyright © The IETF Trust (2008).

This document is subject to the rights, licenses and restrictions contained in BCP 78 and at http://www.rfc-editor.org/copyright.html, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.