DAV Server Information Object

Internet-Draft	DAV Server Information Object	April 2016
Douglass	Expires 3 October 2016	[Page]

Abstract

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

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

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

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

Examples of applications are:¶

caldav * email * File servers¶

3.2. Feature

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

Applications need not support all features that are defined as an optional part of that application. 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¶

4. 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 applications.¶

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

4.1. Server Information Location and Retrieval

4.1.1. Server Information Retrieval

The document may be retrieved from the server by including the server-info-token header field with a value of "*" any request to the server.¶

The server MUST respond to such a request by including a LINK header field with a reltype of "server-info", a token parameter with the current token value and the url being the location of the document.¶

Following that a GET may be executed by the client against that URL, specifying a content type in the ACCEPT header field of "application/server-info+xml".¶

Clients SHOULD retrieve the document in the context of a session and applications 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 application.¶

4.1.2. 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 server feature changes is undesirable so this specification allows clients to check for such changes during normal operations.¶

Clients SHOULD include the server-info-token header field with the current stored value of the token from the document in requests to the server.¶

The server MUST add the link header field to the response when the tokens do not match.¶

4.1.2.1. Header Field: server-info-token

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

This header field may be included in a request at any time a client feels appropriate.¶

4.1.2.2. Header Field: link

The link header field is defined in [RFC5988]. The target IRI as defined by that specification will be the location of the server information document. The "reltype" parameter will have the value "server-info".¶

Additionally, there will be a "token" parameter which has a quoted token as the value.¶

This header field may be included in a response at any time a server feels appropriate.¶

The link header field MUST be returned in response to:¶

An OPTIONS request where the server-info-token header is absent or it's value does not match. * Any request with the server-info-token header field where the value of the header field does not math the current token value.¶

The link header field SHOULD be returned when a client:¶

Attempts to use an unsupported feature.¶
Misuses a feature according to the server info document.¶
Exceeds a limit defined in the document.¶

If the server returns a link header field as part of the response it is an indication to the client that it SHOULD fetch a new copy of the server information document.¶

The following is an example of a link header field - folded to fit on the page¶

Link: </dav/principals/.server-info>; rel="server-info";
 token="7140903ee1b57d0752a7d8da774a398b10de5868"

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

5.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 an "applications" element:¶

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

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

5.2. Server Information server element

The optional "server" element appears once and contains a name and version for the server. The values for both those elements is server specific.¶

5.3. Server Information applications element

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

5.3.1. Server Information application element

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

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

For example:¶

<applications>
  <application>
    <name>caldav</name>
    <features>
      <CALDAV:calendar-access />
      <CS:sharing>
          <CS:no-scheduling />
      </CS:sharing>
    </features>
  </application>
</applications>

5.4. Server Information features element

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

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

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

5.4.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 field.¶

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

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

For example, a calendar application 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>

6. XML Element Definitions

All elements defined in this section are in the "DAV" namespace unless otherwise specified.¶

6.1. server-info XML element

Name

server-info¶

Purpose

Contains information about a server.¶

Definition

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

6.2. token XML element

Name

token¶

Purpose

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

Definition

