Network Working Group Ryan Troll Document: draft-ietf-acap-dataset-model-01.txt Carnegie Mellon Expires October 3, 1999 March 29, 1999 An Introduction to the ACAP Dataset Model Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 list Internet-Draft Shadow Directories, see http://www.ietf.org/shadow.html. Distribution of this memo is unlimited. Abstract The ACAP [ACAP] Dataset Model is very extensible, and allows applications to easily share options and information. With this extensibility comes a complexity that an application designer must fully understand in order to interoperate while using ACAP. This document will help the reader understand and visualize the ACAP hierarchy, come to a better understanding of how to design and access ACAP datasets, and understand the relationship between attributes, entries, datasets, and dataset classes. 0. Outstanding Issues Need to address inheritance. It is ignored in this document, and is a big hairy beast that should be discussed. However, I need help doing so, as I don't fully understand when it should and should not be used yet. Expires October 3, 1999 Troll [Page 1] Internet Draft ACAP Dataset Model March 29, 1999 1. Introduction The Application Configuration Access Protocol [ACAP] is designed to support remote storage and access of program option, configuration, and preference information. The data store model is designed to allow a client relatively simple access to data, to allow new information to be easily added without server reconfiguration, and to promote the use of both standardized data and custom or proprietary data. This document explores the data store model, allowing the reader to visualize what the ACAP data store actually looks like. With this picture, developers will be able to design an ACAP dataset class for their own applications, and interoperate with others. 1.1. Conventions Used in the 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 [KEYWORDS]. 1.2. Terminology Dataset Class A dataset class is a formal description of how to use information stored within a dataset. Descriptions of all attributes, and what their values mean, make up a dataset class. Dataset Every level of the ACAP hierarchy is a dataset. Datasets contain entries, and/or other datasets. Datasets may inherit entries from other datasets, or be standalone repositories of information. Sub-Dataset A dataset may contain other datasets. These datasets are subsets of the main dataset, and may contain entries that are grouped together for a common reason. In a dictionary, words are grouped together based on their first letter. These smaller groupings are subsets of the entire dictionary, just like sub- datasets are subsets of the entire dataset. Sub-datasets do not have to reside on the same ACAP server as the dataset containing the sub-dataset pointer. A site may provide an ACAP server for all users, and this ACAP server may contain custom bookmarks for all users. If a user decides to use another ACAP server for his/her ACAP needs, one entry Expires October 3, 1999 Troll [Page 2] Internet Draft ACAP Dataset Model March 29, 1999 in the user's bookmark dataset could be a sub-dataset pointer back to the site-wide dataset. A full dataset may also be a sub-dataset of another dataset. Being a sub-dataset does not change how the dataset is accessed or viewed. Sub-datasets provide a way for a dataset to break up its data into smaller chunks, and/or share data between datasets. Entry One item in a dataset is an entry (e.g. A web bookmark). An entry consists of a collection of attributes. Attribute The smallest piece of information in an ACAP dataset. An attribute describes one aspect of an entry, and consist of a few pieces of meta-data. The most important meta-data is the name and a value. (e.g. the name 'color' and the value 'black') 2. ACAP Data Model This section defines all of the parts of the ACAP data model, starting with the smallest piece of information. 2.1. Attribute / Value The smallest piece of information in the ACAP data store is an attribute. An attribute includes two pieces of information: a name, and a value. Attributes may also have multiple values. Multiple values are stored as parenthesized lists of values. The value types Atom, Number, String, Parenthesized List, and NIL are defined in [ACAP], section 2.6. Some attributes are already defined, and are used for every entry. These attributes include "entry", which is the name of the entry, and "subdataset", which is used to indicate that the entry represents a sub-dataset. These attributes are not necessarily shown to the user. The bookmark dataset [BOOK] includes the attributes "bookmarks.Description", containing a user-assigned description (e.g. "CMU's ACAP Page"); "bookmarks.Name", containing the name of the reference (e.g. "ACAP Home Page"); and "bookmarks.URL", which is the bookmarked URL (e.g. "http://asg.web.cmu.edu/acap"). In this dataset, the attribute "entry" is not shown to the user, and is only used as a uniquifier within the dataset itself. These attributes, along with others, contain all the information needed by a client regarding this bookmark. Expires October 3, 1999 Troll [Page 3] Internet Draft ACAP Dataset Model March 29, 1999 The dictionary dataset [DICT] includes the attributes "entry" and "dictionary.definition". The attribute "entry" may have the value "spam", and is shown to the user, while the attribute "dictionary.definition" may have the value "("To send multiple unsolicited messages" "A meat-like substance")". 2.1.1. Attribute Naming Scheme Attributes MUST adhere to a strict naming scheme. Attributes names which do not contain a dot (".") are reserved for standardized attributes which have meaning in any dataset. ("entry" and "modtime", for example.) All other attributes MUST contain a dot ("."), and by convention use a name of the format "Dataset.Attr", where 'Dataset' is the name of the dataset, and 'Attr' is the name of the attribute within the dataset. ('Attr' may contain dots.) Some attributes are pre-defined, and have special meanings. These attributes are: entry The name of the entry within the dataset. This value MUST be unique within the dataset. modtime Timestamp of the last modification to anything within this entry. This is generated by the server. subdataset If set, this attributes indicates the existence of a sub-dataset of this entry. For more information on the predefined attributes, consult [ACAP], section 3.1.1. Attribute names are unique across all datasets. This is accomplished by the attribute naming scheme: all attribute names MUST be of the form ".". Within the dictionary dataset, all entries contain the attribute "dictionary.definition", which is a list attribute containing the definition(s) of the word. Also, the attribute "entry" takes on an additional meaning in the dictionary dataset: it is the word the entry is for. 2.1.2. Searching for Specific Attributes When searching an ACAP dataset, a comparison function (referred to as a search comparator) must be specified, in order to handle the different types of values. When searching for a specific string, the "i;ascii-casemap" may be used, while when searching for a number the "i;octet" comparator may be used. For more information on what Expires October 3, 1999 Troll [Page 4] Internet Draft ACAP Dataset Model March 29, 1999 comparators are available, refer to [ACAP], section 3.2. 2.2. Entry An entry is a collection of attributes, grouped together to describe a common item. Entries within a dataset MUST have a unique name. The design of the ACAP dataset MUST make sure this is the case. The entry name does not have to have any bearing on the actual entry content. (For an example of this, see the example at the end of this document.) It is up to the client to choose a unique name for any entries it is going to create in the ACAP hierarchy. At this time, there is no standard way to choose an entry name. For example, when using ACAP to store a personal dictionary, the entry name may be the word. Since the word may have multiple definitions, the dictionary dataset has been structured to use multi-valued attributes to allow clients to store multiple definitions. On the other hand, an ACAP entry describing a bookmark may contain the URL, name, type, and last visited time. The name of the bookmark entry may be an alpha-numeric uniquifier, which has no meaning to the rest of the entry. Another example is to compare the ACAP data store to a filesystem. In this case, every entry may be considered a directory entry. The contents of the files are irrelevant, and only the file attributes are examined. The name of the file is unique within the dataset, just like the dataset entry names, and all entries within the directory have an owner, a modification time, a last accessed time, and a size. 2.3. Dataset A dataset is a collection of entries and datasets, which represent a set of the information being defined. When looking at a collection of bookmarks, a dataset may be defined for each of your folders of bookmarks, with a top-level dataset containing all of these folders, as well as any unfiled bookmarks. 2.3.1. Dataset Inheritance Datasets may also inherit values from other datasets. Sites may want to define a base set of bookmarks that all of their users see. This can be accomplished by using dataset inheritance. When Expires October 3, 1999 Troll [Page 5] Internet Draft ACAP Dataset Model March 29, 1999 accessing a dataset that inherits from another, the accessed dataset appears to contain everything that is actually stored in it, as well as what is stored in the dataset it is inheriting from. For example, a site may want to have a collection of Web bookmarks that are available for all users. If every user's bookmark dataset is configured to inherit from the master bookmark dataset, clients that fetch all of the user's bookmarks will not only see the user's personal bookmarks, but also the site specific bookmarks. One important thing to remember: a client can not distinguish between inherited entries, and entries that are actually in the dataset, unless the search that is performed specificly says not to use inheritance. Designers and adminstrators MUST be careful when using inheritance. 2.4. Dataset Class A dataset class is a formal definition of a dataset. The class definition describes what data is stored, where the information is stored, and what format it is stored in. This allows multiple applications to use the same data within the ACAP server, without having to worry about breaking it for other applications. As long as all applications adhere to the dataset class definition, there will be no problems. Standardizing dataset class definitions allows multiple applications to share data, even if they are from different vendors. By defining a common bookmark dataset class, all web browsers are able to share their bookmarks with one another. In addition, by storing their bookmarks on an ACAP server, multiple instantiations of browsers across multiple computers and operating systems are able to safely modify and update the list, with all other apps picking up the changes as they are made. 2.4.1. Dataset Class Naming Scheme All dataset classes have a name. The name is used to locate the dataset class within the hierarchy. Dataset class names MUST either be of the form "vendor.", or be specified in a standards track or IESG approved experimental RFC. The proposed dictionary dataset class uses the dataset class name "/dictionary", while a vendor's mechanism for storing application-specific options (such as window location) may be under, for example, "/vendor.cyrusoft.mulberry". Expires October 3, 1999 Troll [Page 6] Internet Draft ACAP Dataset Model March 29, 1999 3. Hierarchy The dataset namespace is a slash-separated hierarchy. The first part of the namespace is the dataset class. For standard datasets, this will be the name specified by the standard, such as "/bookmarks" or "/dictionary". For vendor-specific dataset classes, this will be the prefix "vendor", the name of the vendor, and the product, all separated by a periods. (e.g. "/vendor.cyrusoft.mulberry") The second part of the namespace is the ownership class, or scope of the dataset. This can be "site", for server-wide datasets; "group" for administrative group datasets; "host" for host specific data; or "user" for a user's data. If the scope is "group", "host", or "user", the third part of the namespace identifier is the name of the group, host, or user. (For example, "/vendor.cyrusoft.mulberry/host/lister.net.cmu.edu" would be Mulberry preferences specific to the host "lister.net.cmu.edu".) To fetch the bookmarks for user "ryan" on the ACAP server, the dataset to be searched would be "/bookmarks/user/ryan". If "ryan" is the current ACAP user, this may be abbreviated as "/bookmarks/~". The dataset "/byowner" is reserved, and allows searches to show what dataset classes are owned by a given user. Searching "/byowner/user/ryan" will show all of the dataset classes in use by user "ryan". Finally, searching the dataset "/" is equivalent to searching "/byowner/user/". (Or "/byowner/~"). 4. Bookmark Dataset Class The ACAP bookmarks dataset class is defined in [BOOK]. The following example contains a couple of entries in this dataset, to demonstrate sub-datasets as well as give a visible example of what the dataset hierarchy looks like. 4.1. Example The following example shows what data is in ACAP, and how that data may be used to generate a nice list of web bookmarks for your browser. Expires October 3, 1999 Troll [Page 7] Internet Draft ACAP Dataset Model March 29, 1999 4.1.1. ACAP Bookmark Dataset In dataset /bookmarks/user/ryan entry 104 bookmarks.Name "Lurkers Guide to Babylon 5" bookmarks.Description "Cool site with very complete episode guides" bookmarks.URL "http://www.midwinter.com/lurk" bookmarks.Type "link" entry 12dag8 bookmarks.Name "SSH (Secure Shell) Home Page" bookmarks.Description "" bookmarks.URL "http://www.cs.hut.fi/ssh/" bookmarks.Type "link" entry 13ksjhdfgpoa bookmarks.Type "separator" entry 14roblink subdataset "acap://other.acap.domain/bookmarks/rob/public" bookmarks.Name "Rob's Public Bookmarks" bookmarks.Type "folder" entry 15emailfoo subdataset . bookmarks.Name "Email Stuff" bookmarks.Type "folder" In dataset /bookmarks/user/ryan/Email Stuff Expires October 3, 1999 Troll [Page 8] Internet Draft ACAP Dataset Model March 29, 1999 entry 2baz212 bookmarks.Name "ACAP Home Page" bookmarks.Description "It's not LDAP" bookmarks.URL "http://asg.web.cmu.edu/acap" bookmarks.Type "link" entry 3bar51 bookmarks.Name "IMAP Home Page" bookmarks.Description "Protocol for fetching messages" bookmarks.URL "http://asg.web.cmu.edu/cyrus" bookmarks.Type "link" entry 812foo bookmarks.Name "Sieve Home Page" bookmarks.Description "Sieve mail filtering language" bookmarks.URL "http://asg.web.cmu.edu/sieve" bookmarks.Type "link" 4.1.2. Generated Bookmarks File Based on this information, the following web bookmark display can be generated: Lurkers Guide to Babylon 5 SSH (Secure Shell) Home Page ---------------------------- Rob's Public Bookmarks -> Email Stuff -> And, the "Email Stuff" folder / sub-menu would contain: ACAP Home Page IMAP Home Page Sieve Home Page 5. Copyright Copyright (C) The Internet Society 1999. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing Expires October 3, 1999 Troll [Page 9] Internet Draft ACAP Dataset Model March 29, 1999 the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 6. References [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997 [ACAP] C. Newman, J. G. Myers, "Application Configuration Access Protocol", RFC 2244, November 1997 [DICT] C. Daboo, "ACAP Personal Dictionary Dataset", Work In Progress, March 1998 [BOOK] R. Gellens, "ACAP Bookmarks Dataset Class", Work In Progress, December 1998 7. Author's Address Ryan Troll Computing Services Carnegie Mellon 5000 Forbes Avenue Pittsburgh, PA 15213 Phone: (412) 268-8691 Expires October 3, 1999 Troll [Page 10] Internet Draft ACAP Dataset Model March 29, 1999 EMail: ryan@andrew.cmu.edu Expires October 3, 1999 Troll [Page 11]