WebDAV Working Group Alex Hopmann, Microsoft Corporation Internet Draft Lisa Lippert, Microsoft Corporation Document: draft-hopmann-collection-props-00.txt Dec, 1998 Additional WebDAV Collection Properties Status of this Memo This document is an Internet-Draft. 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." To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nic.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). A revised version of this draft document may be submitted to the RFC editor as a Proposed Standard for the Internet Community. Discussion and suggestions for improvement are requested. This document will expire before June, 1999. Distribution of this draft is unlimited. Abstract The WebDAV protocol defines a basic set of properties that should be understood by all DAV servers. This document defines a small set of additional properties that are very useful for displaying navigation interfaces for WebDAV enabled web sites. Table of Contents 1. Introduction .....................................................2 1.1. Notational Conventions ......................................2 2. The Collection Properties ........................................2 1.2. The childcount Property .....................................2 1.3. The defaultdocument Property ................................3 1.4. The id Property .............................................3 1.5. The iscollection Property ...................................3 1.6. The ishidden Property .......................................4 1.7. The isstructureddocument Property ...........................4 1.8. The hassubs Property ........................................5 1.9. The nosubs Property .........................................5 1.10. The objectcount property ..................................6 1.11. The reserved Property .....................................6 1.12. The visiblecount Property .................................6 3. Security Considerations ..........................................6 4. References .......................................................7 5. Author's Addresses ...............................................7 1. Introduction Collections are a type of resource supported by DAV that may have special properties. The DAV draft [DAV] defines how to interact with collections using methods such as MKCOL and PROPFIND, and defines a number of properties which were essential to the proper use of collections. The properties in this draft are not as essential to using collections, therefore they are optional. However, the authors find these to be useful properties to clients, especially to save time and processing and to know how to display collections. Many of these properties are merely hints to a client user interface to help it display collections and options on collections in a manner that is most helpful to the user. 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 RFC 2119 [KEYWORDS]. 2. The Collection Properties This document defines an additional set of properties for use by the WebDAV [1] protocol. These properties provide hints that make it easier to provide efficient user interfaces that provide navigation for WebDAV enabled web sites. If this set of properties is supported, then ALL the properties listed in this draft MUST be supported. This document follows the same collections as the WebDAV protocol specification [1] for defining these properties. 1.2. The childcount Property Name: childcount Namespace: DAV: Purpose: Specifies the number of contained resources. Description: This property identifies the number of resources contained in a given collection. It contains a single integer value with the count of contained resources. This property includes child collections in the count. Definition: 1.3. The defaultdocument Property Name: defaultdocument Namespace: DAV: Purpose: Specifies the default document for a collection. Description: This property contains a URL that identifies the default document for a collection. This is intended for collection owners to be able to set a default document, for example index.html or default.html. If this property is absent, other means must be found to determine the default document. If this property is present but null, the collection does not have a default document and the collection member listing should be used (or nothing). Notes: The server implementation does not need to store this property in the normal property store (the property could well be live). 1.4. The id Property Name: id Namespace: DAV: Purpose: Specifies a unique identifier for this resource. Description: This property contains a globally unique string that identifies this resource. This property MUST be unique across the entire Internet. The id property does not change if the resource changes. This property is intended to aid in recognition of a resource even when moved, updated or renamed. The value of this property is a URI. The URI could contain a string UUID as defined by ISO for RPC [RPC] but any unique URI is sufficient. Definition: 1.5. The isfolder Property Name: isfolder Namespace: DAV: Purpose: Specifies whether or not a collection should appear as a folder. Description: This property identifies whether or not a collection should appear as a folder. It contains either the values "1" or "0". If "1" or absent, the collection should be displayed as a folder. If "0", the collection should NOT be displayed as a folder. For example, a structured document (see below) should have "isfolder" set to "0". Definition: 1.6. The ishidden Property Name: ishidden Namespace: DAV: Purpose: Specifies whether or not a resource is hidden. Description: This property identifies whether or not a resource is hidden. It contains either the values "1" or "0". This can be considered a hint to the client UI: under normal conditions, for non-expert users, hidden files should not be exposed to users. The server may omit the hidden resource from some presentational listings, otherwise the client is responsible for removing hidden resources when displaying to the user. If this property is absent, the collection is not hidden. Since this property provides no actual form of protection to the resources, this MUST NOT be used as a form of access control and should only be used for presentation purposes. Usage example: Many file systems have the option to hide files from the user, but the user can, with special commands, override the hiding. Definition: 1.7. The isstructureddocument Property Name: isstructureddocument Namespace: DAV: Purpose: Specifies whether the resource is a structured document. Description: A structured document is a collection (iscollection should also be true), so COPY, MOVE and DELETE work as for a collection. The structured document may behave at times like a document. For example, clients may wish to display the resource as a document rather than as a collection. This contains either "1" (true) or "0". If this property is absent, the collection is not a structured document. This property can also be considered a hint for the client UI: if the value of "isstructureddocument" is "1", then the client UI may display this to the user as if it were single document. This can be very useful when the default document of a collection is an HTML page with a bunch of images which are the other resources in the collection: only the default document is intended to be viewed as a document, so the entire structure can appear as one document. A Structured document may contain collections. A structured document must have a default document (if the "defaultdocument" property is absent, the default document is assumed by the client to be index.html). Definition: 1.8. The hassubs Property Name: hassubs Namespace: DAV: Purpose: Identifies whether this collection contains any collections which are folders (see "isfolder"). Description: This property identifies whether or not a folder contains sub-folders, from the point of view of client display. Sub-folders are child collections for which "isfolder" = "1". The "hassubs" property contains either the values "1" (yes) or "0" (zero=no). If absent, nothing can be guessed about whether the collection has sub-folders. This property is useful for the efficient display of hierarchy user interfaces. If "hassubs" = "1", then "isfolder" should also be "1" so that clients understand that the folder can be expanded to view its children. Definition: 1.9. The nosubs Property Name: nosubs Namespace: DAV: Purpose: Identifies whether this collection allows child collections to be created. Description: This property identifies whether or not a collection allows child collections to be created. It contains either the values "1" or "0" ("1" indicates that the collection does not allow child collections). While this data is redundant with that returned by the OPTIONS method, providing this information as a property allows better performance since the client can verify the behavior ahead of time without having to issue an individual OPTIONS request on every collection it encounters. If absent, nothing can be guessed about whether the collection allows sub-collections. This property can also be considered to be a hint to the UI about displaying options to the user (the UI might eliminate the option to create a child collection). It is different from a "create child" access right, because the client UI may want to display a "create child collection" option without trying to find out if the user has permissions. This property can be used to suggest that creating child collections just doesn't make sense on this collection no matter what rights the user has. It is most useful on special-purpose collections, such as a deleted files collection or a collection which represents a device such as a printer. This property should not be construed as meaning that sub-collections do not already exist on the collection - it simply prevents new collections from being created by the client. Definition: 1.10. The objectcount property Name: objectcount Namespace: DAV: Purpose: To count the number of non-folder resources in the collection. Description: This is different from childcount in that it omits counting child collections for which "isfolder" = "1". Definition: 1.11. The reserved Property Name: reserved Namespace: DAV: Purpose: Specifies whether or not the collection is reserved. Description: A reserved collection is one that is specially managed by the server and cannot be deleted, renamed, or moved by the client. It contains either the values "1" or "0". Attempts to MOVE or DELETE a reserved collection will fail, and this SHOULD be reflected in the client UI. If absent, the collection should NOT be reserved. The server may allow clients to set this property. It may make sense to also specify that this collection is reserved in the resourcetype; however, in most ways this behaves like a normal collection. Definition: 1.12. The visiblecount Property Name: visiblecount Namespace: DAV: Purpose: Counts the number of visible non-folder resources in the collection. Description: This is the most immediately useful property for the client UI to use to display the sizes of collections for users. The client UI could also display progess when downloading a long list of children in a collection if it knows the total number in advance. This counts all children for which "ishidden" = "0" and "isfolder" = "0". Definition: 3. Security Considerations The ability to hide resources should not be considered a security feature. With the current described behavior, there is a danger that users will be able to discover the hidden resource by trying to write a file of the same name as the hidden resource. In addition, since hidden resources will be exposed via PROPFIND, there is no actual security for them, the hidden nature MUST simply be for presentation (user interface) purposes. This is because the hidden resource feature described here is not intended to be a security feature but a client display feature. Solving the problem of having resources which are undetectable under certain conditions is beyond the scope of this draft. 4. References [HTTP] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, U.C. Irvine, DEC, MIT/LCS, January 1997. [DAV] Y. Goland, E.J. Whitehead, A. Faizi, S.R. Carter, D. Jenson, "Extensions for Distributed Authoring on the World Wide Web", April. 1998, internet-draft, work-in-progress, draft-ietf-webdav-protocol- 08. [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels." RFC 2119, BCP 14. Harvard University. March, 1997. [RPC] ISO/IEC 11578:1996(E) International Standard: "Information Technology -- Open Systems Interconnection -- Remote Procedure Call", December, 1996 (see Annex A) 5. Author's Addresses Alex Hopmann Microsoft Corporation One Microsoft Way Redmond, WA 98052 Email: alexhop@micrososft.com Lisa Lippert Microsoft Corporation One Microsoft Way Redmond, WA 98052 Email: lisal@microsoft.com