DAV Server Information Object

Internet-Draft	Dav Server Information Object	May 2015
Douglass	Expires 2 December 2015	[Page]

Abstract

This specification describes a new XML object that can be retrieved from hosts to discover services, features and limits for that host or domain.¶

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.¶

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."¶

This Internet-Draft will expire on 2 November 2015.¶

1. Introduction

Any given host on a network may support a number of services. Each of those services will have limits or optional features. The advertising and discovery of services, features and limits is often through the use of properties and headers. As the number of services and features grows the amount of data and complexity of the requests grows.¶

Additionally, headers and properties don't allow for caching mechanisms based on etags. A client has to fetch all the information and compare with its stored copies to determine if a service change has taken place.¶

This specification defines a new XML document type which can be retrieved from a host and is easily extended to allow the description of complex services. The schema as described here only handles basic DAV services. Other specifications will extend this specification to define elements for other DAV based services.¶

2. Conventions Used in This Document

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].¶

2.1. Service

By service we mean an application running on one or more hosts at the network application layer and above. The service may provide data storage, manipulation, presentation, communication or other capabilities. The service may use a well defined protocol and is often implemented with a client-server relationship.¶

A service will usually implement one or more features which may be defined by standard specifications. Services and features may also be constrained by various limits.¶

Examples of services are¶

caldav¶
email¶
File servers¶

2.2. Feature

A feature is some functionality provided by a service. For example, a DAV based service may provide the versioning feature.¶

Services need not support all features that are defined as an optional part of that service. Some features may depend on the authenticated state and/or the authorization of the authenticated principal.¶

Examples of features are¶

DAV versioning.¶
DAV access control.¶
CalDAV scheduling.¶

3. Server Information Document Use

A host will make the document available through one or more methods. Depending upon the endpoint and method of retrieval the retrieved document may describe one or more services.¶

If a document provides information for more than one service it SHOULD contain information allowing clients to obtain information about each individual service only. This allows a client to determine what the actual limits and features are for the specific service.¶

3.1. Server Information Location and Retrieval

3.1.1. DAV:server-info-href property

Name:

server-info-href¶

Namespace:

DAV¶

Purpose:

To define the location of the server-info document.¶

Protected:

This property MAY be protected.¶

PROPFIND behavior:

This property SHOULD NOT be returned by a PROPFIND DAV:allprop request (as defined in Section 14.2 of [RFC4918]).¶

COPY/MOVE behavior:

This property value SHOULD be preserved in COPY and MOVE operations.¶

Description:

This property is needed for a client to determine where the server information document is located. If not present, then no document is available for the server.¶

Definition:

    <!ELEMENT server-info-href (DAV:href)>

3.1.2. Server Information Retrieval

The document may be retrieved from the server by doing a PROPFIND on the .well_known (or any location on the service) for the D:server-info-href property defined above.¶

Clients SHOULD retrieve the document in the context of a session and services SHOULD ensure the context is appropriate. Values in the returned document may differ depending on who is authenticated so a server SHOULD require authentication before returning server information for an authenticated service.¶

3.1.3. Server Information Synchronization

While server features may not change frequently it may be important for clients to react rapidly when server features or limits change. Polling for changes is undesirable so this specification allows for informing clients when the server information has changed.¶

The returned server-info document contains an opaque token which the client can use to determine if the server copy is different. This token is used in a number of places to aid client synchronization.¶

3.1.3.1. Header: server-info-token

The server-info-token header takes as a value the current value of the token element in the server-info document.¶

This header may be returned with a response at any time a server feels appropriate. It MAY be returned in response to a request containing an if-not-server-info-token header.¶

The server-info-token header MUST be returned for an OPTIONS request. It SHOULD be returned if a client attempts to use an unsupported feature or misuse a feature or exceed a limit.¶

3.1.3.2. Header: if-not-server-info-token

The if-not-server-info-token header takes as a value the current token stored by the client. If that value matches the value stored by the server it SHOULD NOT return a server-info-token header. If they do not match the server MUST return a server-info-token header with the current value.¶

If a new value is returned by the server the client should refetch a copy of the server info document.¶

4. Server Information Document Structure

This specification defines a new XML document type "server-info". All XML elements in this specification are in the DAV name space.¶

4.1. Server Information server-info element

