7.5 Required Properties

The required WebDAV properties are displayname, getlastmodifed, creationdate, getcontentlength, getcontentlanguage, getcontenttype, resourcetype, and source. Conveniently, this list includes all the values you might expect to see in a directory listing in typical file explorer software: the resource name, the kind of resource it is, when it was last changed, and how big it is. This means that WebDAV properties can easily be used to integrate remote repository navigation into existing user interfaces, as was done with Web Folders on Windows, WebDAV-FS on Mac OS X, and Nautilus on Linux.

In addition to the required properties, three live properties are optional: getetag, supportedlock, and lockdiscovery. The first can't be supported if the server doesn't support ETags, although support for both the getetag property and other ETag functionality is strongly recommended. The two lock-related properties are required if locking support is advertised.

All the properties defined in WebDAV are live properties by definition. That means any behavior required for live properties (such as how properties are moved and copied) applies to all of these.

7.5.1 creationdate

The creationdate property is straightforward; it holds the date and time when the resource was created. The resource may have been created with a PUT request, an MKCOL request, a COPY, or some other operation.

Although WebDAV is silent on these matters, normally a file moved from one location to another or simply renamed does not have its creationdate value reset. However, a COPY operation necessarily creates a new resource, so in that case, creationdate is given a new value on the target resource.

Some WebDAV servers protect the creationdate property, but others do not. If a client wants to change the creationdate property, it can try. However, it may be better for the client to use a custom property. For example, if the client is backing up local files and wants the backup to include the file system creation timestamp, the client should create a new dead property for that value.

The creationdate format is the standard IETF recommended date/time format described in Section 7.1.9:

 <D:creationdate>2003-03-03T20:59:00Z</D:creationdate> 

7.5.2 displayname

The display name of a resource is the string that should be shown to the user. Often, it's a different string than the file name. Many systems restrict file names to limited sets of characters, but display names for resources ought to be able to handle international character sets. When WebDAV was defined, there were few reasonable options for displaying non-ASCII characters in URLs, so displayname was defined in part for better internationalization characteristics.

Some examples of valid displayname property values:

 readme.htm Marketing Plan Les Misérables 

Many WebDAV servers (Exchange 2000, IIS 5.0, Xythos WFS 4.0) tie the value of displayname to the URL so that if the final element in the URL path is readme.htm, the value of displayname must also be readme.htm. This doesn't contravene any normative statements in the WebDAV RFC, but it doesn't match what the WebDAV designers had in mind. It means the displayname value must be unique within a collection, and it can't change without making links break. On these implementations, the displayname property is protected so that clients cannot change the value directly. If a resource is renamed with a MOVE request, the value of displayname automatically changes.

Exchange 2000 defines another way to assign friendly, non-unique names to files. The user may change the value of a subject property, which is initially given the same value as displayname but may be changed. The subject value does not have to be unique within a collection, so a user may see many emails in an Exchange 2000 folder with the same subject but different URLs and displayname values.

The mod_dav implementation treats displayname almost as if it were a dead property. When a new resource is created on a mod_dav server, displayname is left blank. It is writable, so the user can give it a value later. The disadvantage to this approach is that the property will be left blank most of the time, so it ends up being ignored by clients.

The different implementations seem to have left the displayname property at an impasse, unusable. Since clients can't rely on the property being writable, clients don't use it as a display name. The working group could update the standard to declare it to be a writable property, but this would make some deployed clients and servers uninteroperable or noncompliant. Some discussions have involved defining a new property that is clearly required to be writable, but the question is still wide open.

7.5.3 getcontentlanguage

Getcontentlanguage must exist on every resource and must be returned whenever the client asks for all the properties on a resource. Its value is obtained from the HTTP Content-Language header the client sends when the resource body is updated, and it can be returned by the server in the same header when the body is retrieved. Getcontentlanguage only applies to the body, not the properties, of a resource. The property value can contain multiple language codes separated by a comma if the document is expressed in multiple languages.

A value of this property is a "language tag" as defined for HTTP/1.1. HTTP/1.1 uses the exact same language tags in the responses to GET requests. A language tag includes both a language code such as EN for English and a country code such as US for United States. Some examples:

en              Any variant of English
en-ca          English as spoken in Canada
en, fr         English or French

The server usually resets the value of this property based on each request that updates the body of the resource. If a PUT request includes the HTTP Content-Language header, then the value can be set directly from this header. (The syntax and allowed values are the same.) When handling COPY and MOVE, the server should apply the source resource's language value.

Unfortunately, language information isn't often provided or used by clients. There are two disadvantages to this failing:

• The obvious drawback to missing language information is that users don't have this information. Users might want to download a document only if it is in a specific language, but they can't tell until the document has been downloaded.

