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:    <!ELEMENT childcount (#PCDATA) > 
    
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). 
    
   <!ELEMENT defaultdocument (#PCDATA) > 
    
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:    <!ELEMENT id (#PCDATA) > 

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:    <!ELEMENT ishidden (#PCDATA) > 
    
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:    <!ELEMENT ishidden (#PCDATA) >

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:    <!ELEMENT isstructureddocument (#PCDATA) > 
    
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:    <!ELEMENT hassubs (#PCDATA) > 
    
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:    <!ELEMENT nosubs (#PCDATA) >  
    
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:    <!ELEMENT objectcount (#PCDATA) > 
    
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:    <!ELEMENT reserved (#PCDATA) > 
    
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:    <!ELEMENT reserved (#PCDATA) > 
    
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 


