HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 08:36:28 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Thu, 05 Feb 1998 14:24:00 GMT ETag: "323c11-ffe9-34d9cb80" Accept-Ranges: bytes Content-Length: 65513 Connection: close Content-Type: text/plain Service Location Working Group Erik Guttman INTERNET DRAFT Charles Perkins James Kempf 2 February 1998 Sun Microsystems Service Templates and service: Schemes draft-ietf-svrloc-service-scheme-07.txt Status of This Memo This document is a submission by the Service Location Working Group of the Internet Engineering Task Force (IETF). Comments should be submitted to the srvloc@corp.home.net mailing list. Distribution of this memo is unlimited. 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 learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (North Europe), ftp.nis.garr.it (South Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Abstract The ''service:'' URL scheme name is used to define URLs (called ''service: URLs'' in this document) that are primarily intended to be used by the Service Location Protocol in order to distribute service access information. These schemes provide an extensible framework for client-based network software to obtain configuration information required to make use of network services. When registering a service: URL, the URL is accompanied by a set of well-defined attributes which define the service. These attributes convey configuration information to client software, or service characteristics meaningful to end users. This document describes a formal procedure for defining and standardizing new service types and attributes for use with the Guttman,Perkins,Kempf Expires 2 August 1998 [Page i] Internet Draft Service Templates and URLs 2 February 1998 ''service:'' scheme. The formal descriptions of service types and attributes are templates that are human and machine understandable. They SHOULD be used by administrative tools to parse service registration information and by client applications to provide localized translations of service attribute strings. Guttman,Perkins,Kempf Expires 2 August 1998 [Page ii] Internet Draft Service Templates and URLs 2 February 1998 Contents Status of This Memo i Abstract i 1. Introduction 2 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Service Location Protocol . . . . . . . . . . . . . . . . 4 2. Service URL Syntax and Semantics 4 2.1. Service URL Syntax . . . . . . . . . . . . . . . . . . . 4 2.2. Service URL Semantics . . . . . . . . . . . . . . . . . . 5 2.3. Use of service: URLs . . . . . . . . . . . . . . . . . . 7 2.4. Specifying the Service Type-Specific URL Syntax . . . . . 7 2.5. Abstract Service Types . . . . . . . . . . . . . . . . . 8 2.5.1. Advertising Abstract Service Types . . . . . . . 8 3. Service Templates 9 3.1. Syntax of Service Type Templates . . . . . . . . . . . . 10 3.2. Semantics of Service Type Templates . . . . . . . . . . . 12 3.2.1. Definition of a Service Template . . . . . . . . 13 3.2.2. Service Type . . . . . . . . . . . . . . . . . . 13 3.2.3. Version Number . . . . . . . . . . . . . . . . . 13 3.2.4. Service Type Language . . . . . . . . . . . . . . 14 3.2.5. Description . . . . . . . . . . . . . . . . . . . 14 3.2.6. Syntax of the Service Type-specific URL Part . . 14 3.2.7. Attribute Definition . . . . . . . . . . . . . . 15 4. A Process For Standardizing New Service Types 19 5. IANA Considerations 20 6. Internationalization Considerations 21 6.1. Language Identification and Translation . . . . . . . . . 21 7. Security Considerations 22 A. Service Template Examples 22 A.1. FOO . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 A.2. Abstract Service Type: Net-Transducer . . . . . . . . . 23 A.3. Concrete Service Type: Net-Transducer:Thermometer . . . 24 A.4. service: URLs and SLP . . . . . . . . . . . . . . . . . . 25 B. Full Copyright Statement 27 Guttman,Perkins,Kempf Expires 2 August 1998 [Page 1] Internet Draft Service Templates and URLs 2 February 1998 C. Acknowledgments 27 1. Introduction This document describes a URL scheme, called service: URL, which uses a formal notation to define network access information for network services. In addition it describes how to define a set of attributes to associate with a service: URL. These attributes will allow end users and programs to select between network services of the same type that have different capabilities. The attributes are defined in a template document that is readable by people and machines. A client uses attributes to select a particular service. Service selection occurs by obtaining the service: URL that offers the right configuration for the client. Service type templates define the syntax of service: URLs for a particular service type, as well as the attributes which accompany a service: URL in a service registration. Templates are used for the following purposes: Standardization The template is reviewed before it is standardized. Once it is standardized, all versions of the template are archived by IANA. Service Registration Servers making use of the Service Location Protocol [12] register themselves and their attributes. They use the templates to generate the service registrations. In registering, the service must use the specified values for its attributes. Client presentation of Service Information Client applications may display service information. The template provides type information and explanatory text which may be helpful in producing user interfaces. Internationalization Entities with access to the template for a given service type in two different languages may translate between the two languages. A service may register itself in more than one language using templates, though it has been configured by an operator who registered service attributes in a single language. Guttman,Perkins,Kempf Expires 2 August 1998 [Page 2] Internet Draft Service Templates and URLs 2 February 1998 All grammar encoding follows the Augmented BNF (ABNF) [8] for syntax specifications. 1.1. Terminology This section introduces the following terminology: service scheme A URL scheme whose name starts with the string "service:" and is followed by the service type name, constructed according to the rules in this document. An example is "service:lpr:" for the lpr print service [11]. service: URL A URL constructed according to the service scheme definition. It typically provides at least the following: The name of an access protocol, and an address locating this service. The service: URL may include url path information specific to the type of service, as well as attribute information encoded according to the URL grammar. The service: URL is used by the Service Location Protocol to register and discover the location of services. It may be used by other protocols and in documents as well. service type A name identifying the semantics by which the remainder of the service: URL is to be understood. It may denote either a particular network protocol, or an abstract service associated with a variety of protocols. If the service type denotes a particular protocol, then the service type name SHOULD either be assigned the name of a particular well known port [2] by convention or be the Assigned Numbers name for the service [1]. abstract service type A service type name which is associated with a variety of different protocols. An example is given in Appendix A. Section 2 discusses various ways that abstract types can be accommodated. service registration A service: URL and optionally a set of attributes comprise a service registration. This registration is made by or on Guttman,Perkins,Kempf Expires 2 August 1998 [Page 3] Internet Draft Service Templates and URLs 2 February 1998 behalf of a given service. The URL syntax and attributes must conform to the service template for the registered service. service template A formal description of the service attributes and service scheme associated with a particular service type. 1.2. Service Location Protocol The Service Location Protocol [12] allows service: URLs to be registered and discovered. Service: URLs may be also used in other contexts. Client applications discover service registrations by issuing queries for services of a particular type, specifying the attributes of the service: URLs to return. Services may register themselves, or registrations may be made on their behalf. These registrations contain a service: URL, and possibly attributes and digital signatures. 2. Service URL Syntax and Semantics This section describes the syntax and semantics of service: URLs. 2.1. Service URL Syntax The syntax of the service: URL MUST conform to [5]. Moreover, the field has been omitted from the production, since plaintext transmission of passwords is discouraged. The field is the service access point, and describes how to access the service. Note that the syntax for the field depends upon the service type definition. In addition, although both upper case and lower case characters are recognized in the field for convenience, the name is case-folded into lower case. Service types are therefore not distinguished on the basis of case, so, for example, "http" and "HTTP" designate the same service type. This is consistent with general URL practice, as outlined in [6]. The ABNF for a service: URL is: service: URL = "service:" service-type ":" sap service-type = abstract-type ":" url-scheme / concrete-type abstract-type = type-name [ "." naming-auth ] concrete-type = protocol [ "." naming-auth ] type-name = resname Guttman,Perkins,Kempf Expires 2 August 1998 [Page 4] Internet Draft Service Templates and URLs 2 February 1998 naming-auth = resname url-scheme = resname ; A recognized URL scheme name, standardized ; either through common practice or through ; approval of a standards body. resname = alpha [ 1*(alpha / digit / "+" / "-") ] sap = "//" site [ url-part ] site = [ [ user "@" ] hostport ] hostport = host [ ":" port ] host = hostname / hostnumber hostname = *( domainlabel "." ) toplabel alphanum = alpha / digit domainlabel = alphanum / alphanum *[alphanum / "-"] alphanum toplabel = alpha / alpha *[ alphanum / "-" ] alphanum hostnumber = ipv4-number / ipv6-number ipv4-number = 1*3digit 3("." 1*3digit) ipv6-number = 32hex 3digit = digit digit digit port = 1*digit ; A port number must be included if the ; protocol field does not have an IANA ; assigned port number. user = *[ uchar / ";" / "+" / "&" / "=" ] url-part = [ url-path ] [ attr-list ] url-path = 1 * ( "/" *xchar ) ; Each service type must define its own ; syntax consistent with [5]. attr-list = 1 * ( ";" attr-asgn ) attr-asgn = attr-id / attr-id "=" attr-value safe = "$" / "-" / "_" / "." / "~" extra = "!" / "*" / "'" / "(" / ")" / "," / "+" uchar = unreserved / escaped xchar = unreserved / reserved / escaped escaped = "%" hex hex hex "a" / "b" / "c" / "d" / "e" / digit reserved = ";" / "/" / "?" / ":" / "@" / "&" / "=" / "+" unreserved = alpha / digit / safe / extra Certain characters must be escaped before use. To escape any character, precede the two digits indicating its ASCII value by '%'. 2.2. Service URL Semantics The service scheme-specific information following the "service:" URL scheme identifier provides information necessary to access the service. As described in the previous subsection, the form of a service: URL is as follows: Guttman,Perkins,Kempf Expires 2 August 1998 [Page 5] Internet Draft Service Templates and URLs 2 February 1998 service: URL = "service:"":" where has the following form: ///url-path;attr-list As discussed in Section 1, the can be either a concrete protocol name, or an abstract type name. The field includes a site specification (the field) in the format specified by [5]. The field is typically either a domain name (DNS) or an IP network protocol address for the service, and possibly a port number. Note that use of DNS hostnames is preferred for ease of renumbering. The field allows more information to be provided (by way of and ) that can uniquely locate the service or resource if the is not sufficient for that purpose. An field MAY appear at the end of the field, but is never required to exist in any service location registration. The field is composed of a list of semicolon (";") separated attribute assignments of the form: attr-id "=" attr-value or for keyword attributes: attr-id Attributes are part of service: URLs when the attributes are required to access a particular service. For instance, an ACAP [10] service might require that the client authenticate with it through Kerberos. Including an attribute in the service registration allows the ACAP client to make use of the correct SASL [9] authentication mechanism. The ACAP server's registration might look like: service:acap://some.where.net;authentication=KERBEROSV4 Note that there can be other attributes of an ACAP server which are not appropriate to include in the URL. For instance, the list of users who have access to the server is useful for selecting an ACAP server, but is not required for a client to use the registered service. Attributes associated with the service: URL are not typically included in the service: URL. They are stored and retrieved using other mechanisms. The service: URL is uniquely identified with a particular service agent or resource, and is used when registering or Guttman,Perkins,Kempf Expires 2 August 1998 [Page 6] Internet Draft Service Templates and URLs 2 February 1998 requesting the attribute information. The Service Location Protocol specifies how such information is registered by network services and obtained by client software. 2.3. Use of service: URLs A service: URL enables application agents to use a standardized dynamic service access point discovery mechanism. Service: URLs SHOULD be selected according to the suitability of associated attributes. A client application can distinguish the most preferable among several services of the same type by means of their attributes. The client then uses the service: URL to communicate directly to a service. Attributes are specified with a formal service template syntax described in Section 3. If a service: URL registration includes attributes, the registering agent SHOULD also keep track of the attributes which characterize the service. Registrations can be checked against the formal attribute specification defined in the template by the client or agent representing the client. Service registration are typically done using the Service Location Protocol [12] (SLP). SLP provides a mechanism for service: URLs to be obtained dynamically, according to the service's attributes. It is also possible to obtain service: URLs from documents and using other protocols. In this case, the URL may not be accompanied by the service attributes. The context in which the URL appears should make it clear, if possible, when the service is appropriate to use. For example, in a mail message, a service might be recommended for use when the user is in a branch office. Or, an HTML document might include a service: URL as a pointer to a service, describing in text what the service does and who is authorized to use it. 2.4. Specifying the Service Type-Specific URL Syntax When a service type is specified, the specification includes the definition of the syntax for all URLs that are registered by services of that particular type. For instance, the "lpr" service type may be defined with service: URLs in the following form: service:printer:lpr://
/ The section of the URL after the address of the printer: "/" Guttman,Perkins,Kempf Expires 2 August 1998 [Page 7] Internet Draft Service Templates and URLs 2 February 1998 is specific to the lpr service type and corresponds to the field of the general service: URL syntax. This part is specified when the lpr service type is specified. 2.5. Abstract Service Types An abstract service type is a service type that can be implemented by a variety of different service agents. In order to register a service: URL for an abstract service type, the 'abstract-type' grammar rule described in section 3.1 is used. This will result in a URL which includes enough information to use the service, namely, the protocol, address and path information. Unlike 'concrete' service: URLs, however, the service type is not enough to determine the service access. Rather, an abstract service type denotes a class of service types. 2.5.1. Advertising Abstract Service Types Some services may make use of several protocols that are in common use and are distinct services in their own right. In these cases an abstract service type is appropriate. What is essential is that all the required information for the service is clearly defined. For example, suppose a network service is being developed for dynamically loading device drivers. The client requires the following four pieces of information before it can successfully load and execute the driver: 1. The protocol used to load the driver code, for example, "ftp", "http" or "tftp" 2. A pathname identifying where the driver code is located, for example "/systemhost/drivers/diskdrivers.drv", 3. The name of the driver, for example, "scsi". 4. The name of the platform, for example, "sys3.2-rs3000". The temptation is to form the first two items into a URL and embed that into a service: URL. As an example which should be avoided, service:ftp://x3.bean.org/drivers/diskdrivers.drv;driver=scsi; platform=sys3.2-rs3000 is a service: URL which seems to indicate where to obtain the driver. Guttman,Perkins,Kempf Expires 2 August 1998 [Page 8] Internet Draft Service Templates and URLs 2 February 1998 Rather, an abstract service-type SHOULD be used. The service type is not "ftp", as the example indicates. Rather, it is "device-drivers". The service: URL that should be used, consistent with the rules in section [6], is the following: service:device-drivers:ftp://x3.bean.org/drivers/diskdrivers.drv; driver=scsi;platform=sys3.2-rs3000 Other URLs for the same service using other protocols are also supported, as in: service:device-drivers:tftp://x2.bean.org/vol3/disk/drivers.drv; driver=scsi;platform=sys3.2-rs3000 service:device-drivers:http://www.bean.org/drivers/drivpak.drv; driver=scsi;platform=sys3.2-rs3000 Using Service Location Protocol, a service request for the service type "device-drivers" may return all of the three URLs listed above. The attributes associated with the services desired are used to formulate the queries, as: = service:device-drivers = (& (driver=scsi)(platform=sys3.2-rs3000)) This query will return all three URLs listed above. If only the 'tftp' URL was desired, would be set to "service:device-drivers:tftp". The fundamental requirement is that the abstract service type MUST specify enough information to access the service. In every case, a well-specified abstract type will include either an access protocol and a network address where the service is available, or an embedded URL for a standardized URL scheme that describes how to access the service. In the example above, there are three further requirements: A URL path is included for access protocols indicating the document to download, and two attributes are included to characterize the driver. 3. Service Templates Service templates are documents in a formal syntax defining properties important to service registration. These properties are: 1. General information on the service type specification itself, 2. The syntax of the service type-specific part of the service URL, Guttman,Perkins,Kempf Expires 2 August 1998 [Page 9] Internet Draft Service Templates and URLs 2 February 1998 3. The definition of attributes associated with a service. The service type specification document is the service type template. The following subsections describe the syntax and semantics of service type templates. 3.1. Syntax of Service Type Templates Service template documents are encoded in a simple form. They may be translated into any language or character set, but the template used for standardization MUST be encoded in the ASCII subset of UTF8 [13] and be in English. A template document begins with a block of text assigning values to five document identification items. The five identification items can appear in any order within the block, but conventionally the "type" item, which assigns the service type name, occurs at the very top of the document in order to provide context for the rest of the the document. The attribute definition item occurs after the document identification items. All items end with a blank line. The reserved characters are ";", "%", "=", ",", "#", LF, and CR. Reserved characters MUST be escaped. The escape sequence is the same as described in [5]. The service template is encoded in a UTF8 character set, but submitted as a part of an internet-draft, which is encoded in ASCII characters. All characters which are outside of the ASCII range MUST be escaped using the % HEX HEX syntax. For example, the letter e accent aigue would be represented as "%c3%a9". Unfortunately, this will detract from the readability of the service template in the internet draft. Hopefully some public domain tools will emerge for translating escaped UTF8 characters into humanly readable ones. Values in value lists are separated by commas. A value list is terminated by a newline not preceded by a comma. If the newline is preceded by a comma, the value list is interpreted to continue onto the next line. Attribute identifiers, attribute type names, and flags are all case insensitive. For ease of presentation, upper and lower case characters can be used to represent these in the template document. Newlines are significant in the grammar. They delimit one item from another, as well as separating parts of items internally. String values are considered to be a sequence of non-whitespace tokens potentially with embedded whitespace, separated from each Guttman,Perkins,Kempf Expires 2 August 1998 [Page 10] Internet Draft Service Templates and URLs 2 February 1998 other by whitespace. Commas delimit lists of strings. String values are trimmed so as to reduce any sequence of white space interior to a string to a single white space. Preceding or trailing white space is removed. For example: " some value , another example " is trimmed to "some value" and "another example". Note that there can be no ambiguity in string tokenization because values in value lists are separated by a comma. String tokens are not delimited by double quotes (") as is usually the case with programming languages. Attribute tags and values are useful for directory look-up. In this case, decoding of character escapes and trimming white space MUST be performed before string matching. In addition, string matching SHOULD be case insensitive. Templates obey the following ABNF [8] grammar: template = tem-attrs attr-defs tem-attrs = schemetype schemevers schemelang schemetext schemeurl schemetype = "type" "=" scheme termdef schemevers = "version" "=" version-no termdef schemelang = "language" "=" langtag termdef schemetext = "description" "=" newline desc-text termdef schemeurl = "url-syntax" "=" newline url-bnf termdef url-bnf = *[ com-chars ] ; An ABNF describing the production ; in the service: URL grammar of Section 2.1. scheme = service-type [ "." naming-auth ] service-type = scheme-name naming-auth = scheme-name scheme-name = alpha [1*schemechar] [ "." 1*schemechar ] schemechar = alpha / digit / "-" / "+" / version-no = 1*digit "." 1*digit langtag = 2*lower-alpha ;see [3] desc-text = *[ com-chars ] ; A block of free-form text for reading by ; people describing the service in a short, ; informative manner. termdef = newline newline attr-defs = *( attr-def / keydef ) attr-def = id "=" attrtail Guttman,Perkins,Kempf Expires 2 August 1998 [Page 11] Internet Draft Service Templates and URLs 2 February 1998 keydef = id "=" "keyword" newline [help-text] newline attrtail = type flags newline [value-list] [help-text] [value-list] newline id = 1*attrchar type = "string" / "integer" / "boolean" / "opaque" flags = ["m"/"M"] ["l"/"L"] ["o"/"O"] ["x"/"X"] value-list = value newline / value "," value-list / value "," newline value-list help-text = 1*( "#" help-line ) ; A block of free-form text for reading by ; people describing the attribute and ; its values. help-line = *[ com-chars ] newline attrchar = schemechar / ":" / "_" / "$" / "~" / "@" / "." / "|" / "<" / ">" / "*" / "&" value = string / integer / boolean / opaque string = safe-char *[safe-char / white-sp] safe-char integer = [ "+" | "-" ] 1*digit boolean = "true" / "false" opaque = 1*digit ":" 4*radix64-char ; The digits define the original length of ; the opaque value. The restricted character ; string is the radix-64 encoding of the ; opaque value( [7], Sect. 6.8.) ; Newlines are ignored in decoding radix-64 ; values. com-chars = safe-char / white-sp / "," / ";"/ "%" safe-char = attrchar / escaped / " " / "!" / '"' / "'" / "|" / "(" / ")" / "+" / "-" / "." / ":" / "=" / "?" / "[" / "]" / "{" / "/" / "{" / "$" ; All UTF8 printable characters are ; included except ",", "%", ";", and "#". escaped = "%" hex hex hex = digit / "A" / "B" / "C" / "D" / "E" / "a" / "b" / "c" / "d" / "e" white-sp = space / tab newline = CR / ( CR LF ) 3.2. Semantics of Service Type Templates The service type template defines the service attributes and service: URL syntax for a particular service type. The attribute definition includes the attribute type, default values, allowed values and other information. Guttman,Perkins,Kempf Expires 2 August 1998 [Page 12] Internet Draft Service Templates and URLs 2 February 1998 3.2.1. Definition of a Service Template There are six items included in the service template. The semantics of each item is summarized below. type The scheme name of the service scheme. The scheme name consists of the service type name and an optional naming authority name, separated from the service type name by a period. See 3.2.2 for the conventions governing service type names. version The version number of the service type specification. language The language of the service type specification. description A description of the service suitable for inclusion in text read by people. url-syntax The syntax of the service type-specific URL part of the service: URL. attribute definitions A collection of zero or more definitions for attributes associated with the service in service registrations. Each of the following subsections deals with one of these items. 3.2.2. Service Type The service scheme consists of the service type name and an optional naming authority name separated from the service type name by a period. The service scheme is a string that is appended to the 'service:' URL scheme identifier, and is the value of the "type" item in the template document. If the naming authority name is absent it is assumed to be IANA. 3.2.3. Version Number The version number of the service type template is the value of the "version" item. A draft proposal starts at 0.0, and the minor number increments once per revision. A standardized template starts at 1.0. Additions of optional attributes add one to the minor number, and additions of required attributes, changes of definition, or removal of attributes add one to the major number. The intent is that an old service template still accurately, if incompletely, defines the Guttman,Perkins,Kempf Expires 2 August 1998 [Page 13] Internet Draft Service Templates and URLs 2 February 1998 attributes of a service registration if the template only differs from the registration in its minor version. See Section 4 for more detail on how to use the version attribute. 3.2.4. Service Type Language The service type language is a RFC 1766 Language Tag defining the language of the template [3] and is the value of the "language" item. 3.2.5. Description The description is a block of text readable by people in the language of the template and is the value of the "description" item. It should be sufficient to identify the service to human readers and provide a short, informative description of what the service does. If the service type corresponds to a particular protocol, the protocol specification must be cited here. The protocol need not be a standardized protocol. The template might refer to a proprietary specification, and refer the reader of the template to a contact person for further information. 3.2.6. Syntax of the Service Type-specific URL Part The syntax of the service type-specific part of the service: URL is provided in the template document as the value of the "url-syntax" item. The field of the service: URL is designed to provide additional information to locate a service when the field is not sufficient. The field distinguishes URLs of a particular service type from those of another service type. For instance, in the case of the lpr service type, the must include the queue name [11], but other service types may not require this information. The syntax for the field MUST accompany the definition of a new service type, unless the URL scheme has already been standardized and is not a service: URL. The syntax is included in the template document as an ABNF [8] following the rules for URL syntax described in [5]. The field can be very simple, or even omitted. If the URL scheme has already been standardized, the "url-syntax" item SHOULD include a reference to the appropriate standardization documents. Abstract service types may defer this field to the template documents describing their concrete instances. Guttman,Perkins,Kempf Expires 2 August 1998 [Page 14] Internet Draft Service Templates and URLs 2 February 1998 3.2.7. Attribute Definition The bulk of the template is typically devoted to defining service type-specific attributes. An attribute definition precisely specifies the attribute's type, other restrictions on the attribute (whether it is multi-valued, optional, etc), some text readable by people describing the attribute, and lists of default and allowed values. The only required information is the attribute's type, the rest are optional. Registration, deregistration and the use of attributes in queries can be accomplished using the Service Location Protocol [12] or other means. Attributes are used to convey information about a given service for purposes of differentiating different services of the same type. They convey information to be used in the selection of a particular service to establish communicate with, either through a program offering a human interface or programmatically. Attributes can be encoded in different character sets and in different languages. The procedure for doing this is described in Section 6. An attribute definition begins with the specification of the attribute's identifier and ends with a single empty line. Attributes definitions have five components (in order of appearance in a definition): 1. An attribute identifier (the name of the attribute), 2. Attribute descriptors (type and flags), 3. An optional list of values which are assigned to the attribute by default, 4. An optional block of text readable by people providing a short, informative description of the attribute, 5. An optional list of allowed values which restrict the value or values the attribute can take on. 3.2.7.1. The Attribute Identifier An attribute definition starts with the specification of the attribute's identifier. The attribute's identifier serves as the name of the attribute. Note that the characters used to compose an attribute identifier are restricted to those characters considered unrestricted for inclusion in a URL according to [5]. The reason is that services can display prominent attributes in their service: URL registrations. Each attribute identifier must be unique in the Guttman,Perkins,Kempf Expires 2 August 1998 [Page 15] Internet Draft Service Templates and URLs 2 February 1998 template. Since identifiers are case folded, upper case and lower case characters are the same. 3.2.7.2. The Attribute Type Attributes can have one of five different types: string, signed integer, boolean, opaque, or keyword. The attribute's type specification is separated from the attribute's identifier by an equal sign ("=") and follows the equal sign on the same line. The string, signed integer, and boolean types have the standard programming language or database semantics. Integers are restricted to those signed values that can be represented in 32 bits. Booleans are either TRUE or FALSE. Opaques are radix64 numbers [7] that can be used to represent any other kind of data. Keywords are attributes that have no characteristics other than their existence (and possibly the descriptive text in their definition). Keyword and boolean attributes impose restrictions on the following parts of the attribute definition. Keyword attribute definitions MUST have no flag information following the type definition, nor any default or allowed values list. Boolean attributes are single value only, i.e., multi-valued boolean attributes are not allowed. 3.2.7.3. Attribute Flags Flags determine other characteristics of an attribute. With the exception of keyword attributes, which may not have any flags, flags follow the attribute type on the same line as the attribute identifier, and are separated from each other by whitespace. Flags may appear in any order after the attribute type. Other information must not follow the flags, and only one flag identifier of a particular flag type is allowed per attribute definition. The semantics of the flags are as follows: - o or O Indicates that the attribute is optional. If this flag is missing, the attribute is required in every service registration. - m or M Indicates that the attribute can take on multiple values. If this flag is present, every value in a multi-valued attribute has the same type as the type specified in the type part of the attribute definition. Boolean attributes must not include this flag. Guttman,Perkins,Kempf Expires 2 August 1998 [Page 16] Internet Draft Service Templates and URLs 2 February 1998 - l or L Indicates that attribute is literal, i.e., is not meant to be translated into other languages. If this flag is present, the attribute is not necessarily human-readable, and should not be translated when the template is translated. See Section 6 for more information about translation. - x or X Indicates that clients SHOULD include the indicated attribute in requests for services. Neglecting to include this attribute will not sufficiently differentiate the service. If services are obtained without selecting this attribute they will quite likely be useless to the client. The values for multivalued attributes are an unordered set. Deletions of individual values from a multivalued attribute are not supported, and deletion of the attribute causes the entire set of values to be removed. 3.2.7.4. Default Value or List If the attribute definition includes a default value or, in the case of multivalued attributes, a default values list, it begins on the second line of the attribute definition and continues over the following lines until a line ends without a comma. Newlines cannot be embedded in values unless escaped. See Section 2.1. Particular attribute types and definitions restrict the default values list. Keyword attributes MUST NOT have a list of defaults. If an optional attribute's definition has an allowed values list, then a default value or list is REQUIRED. The motivation for this is that defining an attribute with an allowed values list is meant to restrict the values the attribute can take on, and requiring a default value or list assures that the default value is a member of the given set of allowed values. The default value or list indicates what values the attribute is given if no values are assigned to the attribute when a service is registered. If an optional attribute's definition includes no default value or list, the following defaults are assigned: 1. String values are assigned the empty string, 2. Integer values are assigned zero, 3. Boolean values are assigned false, Guttman,Perkins,Kempf Expires 2 August 1998 [Page 17] Internet Draft Service Templates and URLs 2 February 1998 4. Opaque values are assigned a byte array containing no values, 5. Multi-valued attributes are initialized with a single value. For purposes of translating nonliteral attributes, the default values list is taken to be an ordered set, and translations MUST maintain that order. 3.2.7.5. Descriptive Text Immediately after the default values list, if any, a block of descriptive text SHOULD be included in the attribute definition. This text is meant to be readable by people, and should include a short, informative description of the attribute. It may also provide additional information, such as a description of the allowed values. This text is primarily designed for display by interactive browsing tools. The descriptive text is set off from the surrounding definition by a crosshatch character ("#") at the beginning of the line. The text should not, however, be treated as a comment by parsing and other tools, since it is an integral part of the attribute definition. Within the block of descriptive text, the text is transferred verbatim, including indentation and line breaks, so any formatting is preserved. 3.2.7.6. Allowed Values List Finally, the attribute definition concludes with an optional allowed values list. The allowed values list, if any, follows the descriptive text, or, if the descriptive text is absent, the initial values list. The syntax of the allowed values list is identical to that of the initial values list. The allowed values list is also terminated by a line that does not end in a comma. If the allowed values list is present, assignment to attributes is restricted to members of the list. As with the default values list, the allowed values list is also considered to be an ordered set for purposes of translation. 3.2.7.7. Conclusion of An Attribute Definition An attribute definition concludes with a single empty line. Guttman,Perkins,Kempf Expires 2 August 1998 [Page 18] Internet Draft Service Templates and URLs 2 February 1998 4. A Process For Standardizing New Service Types New service types can be suggested simply by providing a service type template and a short description about how to use the service. The template MUST have its "version" template attribute set to 0.0. MAJOR revision numbers come before the '.', MINOR revision numbers come after the '.'. The minor version number increments once with each change until it achieves 1.0. There is no guarantee any version of the service template is backward compatible before it reaches 1.0. Once a service template has reached 1.0, the definition is "frozen" for that version. New templates must be defined, of course, to refine that definition, but the following rules must be followed: A MINOR revision number signifies the introduction of a compatible change. A MAJOR revision number signifies the introduction of an incompatible change. This is formalized by the following rules: - Any new optional attribute defined for the template increases the minor version number by one. All other attributes for the version must continue to be supported as before. A client which supports 1.x can still use later versions 1.y (where x "." "." Each of these fields are defined in Section 2. They correspond to the values of the template fields "type", "version" and "lang". The files for the example templates in this document are called "foo.0.0.en", "Net-Transducer.0.0.en" and "Net-Transducer:Thermomoter.0.0.en". See Section A. The reviewer will ensure that the template submission to IANA has the correct version number in the "version" and "lang" fields. No service type template will be accepted for inclusion in the service template registry unless the Internet Draft submitted Guttman,Perkins,Kempf Expires 2 August 1998 [Page 20] Internet Draft Service Templates and URLs 2 February 1998 includes a security considerations section and contact information for the template document author. The IANA will maintain a registry containing both the service type templates, and the template description document containing the service type template, including all previous versions. The IANA will receive notice by email from the reviewers, which will contain a reference to the Internet Draft that contains the service template. This Internet Draft will be edited to remove the Internet Draft headers and replace them with a simple header stating "This document contains a Service Type Template." Neither the reviewer nor the IANA will take any position on claims of copyright or trademark issues with regard to templates. 6. Internationalization Considerations The service: URL must be encoded using the rules set forth in [5]. The character set encoding is limited to specific ranges within the US-ASCII character set [4]. The template is encoded in UTF8 characters. The template must not include any characters outside of the US-ASCII printable range unless these values are escaped. For instance, a template in Greek would encode the lower case alpha as "which is the UTF8 encoding of the Unicode value 0x03b1. Non-US-ASCII characters in templates will NOT be human readable until un-escaped. 6.1. Language Identification and Translation The language used in attribute strings should be identified using the "language" template item as defined by [3]. A program can translate a service registration from one language to another provided it has both the template of the language for the registration and the template of the desired target language. All standardized attributes are in the same order in both templates, allowing one template to be used as a 'look up table' into the other. A string in one language can be translated to another by finding the string in the corresponding position in the both templates. If a template in a desired language is not available, a "best-effort" translation can always be made from an existing template. Non-literal attribute definitions, attribute identifiers, attribute type names, attribute flags, and the boolean constants "true" Guttman,Perkins,Kempf Expires 2 August 1998 [Page 21] Internet Draft Service Templates and URLs 2 February 1998 and "false" are never translated. Translation of attribute identifiers is prohibited because, as with domain names, they can potentially be part of a service: URL and therefore their character set is restricted. In addition, as with variable identifiers in programming languages, they could become embedded into program code. Other strings, including the descriptive help text, are directly translatable from one language to another. When the service type is standardized, more than one document can be submitted for review. One service type description is approved as a master, so that when a service type template is updated in one language, all the translations (at least eventually) reflect the same semantics. If no document exists describing the standard translation of the service type, a 'best effort' translation for strings should be done. 7. Security Considerations Service type templates provide information that is used to interpret information obtained by the Service Location Protocol. If these templates are modified or false templates are distributed, services may not correctly register themselves, or clients might not be able to interpret service information. The service: URLs themselves MAY specify the service access point and protocol for a particular service type. The Service Location Protocol [12] distributes service: URLs and has an authentication mechanism that allows service: URLs of registered services to be signed and for the signatures to be verified by clients. Each Service Template will include a security considerations section which will describe security issues with using the service scheme for the specific Service Type. A. Service Template Examples The text in the template example sections is to be taken as being a single file. They are completely fictitious (ie. the examples do not represent real services). The FOO example shows how to use service templates for an application that has very few attributes. Clients request the FOO server where their user data is located by including their user name as the value of the user attribute. The Net-Transducer example shows how abstract service types are defined and how a corresponding concrete instance is defined. A Guttman,Perkins,Kempf Expires 2 August 1998 [Page 22] Internet Draft Service Templates and URLs 2 February 1998 system might support any of several NetTransducer services. Here we give only one concrete instance of the abstract type. It is not necessary to register concrete templates for an abstract service type if the abstract service type template is completely clear as to what possible values can be used as a concrete type, and what their interpretation is. A.1. FOO -------------------------template begins here----------------------- type=FOO version=0.0 lang=en description= The FOO service URL provides the location of an FOO service. url-syntax= url-path= ; There is no URL path defined for a FOO URL. users= string M L O # The list of all users which the FOO server supports. groups= string M L O # The list of all groups which the FOO server supports. --------------------------template ends here------------------------ The Internet Draft describing the FOO scheme template must indicate contact information and security considerations, e.g., contact="Erik Guttman" security considerations= If the USER and GROUPS attributes are included a possibility exists that the list of identities for users or groups can be discovered. This information would otherwise be difficult to discover. A.2. Abstract Service Type: Net-Transducer The Internet Draft for the service type template contains the following text: -------------------------template begins here----------------------- Guttman,Perkins,Kempf Expires 2 August 1998 [Page 23] Internet Draft Service Templates and URLs 2 February 1998 type=Net-Transducer version=0.0 lang=en description= This is an abstract service type. The purpose of the Net- Transducer service type is to organize into a single category all network enabled Transducers which have certain properties. url-syntax= url-path= ; Depends on the concrete service type. ; See these templates. sample-units= string L # The units of sample that the Transducer provides, for instance # C (degrees Celsius), V (Volts), kg (Kilograms), etc. sample-resolution= string L # The resolution of the Transducer. For instance, 10^-3 means # that the Transducer has resolution to 0.001 unit. sample-rate= integer L # The speed at which samples are obtained per second. For # instance 1000 means that one sample is obtained every millisecond. --------------------------template ends here------------------------ In addition, the following format might be used for the needed contact and security considerations information. .......... contact="Erik Guttman" security considerations= See the security considerations of the concrete service types. A.3. Concrete Service Type: Net-Transducer:Thermometer -------------------------template begins here----------------------- type=service:Net-Transducer:Thermometer version=0.0 lang=en Guttman,Perkins,Kempf Expires 2 August 1998 [Page 24] Internet Draft Service Templates and URLs 2 February 1998 description= The Thermometer is a Net-Transducer capable of reading temperature. The data is read by opening a TCP connection to one of the ports in the service URL and reading an ASCII string until an NULL character is encountered. The client may continue reading data at no faster than the sample-rate, or close the connection. url-syntax= url-path = ; ports port-list = ";ports=" port-list ports = port / port "," ports ; See the Service URL production rule. ; These are the ports connections can be made on. location-description=string # The location where the Thermometer is located. operator=string O # The operator to contact to have the Thermometer serviced. --------------------------template ends here------------------------ ......... contact="Erik Guttman" security considerations= There is no authentication of the Transducer output. Thus, the Thermometer output could easily be spoofed. A.4. service: URLs and SLP A user with an FOO enabled calendar application should not be bothered with knowing the address of their FOO server. The calendar client program can use SLP to obtain the FOO service: URL automatically, say 'service:foo://server1.nosuch.org', by issuing a Service Request. In the event that this FOO server failed, the Calendar client can issue the same service request again to find the backup FOO server, say 'service:foo://server2.nosuch.org'. In both cases, the service: URL conforms to the FOO service template as do the associated attributes (user and group.) A network thermometer could be advertised as: URL = service:net-transducer:thermometer://v33.test/ports=3211 Attributes = (location-description=Missile bay 32), (operator=Joe Agent), (sample-units=C), Guttman,Perkins,Kempf Expires 2 August 1998 [Page 25] Internet Draft Service Templates and URLs 2 February 1998 (sample-resolution=10^-1),(sample-rate=10) This might be very useful for a technician who wanted to find a Thermometer in Missile bay 32, for example. Guttman,Perkins,Kempf Expires 2 August 1998 [Page 26] Internet Draft Service Templates and URLs 2 February 1998 B. Full Copyright Statement Copyright (C) The Internet Society (1997). 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 implmentation 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 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." C. Acknowledgments Ryan Moats suggestions were very useful in producing this document. Guttman,Perkins,Kempf Expires 2 August 1998 [Page 27] Internet Draft Service Templates and URLs 2 February 1998 References [1] Protocol and service names, October 1994. ftp://ftp.isi.edu/in-notes/iana/assignments/service-names. [2] Port numbers, July 1997. ftp://ftp.isi.edu/in-notes/iana/assignments/port-numbers. [3] H. Alvestrand. Tags for the Identification of Languages. RFC 1766, March 1995. [4] ANSI. Coded Character Set -- 7-bit American Standard code for Information Interchange. X3.4-1986, 1986. [5] T. Berners-Lee, R. Fielding, and L. Masinter. Uniform Resource Locators (URL): Generic Syntax and Semantics. RFC1738 as amended by RFC1808 and updated by draft-fielding-url-syntax-05.txt, May 1997. (work in progress). [6] T. Berners-Lee, L. Masinter, and M. McCahill. Uniform Resource Locators (URL). RFC 1738, December 1994. [7] N. Borenstein and N. Freed. Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. RFC 2045, November 1996. [8] D. Crocker and P. Overell. Augmented BNF for Syntax Specifications: ABNF. draft-ietf-drums-abnf-04.txt, September 1997. (work in progress). [9] J. Myers. Simple Authentication and Security Layer (SASL). draft-myers-auth-sasl-11.txt, May 1997. (work in progress). [10] J. G. Myers. ACAP -- Application Configuration Access Prototol. draft-ietf-acap-spec-04.txt, June 1997. (work in progress). [11] Pete St. Pierre. Definition of lpr: URLs for use with Service Location. draft-ietf-svrloc-lpr-scheme-00.txt, July 1997. (work in progress). [12] J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. Service Location Protocol. RFC 2165, July 1997. [13] F. Yergeau. UTF-8, a transformation format of unicode and ISO 10646. RFC 2044, October 1996. Guttman,Perkins,Kempf Expires 2 August 1998 [Page 28] Internet Draft Service Templates and URLs 2 February 1998 Authors' Addresses Questions about this memo can be directed to: Erik Guttman Charles E. Perkins James Kempf Sun Microsystems Sun Microsystems Sun Microsystems Bahnstr. 2 901 San Antonio Rd. 901 San Antonio Rd. 74915 Waibstadt Palo Alto, CA, 94303 Palo Alto, CA, 94303 Germany USA USA +49 7263 911484 1 650 786 6464 1 650 786 5890 1 650 786 6445 (fax) 1 650 786 6445 (fax) erik.guttman@sun.com charles.perkins@sun.com james.kempf@sun.com Guttman,Perkins,Kempf Expires 2 August 1998 [Page 29]