Service Location Working Group Erik Guttman INTERNET DRAFT Charles Perkins James Kempf 31 July 1997 Sun Microsystems Service Templates and service: Schemes draft-ietf-svrloc-service-scheme-02.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), nic.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 SHOULD be accompanied by a set of well-defined attributes which define the service. These attributes SHOULD convey configuration information to client software, or service characteristics meaningful to end users. Guttman,Perkins,Kempf Expires 31 December 1997 [Page i] Internet Draft Service Templates and URLs 31 July 1997 This document describes a formal procedure for defining and standardizing new service types and attributes for use with the "service:" scheme. The formal descriptions of service types and attributes are templates that are human and machine readable. 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 31 December 1997 [Page ii] Internet Draft Service Templates and URLs 31 July 1997 Contents Status of This Memo i Abstract i 1. Introduction 2 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Service Location Protocol . . . . . . . . . . . . . . . . 4 2. Related work 4 3. Service URL Syntax and Semantics 4 3.1. Service URL Syntax . . . . . . . . . . . . . . . . . . . 4 3.2. Service URL Semantics . . . . . . . . . . . . . . . . . . 6 3.3. Use of service: URLs . . . . . . . . . . . . . . . . . . 8 3.4. Specifying the Service Type-Specific URL Syntax . . . . . 8 3.5. Accommodating Abstract Service Types . . . . . . . . . . 9 3.5.1. Advertising Arbitrary URL's . . . . . . . . . . . 9 3.5.2. Advertising with Contact Information . . . . . . 10 4. Syntax and Semantics of Service Type Specifications 11 4.1. Syntax of Service Type Templates . . . . . . . . . . . . 11 4.2. Semantics of Service Type Templates . . . . . . . . . . . 14 4.2.1. Definition of a Service Template . . . . . . . . 14 4.2.2. Service Scheme . . . . . . . . . . . . . . . . . 15 4.2.3. Service Type Language . . . . . . . . . . . . . . 15 4.2.4. Version Number . . . . . . . . . . . . . . . . . 15 4.2.5. Description . . . . . . . . . . . . . . . . . . . 15 4.2.6. Syntax of the Service Type-specific URL Part . . 15 4.2.7. Attribute Definition . . . . . . . . . . . . . . 16 5. A Process For Standardizing New Service Types 20 6. Internationalization Considerations 21 6.1. Character Set Identification and Use . . . . . . . . . . 21 6.2. Language Identification and Translation . . . . . . . . . 22 7. Security Considerations 22 8. Changes Made Since the Last Version 23 Guttman,Perkins,Kempf Expires 31 December 1997 [Page 1] Internet Draft Service Templates and URLs 31 July 1997 1. Introduction This document describes a URL scheme, called service: URL, which defines network access information for network services using a formal notation. 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 has the configuration the client needs. 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 advertisement. Templates are used for the following distinct purposes: 1. Standardization The template is reviewed before it is standardized. Once it is standardized, all versions of the template are archived by IANA. 2. Service Registration Servers making use of the Service Location Protocol [19] register themselves and their attributes. They use the templates to generate the service registrations. In registering, the service must pick from among the allowable values. 3. 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. 4. Internationalization If a client application has the template for a given service type in two different languages, the attributes may be translated between the two languages. A service may register itself in more than one language using templates, though it has been configured by the system administrator to register in a single language. Guttman,Perkins,Kempf Expires 31 December 1997 [Page 2] Internet Draft Service Templates and URLs 31 July 1997 All grammar encoding follows the Augmented BNF (ABNF) [9] for syntax specifications. 1.1. Terminology This section introduces some terminology for describing service: URLs. 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 [18]. service: URL A URL, registered by a service agent of a particular service type, that conforms to a service scheme definition. The URL acts as an advertisement for the service, through which potential clients can discover the service and its capabilities. An example is service:lpr://server.eng/printer1. service type A name denoting 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 to a particular well known port [3] by convention or 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 from [13] is "wp". Section 3 discusses various ways that abstract types can be accommodated. service advertisement A service: URL and optionally a set of attributes comprise a service advertisement. This advertisement is made by or on behalf of a given service. The URL syntax and attributes must conform to the service template for the advertised service. Guttman,Perkins,Kempf Expires 31 December 1997 [Page 3] Internet Draft Service Templates and URLs 31 July 1997 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 allows service: URLs to be advertised and discovered, [19], though service: URLs may be also used in other contexts. Client applications discover service advertisements by issuing queries for services of a particular type, specifying the attributes of the service: URLs to return. Clients retrieve the attributes of a particular service by supplying its service: URL. Attributes for all service advertisements of a particular type can also be retrieved. Service may advertise themselves, or advertisements may be made on their behalf. These advertisements contain a service: URL, and possibly attributes and digital signatures. 2. Related work The "Finding Stuff" work by Ryan Moats, Martin Hamilton, and Paul Leach uses service: URLs to provide access information about arbitrary network protocols through DNS [14]. DNS SRV Resource Records are a mechanism which provides a way to obtain a service by type for a given domain [10], without specifying which instance of the service type would meet particular requirements. 3. Service URL Syntax and Semantics This section describes the syntax and semantics of service: URLs. 3.1. Service URL Syntax The syntax of the service: URL MUST conform to [6]. The only exception is that the field has been omitted from the production, since plain text transmission of passwords is now discouraged. Note that the syntax for the field depends upon the service type definition. The field is the service access point, and describes how to access the service. In addition, although both upper case and lower case characters are recognized in the field for convenience, the name is case-folded Guttman,Perkins,Kempf Expires 31 December 1997 [Page 4] Internet Draft Service Templates and URLs 31 July 1997 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 [7]. The ABNF for a service: URL is: service: URL = "service:" service-type ":" sap service-type = abstract-type / protocol abstract-type = type-name [ "." naming-auth ] type-name = resname naming-auth = resname protocol = resname ; An Assigned Numbers name [1] or ; well known port name [3] for ; the protocol. resname = 1*[ alpha / digit / "+" / "-" ] sap = "/" [ addr-family ] "/" site [ url-part ] addr-family = *xchar ; depends on the address family site = [ [ user "@" ] hostport ] / [ other-addr ] hostport = host [ ":" port ] other-addr = *xchar ; depends on the address family host = hostname / hostnumber hostname = *( domainlabel "." ) toplabel alphanum = alpha / digit domainlabel = alphanum / alphanum *[alphanum / "-"] alphanum toplabel = alpha / alpha *[ alphanum / "-" ] alphanum ipv4-number = 1*3digit 3*3("." 1*3digit) ipv6-number = 32*hex 3digit = digit digit digit port = 1*digit user = *[ uchar / ";" / "+" / "&" / "=" ] url-part = [ url-path ] [ attr-list ] url-path = 1 * ( "/" *xchar ) ; Each service type must define its ; own syntax consistent ; with [6]. 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 Guttman,Perkins,Kempf Expires 31 December 1997 [Page 5] Internet Draft Service Templates and URLs 31 July 1997 alpha = "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" / "j" / "k" / "l" / "m" / "n" / "o" / "p" / "q" / "r" / "s" / "t" / "u" / "v" / "w" / "x" / "y" / "z" / "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" / "I" / "J" / "K" / "L" / "M" / "N" / "O" / "P" / "Q" / "R" / "S" / "T" / "U" / "V" / "W" / "X" / "Y" / "Z" digit = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 3.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: service: URL = "service:" service-spec ":" sap where has the following form: /addr-family/addr-spec/url-path;attr-list The field includes the field. As discussed in Section 1, the can be either a concrete protocol name, or an abstract type name. The protocol determines the semantics (for service access point) field, and of attributes associated with it. The field indicates the network layer protocol type [2] through which the service communicates with clients. The field is null by default, indicating the Internet Protocol (IP), but it can be used to indicate other address families such as IPX [17] or Appletalk [11]. The field includes a site specification (the field) in the format specified by [6]. The field is typically either a domain name (DNS) or an IP or other network protocol address for the service, and possibly a port number. If another address family is specified in the field, the exact syntax of the field depends on the address family. The field can be null if other information in the service URL or service attributes is sufficient to use the service. Guttman,Perkins,Kempf Expires 31 December 1997 [Page 6] Internet Draft Service Templates and URLs 31 July 1997 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 appears 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 [16] service might require that the client authenticate with it through Kerberos. Including an attribute in the service advertisement allows the ACAP client to make use of the correct SASL [15] authentication mechanism. The ACAP server's advertisement might look like: service:acap://some.where.net;authentication=KERBEROSV4 Note that there can be other attributes of an ACAP server which would not be 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 advertised 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 requesting the attribute information. The Service Location Protocol specifies how such information SHOULD be advertised by network services and obtained by client software. Attributes are associated with service: URLs for three reasons: 1. Attributes associated with a given URL allow for automatic selection of services that have certain features. Client software having particular requirements can choose services based on those requirements. For example, client software may require a server which has the right font, or which has access to specific hardware resources. Guttman,Perkins,Kempf Expires 31 December 1997 [Page 7] Internet Draft Service Templates and URLs 31 July 1997 2. Attributes provide a mechanism by which servers can advertise optional features or dynamic qualities. Clients that require or prefer to make use of optional features or dynamic information can proceed to do so without protocol negotiation or feature selection. Attributes serve as a mechanism for servers to distribute information about a wide variety of characteristics, including physical location, access restrictions and dynamic characteristics such as load. 3. Attributes support selection of service instances by characteristic as opposed to simply by name. Attributes may be used to give people information enabling the selection of particular service using a graphical user interface, for example. 3.3. Use of service: URLs The service: URL is intended to allow arbitrary client/server and peer to peer systems to make use of a standardized dynamic service access point discovery mechanism. It is intended that service: URLs be selected according to the suitability of associated attributes. A client application can obtain the URLs of several services of the same type and distinguish the most preferable among them by means of their attributes. The client uses the service: URL to bind directly to a service. Attributes are specified with a formal service template syntax described in Section 4. If a service: URL is stored by a client or an agent representing a client, the 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 advertisement may be done using the Service Location Protocol [19]. 3.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 [18] is defined with service: URLs in the following form: service:lpr://
/ The section of the URL after the address of the printer: Guttman,Perkins,Kempf Expires 31 December 1997 [Page 8] Internet Draft Service Templates and URLs 31 July 1997 "/" 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. 3.5. Accommodating Abstract Service Types An abstract service type is a service type that can be implemented by a variety of different protocols. Two kinds of advertisements for abstract service types are encouraged by the standard: 1. Advertising arbitrary URL's but including the abstract service type name in the attributes, 2. Advertising a service: URL with enough information, including the protocol, to contact the service and use it but including the protocol in the attributes, Other methods of advertising for abstract service types are discouraged to avoid problems with interoperability. Each of the two methods is discussed in the following subsections. 3.5.1. Advertising Arbitrary URL's An abstract service type may be associated with a collection of protocols and URL's that have already been standardized or are already in widespread use. In such cases, implementors are encouraged to advertise the URL's directly, without creating a new service: URL type. An example of such an abstract service type is the "wp" service [13]. In this case, "wp" (for "white pages") is an abstract service type that can map into a variety of different implementation protocols, for example "ldap", "whois++", etc. Each of these protocols has an existing URL either standardized or in widespread use. Rather than compose a new service: URL, the service SHOULD be advertised with the existing URL scheme and registered under the abstract service type name "wp". However, in order that the URL is clearly identifiable to clients as an instance of the abstract service type, the service type template MUST include a required attribute "service-type" whose value is set upon registration to the abstract service type name. The service Guttman,Perkins,Kempf Expires 31 December 1997 [Page 9] Internet Draft Service Templates and URLs 31 July 1997 type name must conform to the syntactic rules for service type names in the service: URL syntax. 3.5.2. Advertising with Contact Information Some abstract service types may be associated with protocols that do not have URL's in widespread use, or require more information than just a standardized URL to access the service. In such cases, implementors are encouraged to develop a new service: URL type for the advertisement, including enough information so that an application can access the service without further network traffic involving service location. However, implementors SHOULD avoid embedded URL's as a matter of style. For example, suppose a network service is being developed for dynamically loading device drivers. The client requires the following three pieces of information before it can successfully load and instantiate the driver: 1. The protocol used to load the driver code, for example, "ftp", 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". The temptation is to form the first two items into a URL and embed that into a service: URL. Rather, the implemention SHOULD develop a service type-specific service: URL consistent with the syntactic rules of [6] that contains the information needed to successfully use the service but avoids embedded URL's. An example might be the following: service:device-drivers:// drivers.ra.sys/systemhost/drivers/diskdrivers.drv; type=scsi;protocol=ftp where the URL has been broken after the service type field and before the attribute list for readability. In this case, a pathname followed by the field syntax has been used to include the attributes required to successfully make contact with the service and use it. Other syntactic choices are possible. The service type template for such an abstract service type MUST contain required attributes for each piece of contact Guttman,Perkins,Kempf Expires 31 December 1997 [Page 10] Internet Draft Service Templates and URLs 31 July 1997 information beyond the pathname, and MUST, in any case, include a required attribute having the identifier "protocol" that is set at registration time to the protocol needed to contact the service. In the above example, these attributes would be "type" and "protocol". Furthermore, the "protocol" attribute definition SHOULD include a list of allowed values comprising the protocols that can be used to contact the service. 4. Syntax and Semantics of Service Type Specifications Service type specifications are documents in a formal syntax defining properties important to a service advertisement. 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, 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. 4.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 ASCII [5] and be in English. A template document begins with a block of text assigning values to five template identification items. The five template 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 single blank line. Reserved characters encompass ";", "%", "=", ",", "#", LF, and CR. Reserved characters should be escaped. The escape sequence is the same as described in [6]. 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. Guttman,Perkins,Kempf Expires 31 December 1997 [Page 11] Internet Draft Service Templates and URLs 31 July 1997 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, but the result should be case-folded into lower case by parsers and other tools. 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 separated by whitespace. String values are trimmed on both ends to remove whitespace, but interior whitespace is not touched. For example: " some value , another example " would be 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 can be used by some protocols 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 have the following ABNF [9] grammar: template = tem-attrs attr-defs tem-attrs = schemetype schemevers schemelang schemetext schemeurl schemetype = "type" "=" scheme termdef schemevers = "version" "=" version-no termdef schemelang = "language" "=" isolang 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 3. scheme = service-type [ "." naming-auth ] service-type = scheme-name naming-auth = scheme-name scheme-name = 1*schemechar [ "." 1*schemechar ] schemechar = alpha / digit / "-" / "+" / Guttman,Perkins,Kempf Expires 31 December 1997 [Page 12] Internet Draft Service Templates and URLs 31 July 1997 version-no = 1*digit "." 1*digit isolang = 2*2lower-alpha ;see [12] 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 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"] ["x/"X"] ["o"/"O"] 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 / space] 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( [8], Sect. 5.2.) ; Newlines are ignored in decoding radix-64 ; values. com-chars = safe-char / white-sp / "," / ";"/ "%" safe-char = attrchar / escaped / " " / "!" / '"' / "'" / "|" / "(" / ")" / "+" / "-" / "." / ":" / "=" / "?" / "[" / "]" / "{" / "/" / "{" / "$" ; All ASCII 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 ) Guttman,Perkins,Kempf Expires 31 December 1997 [Page 13] Internet Draft Service Templates and URLs 31 July 1997 4.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. 4.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 4.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 advertisements. Each of the following subsections deals with one of these items. Guttman,Perkins,Kempf Expires 31 December 1997 [Page 14] Internet Draft Service Templates and URLs 31 July 1997 4.2.2. Service Scheme 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. As discussed in Sections 1 and 3, the service type name should be either a protocol name or an abstract type name. 4.2.3. Service Type Language The service type language is a two letter ISO-639 code defining the language of the template [12] and is the value of the "language" item. 4.2.4. 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 attributes add one to the minor number, and changes of definition or removal of attributes adds one to the major number. The intent is that an old service template still accurately, if incompletely, defines the attributes of a service advertisement if the template only differs from the advertisement in its minor version. See Section 5 for more detail on how to use the version attribute. 4.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. 4.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 Guttman,Perkins,Kempf Expires 31 December 1997 [Page 15] Internet Draft Service Templates and URLs 31 July 1997 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 [18], 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 service advertisement is an existing URL and not a service: URL. The syntax is included in the template document as an ABNF [9] following the rules for URL syntax described in [6]. There is no requirement for a service scheme to support a . The field can be very simple, or even omitted. If the service advertisement is an existing URL, the "url-syntax" item SHOULD include a reference to the appropriate standardization documents for the URL. 4.2.7. Attribute Definition The bulk of the template is 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 [19] or other means, and discussion of this is beyond the scope of the document. 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 bind to, 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 which acts as 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, Guttman,Perkins,Kempf Expires 31 December 1997 [Page 16] Internet Draft Service Templates and URLs 31 July 1997 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. 4.2.7.1. The Attribute Identifier An attribute definition starts with the specification of the attribute's identifier. The attribute's identifier functions 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 [6]. The reason is that services could want to display prominent attributes in their service: URL advertisements. Each attribute identifier must be unique in the template. Since identifiers are case folded, upper case and lower case characters are the same. 4.2.7.2. The Attribute Type Attributes can have one of five different types: string, 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. The character set used to represent strings is not specified at the time the template is defined, but rather is determined by the service registration. Booleans have the standard syntax. Opaques are radix64 numbers [8] 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. 4.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 Guttman,Perkins,Kempf Expires 31 December 1997 [Page 17] Internet Draft Service Templates and URLs 31 July 1997 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. - 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 considered to be readable by people and should not be translated when the template is translated. See Section 6 for more information about translation. - x or X Indicates that an explicit match between the attribute value and a query value is required, and that partial matches are excluded. An attribute which is both multi-valued and explicit (i.e. both the "M" and "X" flags are set) only requires an explicit match between one attribute and the query. This attribute must be included in every query for the service. Multi-valued attributes are an ordered set like a one-dimensional array or vector in a programming language. Additions to the attributes occur on the end that would have the maximum index if the attribute were a vector. Deletions of individual values from the attribute are not supported, and deletion of the attribute causes the entire set of values to be removed. These properties allow linked sets of multivalued attributes to implement lookup tables and other data structures. Guttman,Perkins,Kempf Expires 31 December 1997 [Page 18] Internet Draft Service Templates and URLs 31 July 1997 Explicit matching attributes are used for creating ACL's and other purposes. As an example of using explicit matching of attributes consider the following attribute definition: acl = string m x #Only people whose names are on this list are allowed to #access the service. george.bonner charles.fowler muhammad.ali.jhin taso.fujimora In this case, every query for advertisements of the service must contain this attribute, and unless there is an exact match between the query string and one of the allowed values, the advertisement will not be returned. 4.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. As a consequence, newlines cannot be embedded in values. 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 not optional but 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, 4. Opaque values are assigned a byte array containing no values, 5. Multi-valued attributes are initialized with a single value. Required attributes must always be included with the service advertisement registration. Guttman,Perkins,Kempf Expires 31 December 1997 [Page 19] Internet Draft Service Templates and URLs 31 July 1997 4.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. 4.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. 4.2.7.7. Conclusion of An Attribute Definition An attribute definition concludes with a single empty line. 5. A Process For Standardizing New Service Types New service types can be suggested simply by providing a service type template and a short description for use of the service The template MUST have its "version" template attribute set to 0.0. 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: Guttman,Perkins,Kempf Expires 31 December 1997 [Page 20] Internet Draft Service Templates and URLs 31 July 1997 - Any new 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 of 1.y (where x