idnits 2.17.1 draft-ietf-acap-dataset-model-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 2 instances of too long lines in the document, the longest one being 7 characters in excess of 72. ** The abstract seems to contain references ([ACAP]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 424 has weird spacing: '...r, "Key words...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 29, 1999) is 9150 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'DICT' -- Possible downref: Non-RFC (?) normative reference: ref. 'BOOK' Summary: 12 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Ryan Troll 3 Document: draft-ietf-acap-dataset-model-01.txt Carnegie Mellon 4 Expires October 3, 1999 March 29, 1999 6 An Introduction to the ACAP Dataset Model 8 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance with 13 all provisions of Section 10 of RFC2026. Internet-Drafts are 14 working documents of the Internet Engineering Task Force (IETF), its 15 areas, and its working groups. Note that other groups may also 16 distribute working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other documents 20 at any time. It is inappropriate to use Internet- Drafts as 21 reference material or to cite them other than as "work in progress." 23 To view the list Internet-Draft Shadow Directories, see 24 http://www.ietf.org/shadow.html. 26 Distribution of this memo is unlimited. 28 Abstract 30 The ACAP [ACAP] Dataset Model is very extensible, and allows 31 applications to easily share options and information. With this 32 extensibility comes a complexity that an application designer must 33 fully understand in order to interoperate while using ACAP. 35 This document will help the reader understand and visualize the ACAP 36 hierarchy, come to a better understanding of how to design and 37 access ACAP datasets, and understand the relationship between 38 attributes, entries, datasets, and dataset classes. 40 0. Outstanding Issues 42 Need to address inheritance. It is ignored in this document, and is 43 a big hairy beast that should be discussed. However, I need help 44 doing so, as I don't fully understand when it should and should not 45 be used yet. 47 1. Introduction 49 The Application Configuration Access Protocol [ACAP] is designed to 50 support remote storage and access of program option, configuration, 51 and preference information. The data store model is designed to 52 allow a client relatively simple access to data, to allow new 53 information to be easily added without server reconfiguration, and 54 to promote the use of both standardized data and custom or 55 proprietary data. 57 This document explores the data store model, allowing the reader to 58 visualize what the ACAP data store actually looks like. With this 59 picture, developers will be able to design an ACAP dataset class for 60 their own applications, and interoperate with others. 62 1.1. Conventions Used in the Document 64 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 65 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 66 document are to be interpreted as described in [KEYWORDS]. 68 1.2. Terminology 70 Dataset Class A dataset class is a formal description of how to use 71 information stored within a dataset. Descriptions of 72 all attributes, and what their values mean, make up a 73 dataset class. 75 Dataset Every level of the ACAP hierarchy is a dataset. 76 Datasets contain entries, and/or other datasets. 77 Datasets may inherit entries from other datasets, or 78 be standalone repositories of information. 80 Sub-Dataset A dataset may contain other datasets. These datasets 81 are subsets of the main dataset, and may contain 82 entries that are grouped together for a common 83 reason. In a dictionary, words are grouped together 84 based on their first letter. These smaller groupings 85 are subsets of the entire dictionary, just like sub- 86 datasets are subsets of the entire dataset. 88 Sub-datasets do not have to reside on the same ACAP 89 server as the dataset containing the sub-dataset 90 pointer. A site may provide an ACAP server for all 91 users, and this ACAP server may contain custom 92 bookmarks for all users. If a user decides to use 93 another ACAP server for his/her ACAP needs, one entry 94 in the user's bookmark dataset could be a sub-dataset 95 pointer back to the site-wide dataset. 97 A full dataset may also be a sub-dataset of another 98 dataset. Being a sub-dataset does not change how the 99 dataset is accessed or viewed. Sub-datasets provide 100 a way for a dataset to break up its data into smaller 101 chunks, and/or share data between datasets. 103 Entry One item in a dataset is an entry (e.g. A web 104 bookmark). An entry consists of a collection of 105 attributes. 107 Attribute The smallest piece of information in an ACAP dataset. 108 An attribute describes one aspect of an entry, and 109 consist of a few pieces of meta-data. The most 110 important meta-data is the name and a value. (e.g. 111 the name 'color' and the value 'black') 113 2. ACAP Data Model 115 This section defines all of the parts of the ACAP data model, 116 starting with the smallest piece of information. 118 2.1. Attribute / Value 120 The smallest piece of information in the ACAP data store is an 121 attribute. An attribute includes two pieces of information: a name, 122 and a value. Attributes may also have multiple values. Multiple 123 values are stored as parenthesized lists of values. The value types 124 Atom, Number, String, Parenthesized List, and NIL are defined in 125 [ACAP], section 2.6. 127 Some attributes are already defined, and are used for every entry. 128 These attributes include "entry", which is the name of the entry, 129 and "subdataset", which is used to indicate that the entry 130 represents a sub-dataset. These attributes are not necessarily 131 shown to the user. 133 The bookmark dataset [BOOK] includes the attributes 134 "bookmarks.Description", containing a user-assigned description 135 (e.g. "CMU's ACAP Page"); "bookmarks.Name", containing the name of 136 the reference (e.g. "ACAP Home Page"); and "bookmarks.URL", which is 137 the bookmarked URL (e.g. "http://asg.web.cmu.edu/acap"). In this 138 dataset, the attribute "entry" is not shown to the user, and is only 139 used as a uniquifier within the dataset itself. These attributes, 140 along with others, contain all the information needed by a client 141 regarding this bookmark. 143 The dictionary dataset [DICT] includes the attributes "entry" and 144 "dictionary.definition". The attribute "entry" may have the value 145 "spam", and is shown to the user, while the attribute 146 "dictionary.definition" may have the value "("To send multiple 147 unsolicited messages" "A meat-like substance")". 149 2.1.1. Attribute Naming Scheme 151 Attributes MUST adhere to a strict naming scheme. Attributes names 152 which do not contain a dot (".") are reserved for standardized 153 attributes which have meaning in any dataset. ("entry" and 154 "modtime", for example.) All other attributes MUST contain a dot 155 ("."), and by convention use a name of the format "Dataset.Attr", 156 where 'Dataset' is the name of the dataset, and 'Attr' is the name 157 of the attribute within the dataset. ('Attr' may contain dots.) 159 Some attributes are pre-defined, and have special meanings. These 160 attributes are: 162 entry The name of the entry within the dataset. This value 163 MUST be unique within the dataset. 165 modtime Timestamp of the last modification to anything within 166 this entry. This is generated by the server. 168 subdataset If set, this attributes indicates the existence of a 169 sub-dataset of this entry. 171 For more information on the predefined attributes, consult [ACAP], 172 section 3.1.1. 174 Attribute names are unique across all datasets. This is 175 accomplished by the attribute naming scheme: all attribute names 176 MUST be of the form ".". 178 Within the dictionary dataset, all entries contain the attribute 179 "dictionary.definition", which is a list attribute containing the 180 definition(s) of the word. Also, the attribute "entry" takes on an 181 additional meaning in the dictionary dataset: it is the word the 182 entry is for. 184 2.1.2. Searching for Specific Attributes 186 When searching an ACAP dataset, a comparison function (referred to 187 as a search comparator) must be specified, in order to handle the 188 different types of values. When searching for a specific string, 189 the "i;ascii-casemap" may be used, while when searching for a number 190 the "i;octet" comparator may be used. For more information on what 191 comparators are available, refer to [ACAP], section 3.2. 193 2.2. Entry 195 An entry is a collection of attributes, grouped together to describe 196 a common item. Entries within a dataset MUST have a unique name. 197 The design of the ACAP dataset MUST make sure this is the case. The 198 entry name does not have to have any bearing on the actual entry 199 content. (For an example of this, see the example at the end of 200 this document.) 202 It is up to the client to choose a unique name for any entries it is 203 going to create in the ACAP hierarchy. At this time, there is no 204 standard way to choose an entry name. 206 For example, when using ACAP to store a personal dictionary, the 207 entry name may be the word. Since the word may have multiple 208 definitions, the dictionary dataset has been structured to use 209 multi-valued attributes to allow clients to store multiple 210 definitions. 212 On the other hand, an ACAP entry describing a bookmark may contain 213 the URL, name, type, and last visited time. The name of the 214 bookmark entry may be an alpha-numeric uniquifier, which has no 215 meaning to the rest of the entry. 217 Another example is to compare the ACAP data store to a filesystem. 218 In this case, every entry may be considered a directory entry. The 219 contents of the files are irrelevant, and only the file attributes 220 are examined. The name of the file is unique within the dataset, 221 just like the dataset entry names, and all entries within the 222 directory have an owner, a modification time, a last accessed time, 223 and a size. 225 2.3. Dataset 227 A dataset is a collection of entries and datasets, which represent a 228 set of the information being defined. When looking at a collection 229 of bookmarks, a dataset may be defined for each of your folders of 230 bookmarks, with a top-level dataset containing all of these folders, 231 as well as any unfiled bookmarks. 233 2.3.1. Dataset Inheritance 235 Datasets may also inherit values from other datasets. Sites may 236 want to define a base set of bookmarks that all of their users see. 237 This can be accomplished by using dataset inheritance. When 238 accessing a dataset that inherits from another, the accessed dataset 239 appears to contain everything that is actually stored in it, as well 240 as what is stored in the dataset it is inheriting from. 242 For example, a site may want to have a collection of Web bookmarks 243 that are available for all users. If every user's bookmark dataset 244 is configured to inherit from the master bookmark dataset, clients 245 that fetch all of the user's bookmarks will not only see the user's 246 personal bookmarks, but also the site specific bookmarks. 248 One important thing to remember: a client can not distinguish 249 between inherited entries, and entries that are actually in the 250 dataset, unless the search that is performed specificly says not to 251 use inheritance. Designers and adminstrators MUST be careful when 252 using inheritance. 254 2.4. Dataset Class 256 A dataset class is a formal definition of a dataset. The class 257 definition describes what data is stored, where the information is 258 stored, and what format it is stored in. This allows multiple 259 applications to use the same data within the ACAP server, without 260 having to worry about breaking it for other applications. As long 261 as all applications adhere to the dataset class definition, there 262 will be no problems. 264 Standardizing dataset class definitions allows multiple applications 265 to share data, even if they are from different vendors. By defining 266 a common bookmark dataset class, all web browsers are able to share 267 their bookmarks with one another. In addition, by storing their 268 bookmarks on an ACAP server, multiple instantiations of browsers 269 across multiple computers and operating systems are able to safely 270 modify and update the list, with all other apps picking up the 271 changes as they are made. 273 2.4.1. Dataset Class Naming Scheme 275 All dataset classes have a name. The name is used to locate the 276 dataset class within the hierarchy. Dataset class names MUST either 277 be of the form "vendor.", or be specified in a 278 standards track or IESG approved experimental RFC. The proposed 279 dictionary dataset class uses the dataset class name "/dictionary", 280 while a vendor's mechanism for storing application-specific options 281 (such as window location) may be under, for example, 282 "/vendor.cyrusoft.mulberry". 284 3. Hierarchy 286 The dataset namespace is a slash-separated hierarchy. The first 287 part of the namespace is the dataset class. For standard datasets, 288 this will be the name specified by the standard, such as 289 "/bookmarks" or "/dictionary". For vendor-specific dataset classes, 290 this will be the prefix "vendor", the name of the vendor, and the 291 product, all separated by a periods. (e.g. 292 "/vendor.cyrusoft.mulberry") 294 The second part of the namespace is the ownership class, or scope of 295 the dataset. This can be "site", for server-wide datasets; "group" 296 for administrative group datasets; "host" for host specific data; or 297 "user" for a user's data. 299 If the scope is "group", "host", or "user", the third part of the 300 namespace identifier is the name of the group, host, or user. (For 301 example, "/vendor.cyrusoft.mulberry/host/lister.net.cmu.edu" would 302 be Mulberry preferences specific to the host "lister.net.cmu.edu".) 304 To fetch the bookmarks for user "ryan" on the ACAP server, the 305 dataset to be searched would be "/bookmarks/user/ryan". If "ryan" 306 is the current ACAP user, this may be abbreviated as "/bookmarks/~". 308 The dataset "/byowner" is reserved, and allows searches to show what 309 dataset classes are owned by a given user. Searching 310 "/byowner/user/ryan" will show all of the dataset classes in use by 311 user "ryan". 313 Finally, searching the dataset "/" is equivalent to searching 314 "/byowner/user/". (Or "/byowner/~"). 316 4. Bookmark Dataset Class 318 The ACAP bookmarks dataset class is defined in [BOOK]. The 319 following example contains a couple of entries in this dataset, to 320 demonstrate sub-datasets as well as give a visible example of what 321 the dataset hierarchy looks like. 323 4.1. Example 325 The following example shows what data is in ACAP, and how that data 326 may be used to generate a nice list of web bookmarks for your 327 browser. 329 4.1.1. ACAP Bookmark Dataset 331 In dataset /bookmarks/user/ryan 333 entry 104 334 bookmarks.Name "Lurkers Guide to Babylon 5" 335 bookmarks.Description "Cool site with very complete episode guides" 336 bookmarks.URL "http://www.midwinter.com/lurk" 337 bookmarks.Type "link" 339 entry 12dag8 340 bookmarks.Name "SSH (Secure Shell) Home Page" 341 bookmarks.Description "" 342 bookmarks.URL "http://www.cs.hut.fi/ssh/" 343 bookmarks.Type "link" 345 entry 13ksjhdfgpoa 346 bookmarks.Type "separator" 348 entry 14roblink 349 subdataset "acap://other.acap.domain/bookmarks/rob/public" 350 bookmarks.Name "Rob's Public Bookmarks" 351 bookmarks.Type "folder" 353 entry 15emailfoo 354 subdataset . 355 bookmarks.Name "Email Stuff" 356 bookmarks.Type "folder" 358 In dataset /bookmarks/user/ryan/Email Stuff 359 entry 2baz212 360 bookmarks.Name "ACAP Home Page" 361 bookmarks.Description "It's not LDAP" 362 bookmarks.URL "http://asg.web.cmu.edu/acap" 363 bookmarks.Type "link" 365 entry 3bar51 366 bookmarks.Name "IMAP Home Page" 367 bookmarks.Description "Protocol for fetching messages" 368 bookmarks.URL "http://asg.web.cmu.edu/cyrus" 369 bookmarks.Type "link" 371 entry 812foo 372 bookmarks.Name "Sieve Home Page" 373 bookmarks.Description "Sieve mail filtering language" 374 bookmarks.URL "http://asg.web.cmu.edu/sieve" 375 bookmarks.Type "link" 377 4.1.2. Generated Bookmarks File 379 Based on this information, the following web bookmark display can be 380 generated: 382 Lurkers Guide to Babylon 5 383 SSH (Secure Shell) Home Page 384 ---------------------------- 385 Rob's Public Bookmarks -> 386 Email Stuff -> 388 And, the "Email Stuff" folder / sub-menu would contain: 390 ACAP Home Page 391 IMAP Home Page 392 Sieve Home Page 394 5. Copyright 396 Copyright (C) The Internet Society 1999. All Rights Reserved. 398 This document and translations of it may be copied and furnished to 399 others, and derivative works that comment on or otherwise explain it 400 or assist in its implementation may be prepared, copied, published 401 and distributed, in whole or in part, without restriction of any 402 kind, provided that the above copyright notice and this paragraph 403 are included on all such copies and derivative works. However, this 404 document itself may not be modified in any way, such as by removing 405 the copyright notice or references to the Internet Society or other 406 Internet organizations, except as needed for the purpose of 407 developing Internet standards in which case the procedures for 408 copyrights defined in the Internet Standards process must be 409 followed, or as required to translate it into languages other than 410 English. 412 The limited permissions granted above are perpetual and will not be 413 revoked by the Internet Society or its successors or assigns. 415 This document and the information contained herein is provided on an 416 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 417 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 418 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 419 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 420 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 422 6. References 424 [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate 425 Requirement Levels", RFC 2119, March 1997 427 429 [ACAP] C. Newman, J. G. Myers, "Application Configuration Access 430 Protocol", RFC 2244, November 1997 432 434 [DICT] C. Daboo, "ACAP Personal Dictionary Dataset", Work In 435 Progress, March 1998 437 [BOOK] R. Gellens, "ACAP Bookmarks Dataset Class", Work In Progress, 438 December 1998 440 7. Author's Address 442 Ryan Troll 443 Computing Services 444 Carnegie Mellon 445 5000 Forbes Avenue 446 Pittsburgh, PA 15213 448 Phone: (412) 268-8691 449 EMail: ryan@andrew.cmu.edu