idnits 2.17.1 draft-ietf-acap-dataset-model-00.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 5 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 412 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 (February 16, 1999) is 9195 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-00.txt Carnegie Mellon 4 Expires August 21, 1999 February 16, 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 1. Introduction 42 The Application Configuration Access Protocol [ACAP] is designed to 43 support remote storage and access of program option, configuration, 44 and preference information. The data store model is designed to 45 allow a client relatively simple access to data, to allow new 46 information to be easily added without server reconfiguration, and 47 to promote the use of both standardized data and custom or 48 proprietary data. 50 This document explores the data store model, allowing the reader to 51 visualize what the ACAP data store actually looks like. With this 52 picture, developers will be able to design an ACAP dataset class for 53 their own applications, and interoperate with others. 55 1.1. Conventions Used in the Document 57 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 58 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 59 document are to be interpreted as described in [KEYWORDS]. 61 1.2. Terminology 63 Dataset Class A dataset class is a formal description of how to use 64 information stored within a dataset. Descriptions of 65 all attributes, and what their values mean, make up a 66 dataset class. 68 Dataset Every level of the ACAP hierarchy is a dataset. 69 Datasets contain entries, and/or other datasets. 70 Datasets may inherit entries from other datasets, or 71 be standalone repositories of information. 73 Sub-Dataset A dataset may contain pointers to other datasets. 74 These datasets are subsets of the main dataset, and 75 may contain entries that are grouped together for a 76 common reason. In a dictionary, words are grouped 77 together based on their first letter. These smaller 78 groupings are subsets of the entire dictionary, just 79 like sub-datasets are subsets of the entire dataset. 81 Sub-datasets do not have to reside on the same ACAP 82 server as the dataset containing the sub-dataset 83 pointer. A site may provide an ACAP server for all 84 users, and this ACAP server may contain custom 85 bookmarks for all users. If a user decides to use 86 another ACAP server for his/her ACAP needs, one entry 87 in the users bookmark dataset could be a sub-dataset 88 pointer back to the site-wide dataset. 90 A full dataset may also be a sub-dataset of another 91 dataset. Being a sub-dataset does not change how the 92 dataset is accessed or viewed. Sub-datasets provide 93 a way for a dataset to break up its data into smaller 94 chunks, and/or share data between datasets. 96 Entry One item in a dataset is an entry (IE: A web 97 bookmark). 98 An entry consists of a collection of attributes. 100 Attribute The smallest piece of information in an ACAP dataset. 101 An attribute describes one aspect of an entry, and 102 consist of a name and a value. (IE: the name 'color' 103 and the value 'black') 105 2. ACAP Data Model 107 This section defines all of the parts of the ACAP data model, 108 starting with the smallest piece of information. 110 2.1. Attribute / Value 112 The smallest piece of information in the ACAP data store is an 113 attribute. An attribute contains two pieces of information: a name, 114 and a value. Attributes may also have multiple values. Multiple 115 values are stored as parenthesized lists of values. The value types 116 Atom, Number, String, Parenthesized List, and NIL are defined in 117 [ACAP], section 2.6. 119 Some attributes are already defined, and are used for every entry. 120 These attributes include "entry", which is the name of the entry, 121 and "subdataset", which is used to indicate that the entry 122 represents a sub-dataset. 124 The bookmark dataset [BOOK] includes the attributes 125 "bookmarks.Description", containing a user-assigned description 126 ("CMU's ACAP Page"); "bookmarks.Name", containing the name of the 127 reference ("ACAP Home Page"); and "bookmarks.URL", which is the 128 bookmarked URL ("http://asg.web.cmu.edu/acap"). These attributes, 129 along with others, will allow clients to use and/or present the 130 bookmarks to the user. 132 The dictionary dataset [DICT] includes the attributes "entry" and 133 "dictionary.definition". The attribute "entry" may have the value 134 "spam", while the attribute "dictionary.definition" may have the 135 value "("To send multiple unsolicited messages" "A meat-like 136 substance")". 138 2.1.1. Attribute Naming Scheme 140 Attributes MUST adhere to a strict naming scheme. Attributes names 141 which do not contain a dot (".") are reserved for standardized 142 attributes which have meaning in any dataset. ("entry" and 143 "modtime", for example.) All other attributes MUST have a name of 144 the format "Dataset.Attr", where 'Dataset' is the name of the 145 dataset, and 'Attr' is the name of the attribute within the dataset. 146 ('Attr' may contain dots.) 148 Some attributes are pre-defined, and have special meanings. These 149 attributes are: 151 entry The name of the entry within the dataset. 153 modtime Timestamp of the last modification to anything within 154 this entry. 156 subdataset If set, this attributes indicates the existence of a 157 sub-dataset of this entry. 159 For more information on the predefined attributes, consult [ACAP], 160 section 3.1.1. 162 Attribute names are unique across all datasets. This is 163 accomplished by the attribute naming scheme: all attribute names 164 MUST be of the form ".". 166 Within the dictionary dataset, all entries contain the attribute 167 "dictionary.definition", which is a list attribute containing the 168 definition(s) of the word. Also, the attribute "entry" takes on an 169 additional meaning in the dictionary dataset: it is the word the 170 entry is for. 172 2.1.2. Searching for Specific Attributes 174 When searching an ACAP dataset, a comparison function (referred to 175 as a search comparator) must be specified, in order to handle the 176 different types of values. When searching for a specific string, 177 the "i;ascii-casemap" may be used, while when searching for a number 178 the "i;octet" comparator may be used. For more information on what 179 comparators are available, refer to [ACAP], section 3.2. 181 2.2. Entry 183 An entry is a collection of attributes, grouped together to describe 184 a common item. Entries within a dataset MUST have a unique name. 185 The design of the ACAP dataset MUST make sure this is the case. The 186 entry name does not have to have any bearing on the actual entry 187 content. (For an example of this, see the example at the end of 188 this document.) 190 It is up to the client to choose a unique name for any entries it is 191 going to create in the ACAP hierarchy. At this time, there is no 192 standard way to choose an entry name. 194 For example, when using ACAP to store a personal dictionary, the 195 entry name may be the word. Since the word may have multiple 196 definitions, the dictionary dataset has been structured to use 197 multi-valued attributes to allow clients to store multiple 198 definitions. 200 On the other hand, an ACAP entry describing a bookmark may contain 201 the URL, name, type, and last visited time. The name of the 202 bookmark entry may be a numeric uniquifier, which has no meaning to 203 the rest of the entry. 205 Another example is to compare the ACAP data store to a filesystem. 206 In this case, every entry may be considered a directory entry. The 207 contents of the files are irrelevant, and only the file attributes 208 are examined. The name of the file is unique within the dataset, 209 just like the dataset entry names, and all entries within the 210 directory have an owner, a modification time, a last accessed time, 211 and a size. 213 2.3. Dataset 215 A dataset is a collection of entries and datasets, which represent a 216 set of the information being defined. When looking at a collection 217 of bookmarks, a dataset may be defined for each of your folders of 218 bookmarks, with a fifth dataset containing all of these folders, as 219 well as any unfiled bookmarks. 221 2.3.1. Dataset Inheritance 223 Datasets may also inherit values from other datasets. Sites may 224 want to define a base set of bookmarks that all of their users see. 225 This can be accomplished by using dataset inheritance. When 226 accessing a dataset that inherits from another, the accessed dataset 227 appears to contain everything that is actually stored in it, as well 228 as what is stored in the dataset it is inheriting from. 230 For example, a site may want to have a collection of Web bookmarks 231 that are available for all users. If every user's bookmark dataset 232 is configured to inherit from the master bookmark dataset, clients 233 that fetch all of the user's bookmarks will not only see the user's 234 personal bookmarks, but also the site specific bookmarks. 236 One important thing to remember: a client can not distinguish 237 between inherited entries, and entries that are actually in the 238 dataset, unless the search that is performed specificly says not to 239 use inheritance. Designers and adminstrators MUST be careful when 240 using inheritance. 242 2.4. Dataset Class 244 A dataset class is a formal definition of a dataset. The class 245 definition describes what data will be stored, where the information 246 will be stored, and what format it will be stored in. This allows 247 multiple applications to use the same data within the ACAP server, 248 without having to worry about breaking it for other applications. 249 As long as all applications adhere to the dataset class definition, 250 there will be no problems. 252 Standardizing dataset class definitions allows multiple applications 253 to share data, even if they are from different vendors. By defining 254 a common bookmark dataset class, all web browsers would be able to 255 share their bookmarks with one another. In addition, by storing 256 their bookmarks on an ACAP server, multiple instantiations of 257 browsers across multiple computers and operating systems would be 258 able to safely modify and update the list, with all other apps 259 picking up the changes as they are made. 261 2.4.1. Dataset Class Naming Scheme 263 All dataset classes have a name. The name is used to locate the 264 dataset class within the hierarchy. Dataset class names MUST either 265 be of the form "vendor.", or be specified in a 266 standards track or IESG approved experimental RFC. The proposed 267 dictionary dataset class will use the dataset class name 268 "/dictionary", while a vendor's mechanism for storing application- 269 specific options (such as window location) may be under 270 "/cyrusoft.mulberry". 272 3. Hierarchy 274 The dataset namespace is a slash-separated hierarchy. The first 275 part of the namespace is the dataset class. For standard datasets, 276 this will be the name specified by the standard, such as 277 "/bookmarks" or "/dictionary". For vendor-specific dataset classes, 278 this will be the name of the vendor and the product, separated by a 279 period. (IE: "/cyrusoft.mulberry") 281 The second part of the namespace is the scope of the dataset to be 282 looked up. This can be "site", for server-wide datasets; "group" 283 for administrative group datasets; "host" for host specific data; or 284 "user" for a user's data. 286 If the scope is "group", "host", or "user", the third part of the 287 namespace identifier is the name of the group, host, or user being 288 looked up. (For example, 289 "/cyrusoft.mulberry/host/lister.net.cmu.edu" would be Mulberry 290 preferences specific to the host "lister.net.cmu.edu".) 292 To fetch the bookmarks for user "ryan" on the ACAP server, the 293 dataset to be searched would be "/bookmarks/user/ryan". If "ryan" 294 is the current ACAP user, this may be abbreviated as "/bookmarks/~". 296 The dataset "/byowner" is reserved, and allows searches to show what 297 dataset classes are owned by a given user. Searching 298 "/byowner/user/ryan" will show all of the dataset classes in use by 299 user "ryan". 301 Finally, searching the dataset "/" is equivalent to searching 302 "/byowner/user/". (Or "/byowner/~"). 304 4. Bookmark Dataset Class 306 The ACAP bookmarks dataset class is defined in [BOOK]. The 307 following example contains a couple of entries in this dataset, to 308 demonstrate sub-datasets as well as give a visible example of what 309 the dataset hierarchy looks like. 311 4.1. Example 313 The following example shows what data is in ACAP, and how that data 314 may be used to generate a nice list of web bookmarks for your 315 browser. 317 4.1.1. ACAP Bookmark Dataset 319 In dataset /bookmarks/user/ryan 320 entry 104 321 bookmarks.Name "Lurkers Guide to Babylon 5" 322 bookmarks.Description "Cool site with very complete episode guides" 323 bookmarks.URL "http://www.midwinter.com/lurk" 324 bookmarks.Type "link" 326 entry 12dag8 327 bookmarks.Name "SSH (Secure Shell) Home Page" 328 bookmarks.Description "" 329 bookmarks.URL "http://www.cs.hut.fi/ssh/" 330 bookmarks.Type "link" 332 entry 13ksjhdfgpoa 333 bookmarks.Type "separator" 335 entry 14roblink 336 subdataset "//other.acap.domain//bookmarks/rob/public" 337 bookmarks.Name "Rob's Public Bookmarks" 338 bookmarks.Type "folder" 340 entry 15emailfoo 341 subdataset . 342 bookmarks.Name "Email Stuff" 343 bookmarks.Type "folder" 345 In dataset /bookmarks/user/ryan/email-stuff 347 entry 2baz212 348 bookmarks.Name "ACAP Home Page" 349 bookmarks.Description "It's not LDAP" 350 bookmarks.URL "http://asg.web.cmu.edu/acap" 351 bookmarks.Type "link" 353 entry 3bar51 354 bookmarks.Name "IMAP Home Page" 355 bookmarks.Description "Protocol for fetching messages" 356 bookmarks.URL "http://asg.web.cmu.edu/cyrus" 357 bookmarks.Type "link" 359 entry 812foo 360 bookmarks.Name "Sieve Home Page" 361 bookmarks.Description "Sieve mail filtering language" 362 bookmarks.URL "http://asg.web.cmu.edu/sieve" 363 bookmarks.Type "link" 365 4.1.2. Generated Bookmarks File 367 Based on this information, the following web bookmark file can be 368 generated: 370 Lurkers Guide to Babylon 5 371 SSH (Secure Shell) Home Page 372 ---------------------------- 373 Rob's Public Bookmarks -> 374 Email Stuff -> 376 And, the "Email Stuff" folder / sub-menu would contain: 378 ACAP Home Page 379 IMAP Home Page 380 Sieve Home Page 382 5. Copyright 384 Copyright (C) The Internet Society 1999. All Rights Reserved. 386 This document and translations of it may be copied and furnished to 387 others, and derivative works that comment on or otherwise explain it 388 or assist in its implementation may be prepared, copied, published 389 and distributed, in whole or in part, without restriction of any 390 kind, provided that the above copyright notice and this paragraph 391 are included on all such copies and derivative works. However, this 392 document itself may not be modified in any way, such as by removing 393 the copyright notice or references to the Internet Society or other 394 Internet organizations, except as needed for the purpose of 395 developing Internet standards in which case the procedures for 396 copyrights defined in the Internet Standards process must be 397 followed, or as required to translate it into languages other than 398 English. 400 The limited permissions granted above are perpetual and will not be 401 revoked by the Internet Society or its successors or assigns. 403 This document and the information contained herein is provided on an 404 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 405 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 406 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 407 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 408 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 410 6. References 412 [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate 413 Requirement Levels", RFC 2119, March 1997 415 417 [ACAP] C. Newman, J. G. Myers, "Application Configuration Access 418 Protocol", RFC 2244, November 1997 420 422 [DICT] C. Daboo, "ACAP Personal Dictionary Dataset", Work In 423 Progress, March 1998 425 [BOOK] R. Gellens, "ACAP Bookmarks Dataset Class", Work In Progress, 426 December 1998 428 7. Author's Address 430 Ryan Troll 431 Computing Services 432 Carnegie Mellon 433 5000 Forbes Avenue 434 Pittsburgh, PA 15213 436 Phone: (412) 268-8691 437 EMail: ryan@andrew.cmu.edu