<!ELEMENT token (#PCDATA) >

6.3. server-instance-info XML element

Name

server-instance-info¶

Purpose

Contains name and version information for a server.¶

Definition

<!ELEMENT server-instance-info (server-name*, server-version*,
                               server-link, server-contact) >
* product name
* product version
* product bug tracker link (or just link)
* system administrator contact ("mailto:", "tel:" an embedded vcard or a link to a vcard?)
* operating system info (string like the result of "uname -a" on POSIX systems)

6.4. name XML element

Name

name¶

Purpose

Within an application or feature element provides the registered name of that application or feature.¶

Within a server element the value of the name element is any text string.¶

Definition

<!ELEMENT name (#PCDATA) >

6.5. version XML element

Name

version¶

Purpose

Within a server element the value of the version element is any text string.¶

Definition

<!ELEMENT version (#PCDATA) >

6.6. applications XML element

Name

applications¶

Purpose

Contains information about all applications on a host.¶

Definition

<!ELEMENT applications (application*) >

6.7. application XML element

Name

application¶

Purpose

Contains information about a specific application on a host.¶

Definition

<!ELEMENT application (name, features) >

6.8. features XML element

Name

features¶

Purpose

Contains information about all application features on a host.¶

Definition

<!ELEMENT features ANY* >

7. 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	Section 18.1 of [RFC4918]
DAV	class-2	Section 18.2 of [RFC4918]
DAV	class-3	Section 18.3 of [RFC4918]
DAV	access-control	Section 7.2 of [RFC3744]
DAV	version-control	Section 3 of [RFC3253]
DAV	extended-mkcol	Section 3.1 of [RFC5689]
DAV	quota	[RFC4331]
DAV	bind	[RFC5842]
DAV	search	[RFC5323]
DAV	sync-collection	[RFC6578]
DAV	add-member	[RFC5995]

7.1. DAV class-1 feature XML element

Namespace

DAV¶

Name

class-1¶

DAV Header Name

1¶

Reference

Section 18.1 of [RFC4918]¶

Description

Class 1 compliant resource¶

Definition

<!ELEMENT class-1 >

7.2. DAV class-2 feature XML element

Namespace

DAV¶

Name

class-2¶

DAV Header Name

2¶

Reference

Section 18.2 of [RFC4918]¶

Description

Class 2 compliant resource¶

Definition

<!ELEMENT class-2 >

7.3. DAV class-3 feature XML element

Namespace

DAV¶

Name

class-3¶

DAV Header Name

3¶

Reference

Section 18.3 of [RFC4918]¶

Description

Class 3 compliant resource¶

Definition

<!ELEMENT class-3 >

7.4. DAV access control feature XML element

Namespace

DAV¶

Name

access-control¶

DAV Header Name

access-control¶

Reference

Section 7.2 of [RFC3744]¶

Description

WebDAV ACL¶

Definition

<!ELEMENT access-control >

7.5. DAV version control feature XML element

Namespace

DAV¶

Name

version-control¶

DAV Header Name

version-control¶

Reference

Section 3 of [RFC3253]¶

Description

WebDAV DeltaV¶

Definition

<!ELEMENT version-control >

7.6. DAV Extended mkcol feature XML element

Namespace

DAV¶

Name

extended-mkcol¶

DAV Header Name

extended-mkcol¶

Reference

Section 3.1 of [RFC5689]¶

Description

Extended mkcol¶

Definition

<!ELEMENT extended-mkcol >

7.7. DAV bind feature XML element

Namespace

DAV¶

Name

bind¶

DAV Header Name

bind¶

Reference

[RFC5842]¶

Description

Binding extensions¶

Definition

<!ELEMENT bind >

7.8. DAV search feature XML element

Namespace

DAV¶

Name

search¶

Reference

[RFC5323]¶

Description

Search extensions¶

Definition

<!ELEMENT search >

7.9. 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 >

7.10. 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 >

7.11. 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 >

8. CalDAV Features

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

All of these are under the CalDAV namespace:¶

urn:ietf:params:xml:ns:caldav¶

Table 2
Name	Reference
calendar-access	[RFC4791]
calendar-auto-schedule	[RFC6638]
calendar-no-timezone	RFC ????

8.1. CalDAV calendar-access feature XML element

Namespace

urn:ietf:params:xml:ns:caldav¶

Name

calendar-access¶

Reference

[RFC4791]¶

Description

Calendar access¶

Definition

<!ELEMENT calendar-access >

8.2. CalDAV calendar-auto-schedule feature XML element

Namespace

urn:ietf:params:xml:ns:caldav¶

Name

calendar-auto-schedule¶

Reference

[RFC4791]¶

Description

CalDAV implicit scheduling¶

Definition

<!ELEMENT calendar-auto-schedule >

8.3. CalDAV calendar-no-timezone feature XML element

Namespace

urn:ietf:params:xml:ns:caldav¶

Name

calendar-no-timezone¶

Reference

[RFC4791]¶

Description

CalDAV implicit timezones¶

Definition

<!ELEMENT calendar-no-timezone >

12. IANA Considerations

12.1. MIME media type Registrations

Media Type: This section defines the MIME media type for use with the server information document.¶
Type name: application¶
Subtype name: server-info+xml¶
Required parameters: None¶
Optional parameters: charset as defined for application/xml in RFC 3023; per RFC 3023, use of the charset property parameter with the value "utf-8" is STRONGLY RECOMMENDED.¶
Encoding considerations: Same as encoding considerations of application/xml as specified in RFC 3023.¶
Security considerations: See previous section.¶
Interoperability considerations: This media type provides an alternative format for iCalendar data based on XML.¶
Published specification: This specification.¶
Additional information
Magic number(s): None¶
File extension(s): xml¶
Macintosh file type code(s): None specified.¶
Person email address to contact for further information: mailto:calsify@ietf.org¶
Intended usage: COMMON¶
Restrictions on usage: There are no restrictions on where this media type can be used.¶
Author: See the "Authors' Addresses" section of this document.¶
Change controller: IETF¶

12.2. New Link reltype Registration

The link relation type "server-info" has been added to the Reference Types Registry defined in Section 6.2 of [RFC5988] with the following values:¶

Relation Name: server-info¶
Description: Provides the location of and current token for the server information document¶
Reference: This specification¶

13. References

13.1. Normative References

[RFC2119]: Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", IETF, DOI 10.17487/RFC2119, BCP 14, RFC 2119, 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", IETF, DOI 10.17487/RFC2518, RFC 2518, 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)", IETF, DOI 10.17487/RFC3253, RFC 3253, March 2002, <https://www.rfc-editor.org/info/rfc3253>.
[RFC3339]: Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", IETF, DOI 10.17487/RFC3339, RFC 3339, 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", IETF, DOI 10.17487/RFC3744, RFC 3744, 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", IETF, DOI 10.17487/RFC4331, RFC 4331, February 2006, <https://www.rfc-editor.org/info/rfc4331>.
[RFC4791]: Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", IETF, DOI 10.17487/RFC4791, RFC 4791, March 2007, <https://www.rfc-editor.org/info/rfc4791>.
[RFC4918]: Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", IETF, DOI 10.17487/RFC4918, RFC 4918, June 2007, <https://www.rfc-editor.org/info/rfc4918>.
[RFC5323]: Reddy, S., Davis, J., Babich, A., and J. Reschke, "Web Distributed Authoring and Versioning (WebDAV) SEARCH", IETF, DOI 10.17487/RFC5323, RFC 5323, November 2008, <https://www.rfc-editor.org/info/rfc5323>.
[RFC5689]: Daboo, C., "Extended MKCOL for Web Distributed Authoring and Versioning (WebDAV)", IETF, DOI 10.17487/RFC5689, RFC 5689, September 2009, <https://www.rfc-editor.org/info/rfc5689>.
[RFC5842]: Clemm, G., Crawford, J., Whitehead, J., and J. Reschke, "Binding Extensions to Web Distributed Authoring and Versioning (WebDAV)", IETF, DOI 10.17487/RFC5842, RFC 5842, April 2010, <https://www.rfc-editor.org/info/rfc5842>.
[RFC5988]: Nottingham, M., "Web Linking", IETF, DOI 10.17487/RFC5988, RFC 5988, October 2010, <https://www.rfc-editor.org/info/rfc5988>.
[RFC5995]: Reschke, J., "Using POST to Add Members to Web Distributed Authoring and Versioning (WebDAV) Collections", IETF, DOI 10.17487/RFC5995, RFC 5995, September 2010, <https://www.rfc-editor.org/info/rfc5995>.
[RFC6578]: Daboo, C. and A. Quillaud, "Collection Synchronization for Web Distributed Authoring and Versioning (WebDAV)", IETF, DOI 10.17487/RFC6578, RFC 6578, March 2012, <https://www.rfc-editor.org/info/rfc6578>.
[RFC6638]: Daboo, C. and B. Desruisseaux, "Scheduling Extensions to CalDAV", IETF, DOI 10.17487/RFC6638, RFC 6638, June 2012, <https://www.rfc-editor.org/info/rfc6638>.
[ISO.8601.2004]: ISO, "Data elements and interchange formats - Information interchange - Representation of dates and times", ISO 8601:2004, December 2004, <https://www.iso.org/standard/40874.html>.