• The less obvious drawback is that some text display choices such as font and layout depend on the language. Some languages share Unicode characters, but these same characters are displayed differently depending on the language selected. Language information helps clients display the document the way it was intended to be viewed.

I recommend that clients send this information when creating resources (or set the value later) if they have a reasonable idea what the value should be. As of 2002, only the Microsoft SharePoint WebDAV client is known to send the Content-Language header.

Server implementations of WebDAV vary in their behavior with respect to the Content-Language header and getcontentlanguage property, even though the feature is a requirement of RFC2518. Xythos WebFile Server (WFS) saves the property if it is provided in the header but returns an empty property value if no language information is available. In contrast, mod_dav always returns a value derived from the system settings and ignores the value of the Content-Language header sent by the client. In any case, servers should not return 404 Not Found for this (or any) required property.

7.5.4 getcontentlength

The getcontentlength property value is an integer. It can be most accurately interpreted as "the value of the Content-Length header if the contents were to be retrieved using a GET request." In most cases for static resources, this is also the size of the resource body in storage.

The property value may not be accurate, depending on the server implementation and its tradeoffs in arriving at an accurate number. In some server implementations, the file storage size may be greater or less than the number of bytes in the response to GET for example, if the stored file includes metadata that is stripped out before sending or if the file is stored zipped or on tape. In this case, it may be too time-consuming for the server to calculate the exact length, and instead the stored size is used as an approximation, even though this is does not comply with the specification.

Dynamic Web pages can, of course, vary in length with each GET request. If a WebDAV server supports dynamic resources, it must deal with this problem in some manner. Since authoring clients that support WebDAV are typically more interested in the source code for a dynamically generated resource than in the result, a server may reasonably provide the length of the source code when clients request the getcontentlength property.

7.5.5 getcontenttype

The getcontenttype property is quite useful because clients can use it to display an informative icon in directory listings. Before downloading a file called README, the client can see whether it will be in text format or not. WebDAV, like HTTP and email [RFC2045], uses MIME types to express the content format.

The server originally gets the value of this property from the Content-Type header on the PUT request that creates the resource. If the resource was created with COPY or MOVE, the server gets the content type from the source resource.

Examples of values for the getcontenttype property include:

text/plain    Ordinary unformatted text
text/html     Text formatted using HTML
image/jpeg    An image represented in the JPEG format

7.5.6 getetag

The ETag of a document is a token or tag used to identify a particular content instance. It's used throughout the World Wide Web for clients and proxies to find out if a document has changed or not (see Section 3.4). The client or proxy can then decide whether to load it from a cache instead, potentially saving bandwidth and returning results faster. The concept is simple: Merely change the ETag of the document every time its contents change.

WebDAV provides the ETag as a property, which gives clients an important benefit: They can find out all the current ETags in one request. The client can then quickly choose which files to update if several files are stored locally in a cache or a synchronized local copy.

Why Use ETag?

Although it's theoretically possible to use a sufficiently accurate value of getlastmodified to see if a resource needs to be updated or synchronized, it's not easy or reliable. Servers and clients both may have clock skew, time zones make it complicated, and the timestamp has to be accurate.

ETags were defined in HTTP to reliably figure out when to update or synchronize a resource. WebDAV makes this even easier, by providing a way (PROPFIND) to retrieve the ETag values for all the resources in a collection.

The value of an ETag and the value of the getetag property are the same: an opaque blob as far as the client is concerned. No attempt should be made to learn anything from the structure or contents of the ETag, because it's only required to be unique, not meaningful.

The ETag value must change when the body changes but not when only property values change. There are a couple of problems with tracking property changes with ETags:

• HTTP clients aren't aware of properties, yet they use ETags in caching. An HTTP client will unnecessarily download an entity that hasn't changed if its ETag changes. This is only a performance issue.

• WebDAV clients that use GET and then PUT to author files must use the ETag to verify that the file hasn't changed between the GET and the PUT. Even if the client locked the file, the lock may have expired accidentally. If the ETag indicates that the file has changed, users may be prompted to overwrite nonexistent changes or throw away their own changes unnecessarily. It's best to cause this kind of user confusion as seldom as possible.

7.5.7 getlastmodified

Many file systems display the time a file was last modified in detailed directory listings. WebDAV provides this property for that functionality. This property should not be used for caching if ETags are available, because dates are less reliable than ETags, but it's still quite useful for displaying to the user.

The issue of whether property changes result in an updated getlastmodified value has been discussed quite a bit because it's underspecified in RFC2518. I recommend tracking modifications to the body only, not properties, for a number of reasons:

• The basic language in the RFC implies that since the property is linked to the Last-Modified header on a GET request, it should take the same value. That is, it contains the date that the content returned by a GET request was last modified.

