This specification describes a new XML object that can be retrieved from hosts to discover applications, features and limits for that host or domain.
© 2016 The Calendaring and Scheduling Consortium, Inc.
This document is not a CalConnect Standard. It is distributed for review and comment, and is subject to change without notice and may not be referred to as a Standard. Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior written permission. Permission can be requested from the address below.
The Calendaring and Scheduling Consortium, Inc.
4390 Chaffin Lane
McKinleyville
California 95519
United States of America
www.calconnect.org
This specification describes a new XML object that can be retrieved from hosts to discover applications, features and limits for that host or domain.
Any given host on a network may support a number of applications. Each will have limits or optional features. The advertising and discovery of applications, features and limits is often through the use of properties and headers. As the number of applications 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 application 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 applications. The schema as described here only handles basic DAV applications. Other specifications will extend this specification to define elements for other DAV based applications.
This specification describes a new XML object that can be retrieved from hosts to discover applications, features and limits for that host or domain.
For the purposes of this document, the following terms and definitions apply.
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
File servers
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
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
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.
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.
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.
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.
The link header field is defined in
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
This specification defines a new XML document type “server-info”. All XML elements in this specification are in the DAV name space.
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:
If a “features” element appears inside the “server-info” element then the features apply to all applications.
The optional “server” element appears once and contains a name and version for the server. The values for both those elements is server specific.
The “applications” element appears once and contains 0 or more “application”
elements each of which provides information about a application. do the applications have to be on the same host? I think not.
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:
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.
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:
All elements defined in this section are in the “DAV” namespace unless otherwise specified.
server-info
Contains information about a server.
token
Contains an opaque token which changes when the document changes.
server-instance-info
Contains name and version information for a server.
name
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.
version
Within a server element the value of the version element is any text string.
applications
Contains information about all applications on a host.
application
Contains information about a specific application on a host.
features
Contains information about all application features on a host.
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.
| Namespace | Name | Reference |
|---|---|---|
| DAV | class-1 | |
| DAV | class-2 | |
| DAV | class-3 | |
| DAV | access-control | |
| DAV | version-control | |
| DAV | extended-mkcol | |
| DAV | quota | |
| DAV | bind | |
| DAV | search | |
| DAV | sync-collection | |
| DAV | add-member |
DAV
class-1
1
Class 1 compliant resource
DAV
class-2
2
Class 2 compliant resource
DAV
class-3
3
Class 3 compliant resource
DAV
access-control
access-control
WebDAV ACL
DAV
version-control
version-control
WebDAV DeltaV
DAV
extended-mkcol
extended-mkcol
Extended mkcol
DAV
bind
bind
Binding extensions
DAV
search
Search extensions
DAV
quota
DAV quotas. May not apply to all resources. Absence of this feature implies no support on any resource.
DAV
sync-collection
Collection synchronization report. May not apply to all resources. Absence of this feature implies no support on any resource.
DAV
add-member
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.
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
| Name | Reference |
|---|---|
| calendar-access | |
| calendar-auto-schedule | |
| calendar-no-timezone | RFC ???? |
urn:ietf:params:xml:ns:caldav
calendar-access
Calendar access
urn:ietf:params:xml:ns:caldav
calendar-auto-schedule
CalDAV implicit scheduling
urn:ietf:params:xml:ns:caldav
calendar-no-timezone
CalDAV implicit timezones
TBD.
Tag enabling synchronization
Document location (section 3)
server-info token in DAV header returned as part of OPTIONS response
Clients that see that and do not have a server-info document for that application should do a propfind to discover document href.
Authenticated v unauth
Clients may fetch the si doc in an unauth mode. When they auth they must recheck their token and refetch if appropriate.
Caching by intermediaries might be an issue Server info may vary by user-agent.
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)
Add something about rscale — calendar-rscale element
TBD.
Something about not sending server name + version. Opaque version code.
This section defines the MIME media type for use with the server information document.
application
server-info+xml
None
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.
Same as encoding considerations of application/xml as specified in RFC 3023.
See previous section.
This media type provides an alternative format for iCalendar data based on XML.
This specification.
None
xml
None specified.
COMMON
There are no restrictions on where this media type can be used.
See the “Authors’ Addresses” section of this document.
IETF
The link relation type “server-info” has been added to the Reference Types Registry defined in
Relation Name: server-info
Description: Provides the location of and current token for the server information document
Reference: This specification
This specification is a result of discussions that took place within the Calendaring and Scheduling Consortium’s CalDAV Technical Committee. The author thanks the participants of that group.
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.
This document specifies a set of methods, headers, and content-types ancillary to HTTP/1.1 for the management of resource properties, creation and management of resource collections, namespace manipulation, and resource locking (collision avoidance). [STANDARDS-TRACK]
This document specifies a set of methods, headers, and resource types that define the WebDAV (Web Distributed Authoring and Versioning) versioning extensions to the HTTP/1.1 protocol. [STANDARDS-TRACK]
This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.
This document specifies a set of methods, headers, message bodies, properties, and reports that define Access Control extensions to the WebDAV Distributed Authoring Protocol. This protocol permits a client to read and modify access control lists that instruct a server whether to allow or deny operations upon a resource (such as HyperText Transfer Protocol (HTTP) method invocations) by a given principal. A lightweight representation of principals as Web resources supports integration of a wide range of user management repositories. Search operations allow discovery and manipulation of principals using human names. [STANDARDS-TRACK]
Web Distributed Authoring and Versioning (WebDAV) servers are frequently deployed with quota (size) limitations. This document discusses the properties and minor behaviors needed for clients to interoperate with quota (size) implementations on WebDAV repositories. [STANDARDS-TRACK]
This document defines extensions to the Web Distributed Authoring and Versioning (WebDAV) protocol to specify a standard way of accessing, managing, and sharing calendaring and scheduling information based on the iCalendar format. This document defines the “calendar-access” feature of CalDAV. [STANDARDS-TRACK]
Web Distributed Authoring and Versioning (WebDAV) consists of a set of methods, headers, and content-types ancillary to HTTP/1.1 for the management of resource properties, creation and management of resource collections, URL namespace manipulation, and resource locking (collision avoidance).
RFC 2518 was published in February 1999, and this specification obsoletes RFC 2518 with minor revisions mostly due to interoperability experience. [STANDARDS-TRACK]
This document specifies a set of methods, headers, and properties composing Web Distributed Authoring and Versioning (WebDAV) SEARCH, an application of the HTTP/1.1 protocol to efficiently search for DAV resources based upon a set of client-supplied criteria. [STANDARDS-TRACK]
This specification extends the Web Distributed Authoring and Versioning (WebDAV) MKCOL (Make Collection) method to allow collections of arbitrary resourcetype to be created and to allow properties to be set at the same time. [STANDARDS-TRACK]
This specification defines bindings, and the BIND method for creating multiple bindings to the same resource. Creating a new binding to a resource causes at least one new URI to be mapped to that resource. Servers are required to ensure the integrity of any bindings that they allow to be created. This document defines an Experimental Protocol for the Internet community.
This document specifies relation types for Web links, and defines a registry for them. It also defines the use of such links in HTTP headers with the Link header field. [STANDARDS-TRACK]
The Hypertext Transfer Protocol (HTTP) Extensions for the Web Distributed Authoring and Versioning (WebDAV) do not define the behavior for the “POST” method when applied to collections, as the base specification (HTTP) leaves implementers lots of freedom for the semantics of “POST”.
This has led to a situation where many WebDAV servers do not implement POST for collections at all, although it is well suited to be used for the purpose of adding new members to a collection, where the server remains in control of the newly assigned URL. In fact, the Atom Publishing Protocol (AtomPub) uses POST exactly for that purpose. On the other hand, WebDAV-based protocols, such as the Calendaring Extensions to WebDAV (CalDAV), frequently require clients to pick a unique URL, although the server could easily perform that task.
This specification defines a discovery mechanism through which servers can advertise support for POST requests with the aforementioned “add collection member” semantics. [STANDARDS-TRACK]
This specification defines an extension to Web Distributed Authoring and Versioning (WebDAV) that allows efficient synchronization of the contents of a WebDAV collection. [STANDARDS-TRACK]
This document defines extensions to the Calendaring Extensions to WebDAV (CalDAV) “calendar-access” feature to specify a standard way of performing scheduling operations with iCalendar-based calendar components. This document defines the “calendar-auto-schedule” feature of CalDAV. [STANDARDS-TRACK]