INTERNET-DRAFT J. Boynton Produx House, Corp. Expires six months from --> 5 August 1999 Uniform Object Locator -- UOL 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract A Uniform Object Locator (UOL) provides a hierarchical "human-readable" format for describing the location of any single attribute within any data object. A UOL emulates the internal structure of a data object by dividing a partial URL into two re-usable components; An object constructor and an object name. Special object elements within the constructor are used to organize directories into nested object containers. Identical object containers, using different names, are guaranteed to have the same parameter structure. The UOL format is particularly suited for retrieval and storage of parameter values through multiple object layers. Its basic construction allows it to be combined with a URL; without modification. Possible uses include distributed object management, XML, and e-business development. Boynton Expires February 2000 [page 1] INTERNET-DRAFT Uniform Object Locator 5 August, 1999 Table of Contents 1 Introduction 1.1 Purpose 1.2 Terminology 1.3 General Description 1.3.1 Construction 1.3.2 Absolute and Relative Form 1.3.3 Practical Examples 2 Objects 2.1 Root Object 2.2 Object Element 2.2.1 Assigning Names 2.2.2 Nested Objects 2.3 Group Element 2.3.1 Shared Directory 2.3.2 Group Parameter 2.4 Default Object 3 Combining UOLs 4 Embedding a UOL in a URL 5 Application Programming Interface 5.1 Group Element Interface 5.1.1 Resource Allocation 5.1.2 Extending the "NAMES" Parameter 5.2 Default Object Naming 5.3 Referencing a Comment 5.3.1 Types 5.3.2 Reserved Method 6 Author's Address 1 Introduction 1.1 Purpose The purpose of the UOL is to provide a hierarchical "human-readable" format for describing parameters within nested objects. It can be used in a full or partial form, and can be appended to the reference portion of a URL for interaction with files on a host machine. The UOL format emulates the internal structure of a data object by providing an object constructor and an object name. Special elements within the constructor are used to organize directories into nested object containers. Identical object containers, using different names, are guaranteed to have the same parameter structure. 1.2 Terminology For clarity, the specific role of elements within the UOL are defined below. element A single, un-delimited, string of characters. Boynton Expires February 2000 [page 2] INTERNET-DRAFT Uniform Object Locator 5 August, 1999 directory A typical hierarchical string of elements delimited by, and ending with, a '/' (forward slash). parameter A directory, contained by an "object", referencing a single attribute or field. constructor The full directory and/or object path described by the UOL, followed by a single attribute; where no attribute is given, the path itself. object name An ordered collection of '.' (dot) delimited elements that, when used together, provide the full name of the constructor. name element An individual element within an object name. Its value is mapped to an object element. container Any directory within a constructor. object A constructor and any segment of a constructor beginning with an object element. directory element An individual element within a constructors directory. A directory element MUST have a trailing '/' (forward slash) character. object element A directory element with an assigned name element. An object element MUST have the prefix ".." (dot, dot). group element A directory element containing a collection of object elements. 1.3 General Description 1.3.1 Construction The UOL is constructed from a hierarchical list of elements in similar fashion to a URL; with the '/' forward slash as the delimiter for directory elements. A UOL, however, does not include a protocol declaration. In addition, the reference portion of a UOL is reserved for object naming purposes. The result divides the UOL into two re-usable components; an object constructor and object name. Boynton Expires February 2000 [page 3] INTERNET-DRAFT Uniform Object Locator 5 August, 1999 1.3.2 Absolute and Relative Forms A UOL can be absolute or relative. An absolute UOL MUST contain a top level directory element equal to a single forward slash("/") with no assigned object name(a root object). A relative UOL MUST not have a forward slash as the first element in its constructor. It may, however have a prefix of "../". By convention, a UOL with the prefix "../" will resolve to the next higher directory when combined with an absolute UOL. The prefix, itself, is not considered an element of the constructor. 1.3.3 Practical Examples The following section provides simplified examples for how a UOL could be used in "real world" application. The examples given are for a fictitious company with branch offices in three cities LA, Dallas, and Tampa. Each office has, three departments: sales, accounting("ACCT"), and customer service("CS"). The example below shows a UOL referencing the total hours worked by an employee named Jones, from the sales department of the LA branch office. "/..branch/..dept/..log/hours/total#LA.sales.Jones" In the example above, "..branch", "..dept" and "..log" are nested objects. "..log" is an object modeling a detailed employee record. Because identical named objects are guaranteed to have the same parameters, the constructor can be re-used. The next example uses the same constructor to reference the total hours worked by an accounting employee at the Dallas branch. "/..branch/..dept/..log/hours/total#Dallas.ACCT.Smith" Like the constructor, object names can also be re-used. In the example below, a constructor is modified to retrieve several records for a customer service associate in Tampa. "/..branch/..dept/..log/hours/total#Tampa.CS.Carter" "/..branch/..dept/..log/hours/overtime#Tampa.CS.Carter" "/..branch/..dept/..log/hours/vacation#Tampa.CS.Carter" 2 Objects 2.1 Root Object The root object is the top level container for all objects and parameters in the UOL constructor. It does not belong to any object group and has no assigned name. The root object is always the first Boynton Expires February 2000 [page 4] INTERNET-DRAFT Uniform Object Locator 5 August, 1999 element in an absolute UOL constructor and is represented by a single forward slash("/"). 2.2 Object Element The primary difference between a URL and a UOL is the inclusion of an "Object Element". The object element declares its sub-elements to represent a data object by assigning them to an object name. Each name assigned to an object element creates a new object with identical parameters. The object element is denoted by the prefix ".." (dot dot) and, is always accompanied by a trailing "/" (forward slash). An exception to this scheme is the value "../" which has a specific meaning and is NOT considered an object element. 2.2.1 Assigning Names Each object element is assigned a name element. The name element is appended to the object name(if any) inherited from the parent director. The object name is appended to the end of the UOL following a reference character "#" (number sign). The new object name is then inherited by all sub-directories of the object element. example "/..object/sub_dir/field#name" 2.2.2 Nested Objects Any object element contained by another is a "nested" object. The name element assigned to the nested object is appended to the object name inherited from its parent. The nested name element is delimited from the object name by a '.'(dot) character. example "/..parent_object/..nested_object/field#parent_name.nested_name" 2.3 Group Element The group element represents a collection of related object elements. Its object name (if any) is inherited from the parent directory. Object elements, within the group, supply a name element to extend the group name. 2.3.1 Shared Directory The group element is defined in the same directory as the object elements it contains. This is possible because all are guaranteed to have different object names. Therefore, defining a separate directory is unnecessary. 2.3.2 Group Parameter - "~" By convention, a UOL with no attribute should return an object Boynton Expires February 2000 [page 5] INTERNET-DRAFT Uniform Object Locator 5 August, 1999 equivalent to a UOL directory. The group element, however, shares its directory with the object element. Although the two are differentiated by their object name, the names may initially be unknown to a UOL parser. For this reason, a "~" (tilde) is used as a parameter to disambiguate the two elements. Where used as a parameter, "~" must directly follow a group(object) element. Use as a parameter elsewhere is unsafe. A '~' can, however, be used in a parameter when accompanied by other characters or, within other elements. example group element = "/..object1/..object2/~#groupName" object element = "/..object1/..object2/#groupName.objectName" 2.4 Default Object The name "*" (a single asterisk) is reserved for naming a default object element. Applications use the default object as a template for creating sub-elements within a director. An XML Application, for instance, may wish to use a default object to store fields provided in a DTD(Document Type Definition). The default object also provides a container for default values. Applications that do not wish to provide this function should return a value equivalent to null when a default value is requested. 3 Combining UOLs In general, the object constructor of a UOL is resolved the same as elements within a URL. Care should be taken, however, to maintain proper relationships between object elements and their assigned names. example Where an absolute UOL is equal to: "/..object1/sub_dir/..object2/field#name1.name2" rel UOL = field_2 result = "/..object1/sub_dir/..object2/field_2#name1.name2" rel UOL = ..object3/field_3#name3 result = "/..object1/sub_dir/..object2/..object3/field_3#name1.name2.name3" rel UOL = ../field_2 result = "/..object1/sub_dir/field_2#name1" rel UOL = ../..object3/field_3#name3 result = "/..object1/sub_dir/..object3/field_3#name1.name3" rel UOL = ../sub_dir_2/field_4 result = "/..object1/sub_dir/sub_dir_2/field_4#name1" Boynton Expires February 2000 [page 6] INTERNET-DRAFT Uniform Object Locator 5 August, 1999 4 Embedding a UOL in a URL The basic form of the UOL does not declare a protocol. For interaction with files on a host machine, the UOL is embedded in a fully qualified(absolute) URL as a reference. In the example below, a '#' separates the URL from the UOL statement. example "http//www.myhost.com/mydata.xml#..object/sub_dir/field#name" This form instructs the host machine to return the entire contents of the file. A client side application is then used to retrieve the UOL value from the file. The use of multiple '#' (reference) characters is not ambiguous because the URL MUST declare a protocol. Therefore, ownership of the reference character is easily determined. NOTE If this use of the '#' character is deemed illegal, an alternate embedded form should use a '?'(question mark) as a separator (URL?UOL). 5 Application Programming Interface This section proposes an API (Application Programming Interface) that extends the capabilities of a UOL for practical use in application development. 5.1 Group Element Interface Applications can use the group element in two important way. First, as a reference to a list of named elements contained by the group and second, as a general reference to all objects in the collection. To provide this functionality, the UOL specification reserves two parameters "NAMES" and "~" (a single tilde). 5.1.1 Resource Allocation The parameter "NAMES" (all uppercase) is reserved for resource allocation purposes. The word is reserved only when used as a parameter and only in all uppercase form. Mixed case or lowercase use is unreserved. Where used as a parameter, "NAMES" must directly follow a group(object) element. Use of this parameter elsewhere is unsafe. example UOL = "/..ObjectGroup/NAMES#" The parameter, itself, is a reference to a ',' comma delimited string of names. Each name represents a named object element in the group. The names provided in the string are extensions to the name inherited from the group element. The full object name is represented by a combination of the two. An application uses this list to allocate resources and/or perform special functions prior to loading data. Boynton Expires February 2000 [page 7] INTERNET-DRAFT Uniform Object Locator 5 August, 1999 example UOL = "/..Object/NAMES#" Value = "name1, name2, name3" Result = "/..Object/#name1"|"/..Object/#name2"|"/..Object/#name3" 5.1.2 Extended Use In addition to providing a reference to object names, the "NAMES" parameter can be extended to provide instructions on how the names are used. The extended form appends a "." (dot) to the end of the parameter; followed by a statement. The statement used can be any string of safe and unreserved characters that will be understood by the host application. Three hypothetical examples are given below. examples "/..ObjectGroup/NAMES.add#" - add the list to an existing group of names. "/..ObjectGroup/NAMES.subtract#" - subtract the list from an existing group. "/..ObjectGroup/NAMES.Vector#" - import names from a binary Vector object 5.2 Default Object Naming A UOL parser should provide default names where name elements have been omitted. By doing so, an object constructor, by itself, can be used to return a default value. This feature provides advantages when loading templates or DTD. In the first example below, default names are added to a UOL that declares two object elements. In the second example, a UOL declares two object elements and one name. However, the "NAMES" parameter indicates the last object is a group element. Therefore, a default name is not required. example UOL = "/..object1/..object2/field#*.*" UOL = "/..object1/..object2/NAMES#name1" 5.3 Referencing a Comment The character '!' (exclamation point) is reserved for referencing a "comment". When the first character in a UOL String is equal to '!', the value referenced is a discriptor attached to the actual value. The comment argument is intended to provide specific details, such as: object type, format, general characteristics, or formulas. 5.3.1 Types A comment can be any String argument or any binary object that can be readily converted to a String value by the client application. If a comment is represented by a binary object, the objects String Boynton Expires February 2000 [page 8] INTERNET-DRAFT Uniform Object Locator 5 August, 1999 value MUST be suitable for reverse parsing to an equivalent object form. Where a comment value is not provided, an application should assign a value equivalent to null. 5.3.2 Reserved Method An '!' at the beginning of a UOL is a generic comment marker that MUST be supported. However, applications may store and retrieve comments using any method that will produce a valid result. The reserved method adds a '!' character to the beginning of the last parameter element in a constructor. Although the alternate syntax is reserved (to avoid naming conflicts), applications do not have to support the method itself. example generic syntax = "!/..object1/sub_dir/field_2#name1" alternate syntax = "/..object1/sub_dir/!field#name1" 6 Author's Address Jon L. Boynton Produx House, Corp. 19300 Nalle Rd. North Ft.Myers, FL 33917 Phone 941 543 4491 Email jon@datamessenger.com Boynton Expires February 2000 [page 9]