• Implementations that store resources directly in the file system need to use the file system semantics for the property. Usually in this case the modified date only changes when the body or content is updated.

• Clients may depend on the value of the property to refresh a cache of the resource or decide whether to overwrite it. A value that changes when properties change would involve unnecessary work and possible confusion.

Some WebDAV Working Group members argued that properties were an important part of the context of a resource, and clients needed to know when properties changed as well (perhaps to synchronize property values, too). However, clients can't rely on this unless all servers behave the same way, which they don't. The Apache module mod_dav and Microsoft's implementations of WebDAV update the getlastmodified timestamp only when bodies or contents change. At least one Oracle implementation updates it for every property change. A new property could easily be defined for the last time properties were updated.

7.5.8 resourcetype

The resourcetype property is used to distinguish between an ordinary resource (represented by an empty property value) and a special kind of resource, a collection. It's also intended to be easily extensible so that a resource can advertise that it is a new type, even a custom type defined in a custom namespace. Thus, the value of this property is expressed in XML.

Microsoft Web Folders doesn't do a good job of handling the resourcetype property. It assumes that if the property is not empty, then the resource must be a collection. Of course, it might not be a collection it might be a custom or new resource type that does not have any children to query. This quirk makes it difficult for protocol extension designers to add new kinds of resources that aren't collections (such as versions, added by DeltaV, which we'll see in Chapter 10, WebDAV Products and Tools) without making life hard for Web Folders users.

When a client sees a resourcetype it doesn't recognize, it should assume it's a regular noncollection resource. That probably means it can be locked, moved, or copied.

7.5.9 source

The source property is intended to contain the URLs to the source files that are used to build a dynamic resource. The property is empty on static resources. On a dynamic resource, the property may contain one or several URLs because some dynamic Web pages are compiled from multiple source files. In theory, this should allow clients to author dynamic pages on Web sites.

A source URL might be a regular URL, but it might also be a parameterized URL. Any of these could be source URLs:

http://www.example.com/stockticker.jsp?getsource=true

http://www.example.com/__src/hr/emp-view.jsp

http://www.example.com/cgi-bin/emp-view.c

The source property is another complex XML-valued property. Listing 7-13 is taken straight from RFC2518.

Listing 7-13 Sample value for source property.

 <?xml version="1.0" encoding="utf-8" ?> <D:prop xmlns:D="DAV:" xmlns:F="http://www.foocorp.com/ Project/">    <D:source>       <D:link>          <F:projfiles>Source</F:projfiles>          <D:src>http://foo.bar/program</D:SRC>          <D:dst>http://foo.bar/src/main.c</D:DST>       </D:link>       <D:link>          <F:projfiles>Library</F:projfiles>          <D:src>http://foo.bar/program</D:SRC>          <D:dst>http://foo.bar/src/main.lib</D:DST>       </D:link>       <D:link>          <F:projfiles>Makefile</F:projfiles>          <D:src>http://foo.bar/program</D:SRC>          <D:dst>http://foo.bar/src/makefile</D:DST>       </D:link>    </D:source> </D:prop> 

In theory, the client can simply GET each of the destination (dst) URLs in the property to view the source code. In practice, it's not so simple. Do destination URLs in the property point to WebDAV resources, HTTP resources, or others? Do all the source (src) URLs have to be the same URL? Does the source URL have to be the URL of the resource this property appears on? Is this property interoperable with or without the projfiles extension in the custom namespace?

The whole issue of authoring source code is seriously underspecified. In addition to the questions arising from the format of the source property, there are even more unanswered questions:

• To edit source code, should the client PUT to the original resource URL or the new one?

• How does a client add a new source file?

• What happens if more than one resource points to (uses) the same source code?

• When a dynamic resource is the source of a MOVE or a COPY operation, is the new resource created at the destination a dynamic resource or a static snapshot?

• Can any collection contain dynamic resources or only some?

• What kind of dynamic resources are supported on this server JSP, ASP, CGI?

Not surprisingly, no known WebDAV server or client fully supports the source property, and certainly no interoperability has been shown. Some WebDAV servers (e.g., Microsoft Exchange 2000, Xythos WebFile Server) do not handle dynamic content at all. Other servers do support dynamic content, but they may not have a way of knowing what the URL is to get the unevaluated source code for the page (e.g., mod_dav).

IIS 5.0 does support dynamic content and does know where the source code is for some kinds of pages, including Active Server Pages. However, IIS 5.0 does not use the source property. The IIS 5.0 mechanism is the Translate header, which is described in Section 9.2.1.

The WebDAV specification is not clear on how to return properties that are required but do not have values, such as the source property on a static resource. The server may return an empty value for this property or return 404 Not Found.