At the top level of the document is a "server-info" element which encloses a change token, an optional "features" element and a "services" element¶

          <?xml version="1.0" encoding="utf-8"?>
          <server-info xmlns="DAV">
            <token>...</token>
            <features>
              ...
            </features>
            <services>
              ...
            </services>
          </server-info>

If a "features" element appears inside the "server-info" element then the features apply to all services.¶

4.2. Server Information services element

The "services" element appears once and contains 0 or more "service" elements each of which provides information about a service.¶

NOTE: do the service have to be on the same host? I think not.¶

4.2.1. Server Information service element

The "service" element contains the name and information about the location of that service and how to obtain a service specific server-info document.¶

It may also contain a "features" element which lists features implemented by that service.¶

For example:¶

          <services>
            <features>
              <DAV:class-1 />
              <DAV:class-2 />
              <DAV:access-control />
            </features>
            <service>
              <name>caldav</name>
              <href>https:cal.example.org//.well-known/caldav</href>
              <features>
                <CALDAV:calendar-access />
                <CS:sharing>
                    <CS:no-scheduling />
                </CS:sharing>
              </features>
            </service>
          </services>

4.3. Server Information features element

The "features" element contains 0 or more elements each specifying a feature supported by that service.¶

The "features" element may appear within the "server-info" element - in which case it applies to all services or it may appear inside a "service" element in which case it only applies to that service.¶

When a single service is specified the features named SHOULD be accessible for the same authentication and authorization level.¶

4.3.1. Server Information feature element

A feature is specified by an element defined in this document or by an element defined in the specification for that feature.¶

WebDAV feature elements correspond to, but are not exactly the same as, the elements returned in the DAV header.¶

Some features have no corresponding DAV header element. This may be because the feature is not available on all resources. The occurrence of a such a feature simple advertises the availability of that feature on some resources.¶

For a service supporting this specification, the absence of a feature means that feature is NOT supported on any resource.¶

For example, a calendar service may return the following which specifies a global set of features:¶

            <features>
              <DAV:class-1 />
              <DAV:class-2 />
              <DAV:access-control />
              <CALDAV:calendar-access />
              <CALDAV:calendar-availability />
              <CALDAV:calendar-auto-schedule />
            </features>

5. XML Element Definitions

All elements defined here are in the "DAV:" namespace.¶

5.1. server-info XML element

Name:

server-info¶

Purpose:

Contains information about a single service.¶

Definition:

       <!ELEMENT server-info (token, services?, features?) >

5.2. token XML element

Name:

token¶

Purpose:

Contains an opaque token which changes when the document changes..¶

