Service Location Working Group Erik Guttman
INTERNET DRAFT Charles Perkins
James Kempf
31 September 1997 Sun Microsystems
Service Templates and service: Schemes
draft-ietf-svrloc-service-scheme-03.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 March 1997 [Page i]
Internet Draft Service Templates and URLs 31 September 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 March 1997 [Page ii]
Internet Draft Service Templates and URLs 31 September 1997
Contents
Status of This Memo i
Abstract i
1. Introduction 1
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 . . . . . 9
3.5. Accommodating Abstract Service Types . . . . . . . . . . 9
3.5.1. Advertising Abstract Service Types . . . . . . . 9
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 Type . . . . . . . . . . . . . . . . . . 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 . . 16
4.2.7. Attribute Definition . . . . . . . . . . . . . . 16
5. A Process For Standardizing New Service Types 20
6. Internationalization Considerations 21
6.1. Language Identification and Translation . . . . . . . . . 21
7. Security Considerations 22
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
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 1]
Internet Draft Service Templates and URLs 31 September 1997
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 an operator who
registered service attributes in a single language.
All grammar encoding follows the Augmented BNF (ABNF) [9] for syntax
specifications.
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 2]
Internet Draft Service Templates and URLs 31 September 1997
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 which conforms to the service scheme definition. It
provides at least the following: The name of an access
protocol, and an address where this service is active. 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 advertise and discover the
location of services. It may be used by other protocols and in
documents as well.
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 the name of 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 March 1997 [Page 3]
Internet Draft Service Templates and URLs 31 September 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.
Services 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 <password> field has been omitted from the
<site> production, since plain text transmission of passwords is
now discouraged. Note that the syntax for the <sap> field depends
upon the service type definition. The <sap> 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 <service-type> field for convenience, the name is case-folded
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 4]
Internet Draft Service Templates and URLs 31 September 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 / concrete-type
abstract-type = type-name [ "." naming-auth ]
concrete-type = protocol [ "." naming-auth ]
type-name = resname
naming-auth = resname
protocol = resname
; An Assigned Numbers name [1] or
; well known port name [3] for
; the protocol. Other names may be assigned
; if no prior assigned name exists.
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 = 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 [6].
attr-list = 1 * ( ";" attr-asgn )
attr-asgn = attr-id / attr-id "=" attr-value
safe = "$" / "-" / "_" / "." / "~"
extra = "!" / "*" / "'" / "(" / ")" / "," / "+"
uchar = unreserved / escaped
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 5]
Internet Draft Service Templates and URLs 31 September 1997
xchar = unreserved / reserved / escaped
escaped = "%" hex hex
hex "a" / "b" / "c" / "d" / "e" / digit
reserved = ";" / "/" / "?" / ":" / "@" / "&" / "=" / "+"
unreserved = alpha / digit / safe / extra
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 <sap> has the following form:
/addr-family/addr-spec/url-path;attr-list
The <service-spec> field includes the <service-type> field. As
discussed in Section 1, the <service-type> can be either a concrete
protocol name, or an abstract type name.
The protocol determines the semantics of the <sap> (for service
access point) field, and of attributes associated with it.
The <addr-family> field indicates the network layer protocol
type [2] through which the service communicates with clients. The
<addr-family> 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 <service-part> field includes a site specification (the
<site> field) in the format specified by [6]. The <site> 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 <addr-family> field, the
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 6]
Internet Draft Service Templates and URLs 31 September 1997
exact syntax of the <site> field depends on the address family. The
<site> field can be null if other information in the service URL or
service attributes is sufficient to use the service.
The <sap> field allows more information to be provided (by way of
<url-path> and <attr-list>) that can uniquely locate the service or
resource if the <addr-spec> is not sufficient for that purpose.
An <attr-list> field appears at the end of the <url-part> field,
but is never required to exist in any service location registration.
The <attr-list> 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
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 7]
Internet Draft Service Templates and URLs 31 September 1997
require a server which has the right font, or which has access to
specific hardware resources.
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] (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
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 8]
Internet Draft Service Templates and URLs 31 September 1997
include a service: URL as a pointer to a service, describing in text
what the service does and who is authorized to use it.
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://<address of printer>/<queue name>
The section of the URL after the address of the printer:
"/" <queue name>
is specific to the lpr service type and corresponds to the
<url-path> 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.
In order to advertise an 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
the protocol to use. Rather it is the collective type of service.
This is further discussed in the section below.
Other methods of advertising abstract service types, such as creating
service type names which are compound or have their own internal
hierarchical convention are not encouraged. This will avoid problems
with interoperability.
Other methods of advertising for abstract service types are
discouraged to avoid problems with interoperability.
3.5.1. Advertising Abstract Service Types
Some services may make use of several protocols which are in common
use, but are distinct services in their own right. In these cases an
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 9]
Internet Draft Service Templates and URLs 31 September 1997
abstract service type is appropriate. What is essential is that all
the required information for the service be clearly defined.
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",
"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".
The temptation is to form the first two items into a URL and embed
that into a service: URL. For example:
service:ftp:/x3.bean.org/drivers/diskdrivers.drv;driver=scsi
is a service: URL which seems to indicate where to obtain the
driver.
Rather, an abstract service-type should be used. The service type
which is desired is not "ftp", as the example indicates. Rather,
it is "device-drivers". The service: URL which 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
This also supports other URLs for the same service using other
protocols, 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 SLP, a search for the service type "device-drivers" may return
all of the three URLs listed above. The client could select the most
appropriate access protocol for the desired resource.
The important thing is that the abstract service type is well
specified. This means that anyone who needs a resource of that type
will obtain all information needed to access it. In every case this
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 10]
Internet Draft Service Templates and URLs 31 September 1997
will include an access protocol and a network address where the
service is available. In the example above, there were three further
requirements: A URL path would have to be included for access
protocols indicating the document to download, and two attributes had
to be included to characterize the driver.
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 UTF8 [20, 21] 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 March 1997 [Page 11]
Internet Draft Service Templates and URLs 31 September 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 potentially with embedded whitespace, separated from each
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 is reduced to a single white space. Preceding or trailing
white space is removed. 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 <url-path> production
; in the service: URL grammar of Section 3.
scheme = service-type [ "." naming-auth ]
service-type = scheme-name
naming-auth = scheme-name
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 12]
Internet Draft Service Templates and URLs 31 September 1997
scheme-name = 1*schemechar [ "." 1*schemechar ]
schemechar = alpha / digit / "-" / "+" /
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 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
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 13]
Internet Draft Service Templates and URLs 31 September 1997
newline = CR / ( CR LF )
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 March 1997 [Page 14]
Internet Draft Service Templates and URLs 31 September 1997
4.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. As discussed in Sections 1 and 3,
the service type name should be either a protocol name or an abstract
type name.
If the service type corresponds to an abstract service type the
allowed protocols to satisfy it SHOULD be listed here, along with
their formal specifications.
4.2.3. Service Type Language
The service type language is a RFC 1766 Language Tag defining the
language of the template [4] 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.
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.
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 15]
Internet Draft Service Templates and URLs 31 September 1997
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 <url-path> field of the service: URL is
designed to provide additional information to locate a service when
the <addr-spec> field is not sufficient. The <url-path> 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
<url-path> must include the queue name [18], but other service types
may not require this information.
The syntax for the <url-path> field MUST accompany the definition
of a new service type, unless the URL scheme has already been
standardized 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 <url-path>. The <url-path> 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.
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):
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 16]
Internet Draft Service Templates and URLs 31 September 1997
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,
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.
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 17]
Internet Draft Service Templates and URLs 31 September 1997
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
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.
The default and allowed values in the template for multivalued
attributes are an ordered set like an array or vector in a
programming language. The ordering this imposes on the attributes
listed in the service template allows one template to be used in
conjunction with another as a look-up table. This is how translation
between languages using templates is done, see Section 6. Note that
the attribute values associated with service advertisements are not
well ordered when retrieved from SLP, however. The order in which
they are stored and returned is implementation dependent. Therefore
one may not assume that the multiple values of a particular services'
attributes have any meaningful ordering.
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 18]
Internet Draft Service Templates and URLs 31 September 1997
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 unless escaped.
See Section 4.2.
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.
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
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 19]
Internet Draft Service Templates and URLs 31 September 1997
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:
- 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 of 1.y (where x<y) as
it ignores attributes it doesn't know about.
- Adding a mandatory attribute, removing support for an attribute
or changing definition of an attribute requires changing the
major version number of a service template. A client application
may be unable to make use of this information, or it may need
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 20]
Internet Draft Service Templates and URLs 31 September 1997
to obtain the most recent service template to help the user
interpret the service information.
The template should be posted to the Service Location Working Group
mailing list for review. Ideally, experts in the implementation and
deployment of the particular protocol are consulted so as to add or
delete attributes or change their definition to make the template as
useful as possible.
All published versions of the template must be available on-line,
including obsolete ones. Once consensus is achieved, the template
should be reissued with possible corrections, having its Version
number set to 1.0. If there is no comment on the template after 3
months, it should be considered to have been accepted.
6. Internationalization Considerations
The service: URL itself must be encoded using the rules set forth
in [6]. The character set encoding is limited to specific ranges
within the US-ASCII character set [5].
The template itself is encoded in UTF8 characters.
6.1. Language Identification and Translation
The language used in attribute strings should be identified using the
"language" template item as defined by [4].
A program can translate a service advertisement from one language to
another provided it has both the template of the language for the
advertisement and the template of the desired target language. All
standardized attributes are in the same order in both templates.
All non-arbitrary strings, including the descriptive help text, is
directly translatable from one language to another. Non-literal
attribute definitions, attribute identifiers, attribute type names,
attribute flags, and the boolean constants "true" 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.
All strings used in attribute values are assumed translatable unless
explicitly defined as being literal, so that best effort translation
(see below) does not modify strings which are meant to be interpreted
by a program, not a person.
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 21]
Internet Draft Service Templates and URLs 31 September 1997
There are two ways to go about translation: standardization and best
effort.
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 specify the service access point and
protocol for a particular service type. These service: URLs could
be distributed and indicate the location of a service other than
that which a user would normally want to use. The Service Location
Protocol [19] distributes service: URLs and has an authentication
mechanism that allows service: URLs of advertised services to be
signed and for the signatures to be verified by clients.
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 22]
Internet Draft Service Templates and URLs 31 September 1997
References
[1] Protocol and service names, October 1994.
ftp://ftp.isi.edu/in-notes/iana/assignments/service-names.
[2] Address family numbers, October 1995.
ftp://ftp.isi.edu/in-notes/iana/assignments/address-family-numbers.
[3] Port numbers, July 1997.
ftp://ftp.isi.edu/in-notes/iana/assignments/port-numbers.
[4] H. Alvestrand. Tags for the Identification of Languages. RFC
1766, March 1995.
[5] ANSI. Coded Character Set -- 7-bit American Standard code for
Information Interchange. X3.4-1986, 1986.
[6] 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).
[7] T. Berners-Lee, L. Masinter, and M. McCahill. Uniform Resource
Locators (URL). RFC 1738, December 1994.
[8] N. Borenstein and N. Freed. MIME (Multipurpose Internet Mail
Extensions) Part One: Mechanisms for Specifying and Describing
the Format of Internet Message Bodies. RFC 1521, September
1993.
[9] D. Crocker and P Overell. Augmented BNF for Syntax
Specifications: ABNF. draft-ietf-drums-abnf-02.txt, March
1997. (work in progress).
[10] A. Gulbrandsen and P. Vixie. A DNS RR for specifying the
location of services (DNS SRV). RFC 2052, October 1996.
[11] S. Gursharan, R. Andrews, and A. Oppenheimer. Inside AppleTalk.
Addison-Wesley, 1990.
[12] Geneva ISO. Code for the representation of names of languages.
ISO 639:1988 (E/F), 1988.
[13] R. Moats. Defining White Pages and Yellow Pages Services.
draft-ietf-svrloc-wpyp-00.txt, February 1997. (work in
progress).
[14] R. Moats and M. Hamilton. Finding Stuff (Providing information
to support service discovery). draft-ietf-svrloc-advertise-00.txt,
February 1997. (work in progress).
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 23]
Internet Draft Service Templates and URLs 31 September 1997
[15] J. Myers. Simple Authentication and Security Layer (SASL).
draft-myers-auth-sasl-11.txt, May 1997. (work in progress).
[16] J. G. Myers. ACAP -- Application Configuration Access Prototol.
draft-ietf-acap-spec-04.txt, June 1997. (work in progress).
[17] Inc Novell. Advanced netware v2.1 internetwork packet exchange
protocol (ipx) with asynchronous event scheduler (aes), October
1986.
[18] Pete St. Pierre. Definition of lpr: URLs for use with Service
Location. draft-ietf-svrloc-lpr-scheme-00.txt, July 1997.
(work in progress).
[19] J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. Service
Location Protocol. RFC 2165, July 1997.
[20] F. Yergeau. UTF-8, a transformation format of unicode and ISO
10646. RFC 2044, October 1996.
[21] F. Yergeau. UTF-8, a transformation format of unicode and ISO
10646. draft-yergeau-utf8-rev-00.txt, April 1997. (work in
progress).
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 415 786 6464 1 415 786 5890
1 415 786 6445 (fax) 1 415 786 6445 (fax)
erik.guttman@sun.com charles.perkins@sun.com james.kempf@sun.com
Guttman,Perkins,Kempf Expires 31 March 1997 [Page 24]