Definition:

       <!ELEMENT token (#PCDATA) >

5.3. services XML element

Name:

services¶

Purpose:

Contains information about all services on a host.¶

Definition:

       <!ELEMENT services (service*) >

5.4. service XML element

Name:

service¶

Purpose:

Contains information about a specific service on a host.¶

Definition:

       <!ELEMENT service (name, href?) >

5.5. name XML element

Name:

name¶

Purpose:

Within a service or feature element provides the registered name of that service or feature.¶

Definition:

       <!ELEMENT feature (#PCDATA) >

5.6. href XML element

Name:

href¶

Purpose:

Contains location of a specific service.¶

Definition:

       <!ELEMENT href (#PCDATA) >

5.7. features XML element

Name:

features¶

Purpose:

Contains information about all service features on a host.¶

Definition:

       <!ELEMENT features ANY* >

6. WebDAV Features

Here we define the feature elements for features defined in the various DAV related specifications.¶

Specifications which extend this specification should define additions to this table. In addition, they may define the XML specification for that element.¶

Table 1
Namespace	Name	Reference
DAV	class-1	[RFC4918]: section 18.1
DAV	class-2	[RFC4918]: section 18.2
DAV	class-3	[RFC4918]: section 18.3
DAV	access-control	[RFC3744]: section 7.2
DAV	version-control	[RFC3253]: section 3
DAV	extended-mkcol	[RFC5689]: section 3.1
DAV	quota	[RFC4331]
DAV	sync-collection	[RFC6578]
DAV	add-member	[RFC5995]

6.1. DAV class-1 feature XML element

Namespace:

DAV¶

Name:

class-1¶

DAV Header Name:

1¶

Reference:

[RFC4918]: section 18.1¶

Description:

Class 1 compliant resource¶

Definition:

      <!ELEMENT class-1 >

6.2. DAV class-2 feature XML element

Namespace:

DAV¶

Name:

class-2¶

DAV Header Name:

2¶

Reference:

[RFC4918]: section 18.2¶

Description:

Class 2 compliant resource¶

Definition:

      <!ELEMENT class-2 >

6.3. DAV class-3 feature XML element

Namespace:

DAV¶

Name:

class-3¶

DAV Header Name:

3¶

Reference:

[RFC4918]: section 18.3¶

Description:

Class 3 compliant resource¶

Definition:

      <!ELEMENT class-3 >

6.4. DAV access control feature XML element

Namespace:

DAV¶

Name:

access-control¶

DAV Header Name:

access-control¶

Reference:

[RFC3744]: section 7.2¶

Description:

WebDAV ACL¶

Definition:

      <!ELEMENT access-control >

6.5. DAV version control feature XML element

Namespace:

DAV¶

Name:

version-control¶

DAV Header Name:

version-control¶

Reference:

[RFC3253]: section 3¶

Description:

WebDAV DeltaV¶

Definition:

      <!ELEMENT version-control >

6.6. DAV Extended mkcol feature XML element

Namespace:

DAV¶

Name:

extended-mkcol¶

DAV Header Name:

extended-mkcol¶

Reference:

[RFC5689]: section 3.1¶

Description:

Extended mkcol¶

Definition:

      <!ELEMENT extended-mkcol >

6.7. DAV quota feature XML element

Namespace:

DAV¶

Name:

quota¶

Reference:

[RFC4331]¶

Description:

DAV quotas. May not apply to all resources. Absence of this feature implies no support on any resource.¶

Definition:

      <!ELEMENT quota >

6.8. DAV Sync Collection feature XML element

Namespace:

DAV¶

Name:

sync-collection¶

Reference:

[RFC6578]¶

Description:

Collection synchronization report. May not apply to all resources. Absence of this feature implies no support on any resource.¶

Definition:

      <!ELEMENT sync-collection >

6.9. DAV Add Member feature XML element

Namespace:

DAV¶

Name:

add-member¶

Reference:

[RFC6578]¶

Description:

Using POST to add a member to a collection. May not apply to all resources. Absence of this feature implies no support on any resource.¶

Definition:

      <!ELEMENT add-member >

12. Normative References

[ISO.8601.2004]: International Organization for Standardization, "Data elements and interchange formats -- Information interchange -- Representation of dates and times", 2004.
[RFC2119]: Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC2518]: Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. Jensen, "HTTP Extensions for Distributed Authoring -- WEBDAV", RFC 2518, DOI 10.17487/RFC2518, February 1999, <https://www.rfc-editor.org/info/rfc2518>.
[RFC3253]: Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J. Whitehead, "Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning)", RFC 3253, DOI 10.17487/RFC3253, March 2002, <https://www.rfc-editor.org/info/rfc3253>.
[RFC3339]: Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, <https://www.rfc-editor.org/info/rfc3339>.
[RFC3744]: Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol", RFC 3744, DOI 10.17487/RFC3744, May 2004, <https://www.rfc-editor.org/info/rfc3744>.
[RFC4331]: Korver, B. and L. Dusseault, "Quota and Size Properties for Distributed Authoring and Versioning (DAV) Collections", RFC 4331, DOI 10.17487/RFC4331, February 2006, <https://www.rfc-editor.org/info/rfc4331>.
[RFC4918]: Dusseault, L., Ed., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, June 2007, <https://www.rfc-editor.org/info/rfc4918>.
[RFC5689]: Daboo, C., "Extended MKCOL for Web Distributed Authoring and Versioning (WebDAV)", RFC 5689, DOI 10.17487/RFC5689, September 2009, <https://www.rfc-editor.org/info/rfc5689>.
[RFC5995]: Reschke, J., "Using POST to Add Members to Web Distributed Authoring and Versioning (WebDAV) Collections", RFC 5995, DOI 10.17487/RFC5995, September 2010, <https://www.rfc-editor.org/info/rfc5995>.
[RFC6578]: Daboo, C. and A. Quillaud, "Collection Synchronization for Web Distributed Authoring and Versioning (WebDAV)", RFC 6578, DOI 10.17487/RFC6578, March 2012, <https://www.rfc-editor.org/info/rfc6578>.