idnits 2.17.1 draft-ietf-svrloc-service-scheme-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-24) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 3 instances of too long lines in the document, the longest one being 3 characters in excess of 72. == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 41: '...ce: URL, the URL SHOULD be accompanied...' RFC 2119 keyword, line 42: '... the service. These attributes SHOULD...' RFC 2119 keyword, line 50: '... SHOULD be used by administrative to...' RFC 2119 keyword, line 224: '... The syntax of the service: URL MUST conform to [6]. The only...' RFC 2119 keyword, line 359: '...such information SHOULD be advertised ...' (18 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1166 has weird spacing: '...sun.com charl...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '1' -- Possible downref: Non-RFC (?) normative reference: ref. '2' -- Possible downref: Non-RFC (?) normative reference: ref. '3' ** Obsolete normative reference: RFC 1766 (ref. '4') (Obsoleted by RFC 3066, RFC 3282) -- Possible downref: Non-RFC (?) normative reference: ref. '5' == Outdated reference: A later version (-09) exists of draft-fielding-url-syntax-05 -- Possible downref: Normative reference to a draft: ref. '6' ** Obsolete normative reference: RFC 1738 (ref. '7') (Obsoleted by RFC 4248, RFC 4266) ** Obsolete normative reference: RFC 1521 (ref. '8') (Obsoleted by RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC 2049) == Outdated reference: A later version (-04) exists of draft-ietf-drums-abnf-02 ** Obsolete normative reference: RFC 2052 (ref. '10') (Obsoleted by RFC 2782) -- Possible downref: Non-RFC (?) normative reference: ref. '11' -- Possible downref: Non-RFC (?) normative reference: ref. '12' == Outdated reference: A later version (-04) exists of draft-ietf-svrloc-wpyp-00 -- Possible downref: Normative reference to a draft: ref. '13' -- No information found for draft-ietf-svrloc-advertise - is the name correct? -- Possible downref: Normative reference to a draft: ref. '14' == Outdated reference: A later version (-12) exists of draft-myers-auth-sasl-11 == Outdated reference: A later version (-06) exists of draft-ietf-acap-spec-04 -- Possible downref: Non-RFC (?) normative reference: ref. '17' -- Possible downref: Normative reference to a draft: ref. '18' Summary: 14 errors (**), 0 flaws (~~), 8 warnings (==), 14 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Service Location Working Group Erik Guttman 2 INTERNET DRAFT Charles Perkins 3 James Kempf 4 31 July 1997 Sun Microsystems 6 Service Templates and service: Schemes 7 draft-ietf-svrloc-service-scheme-02.txt 9 Status of This Memo 11 This document is a submission by the Service Location Working Group 12 of the Internet Engineering Task Force (IETF). Comments should be 13 submitted to the srvloc@corp.home.net mailing list. 15 Distribution of this memo is unlimited. 17 This document is an Internet-Draft. Internet-Drafts are working 18 documents of the Internet Engineering Task Force (IETF), its areas, 19 and its working groups. Note that other groups may also distribute 20 working documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at 24 any time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as ``work in progress.'' 27 To learn the current status of any Internet-Draft, please check 28 the ``1id-abstracts.txt'' listing contained in the Internet-Drafts 29 Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (North 30 Europe), ftp.nis.garr.it (South Europe), munnari.oz.au (Pacific Rim), 31 ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). 33 Abstract 35 The 'service:' URL scheme name is used to define URLs (called 36 'service: URLs' in this document) that are primarily intended to be 37 used by the Service Location Protocol in order to distribute service 38 access information. These schemes provide an extensible framework 39 for client-based network software to obtain configuration information 40 required to make use of network services. When registering a 41 service: URL, the URL SHOULD be accompanied by a set of well-defined 42 attributes which define the service. These attributes SHOULD 43 convey configuration information to client software, or service 44 characteristics meaningful to end users. 46 This document describes a formal procedure for defining and 47 standardizing new service types and attributes for use with the 48 "service:" scheme. The formal descriptions of service types and 49 attributes are templates that are human and machine readable. They 50 SHOULD be used by administrative tools to parse service registration 51 information and by client applications to provide localized 52 translations of service attribute strings. 54 Contents 56 Status of This Memo i 58 Abstract i 60 1. Introduction 2 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.2. Service Location Protocol . . . . . . . . . . . . . . . . 4 64 2. Related work 4 66 3. Service URL Syntax and Semantics 4 67 3.1. Service URL Syntax . . . . . . . . . . . . . . . . . . . 4 68 3.2. Service URL Semantics . . . . . . . . . . . . . . . . . . 6 69 3.3. Use of service: URLs . . . . . . . . . . . . . . . . . . 8 70 3.4. Specifying the Service Type-Specific URL Syntax . . . . . 8 71 3.5. Accommodating Abstract Service Types . . . . . . . . . . 9 72 3.5.1. Advertising Arbitrary URL's . . . . . . . . . . . 9 73 3.5.2. Advertising with Contact Information . . . . . . 10 75 4. Syntax and Semantics of Service Type Specifications 11 76 4.1. Syntax of Service Type Templates . . . . . . . . . . . . 11 77 4.2. Semantics of Service Type Templates . . . . . . . . . . . 14 78 4.2.1. Definition of a Service Template . . . . . . . . 14 79 4.2.2. Service Scheme . . . . . . . . . . . . . . . . . 15 80 4.2.3. Service Type Language . . . . . . . . . . . . . . 15 81 4.2.4. Version Number . . . . . . . . . . . . . . . . . 15 82 4.2.5. Description . . . . . . . . . . . . . . . . . . . 15 83 4.2.6. Syntax of the Service Type-specific URL Part . . 15 84 4.2.7. Attribute Definition . . . . . . . . . . . . . . 16 86 5. A Process For Standardizing New Service Types 20 88 6. Internationalization Considerations 21 89 6.1. Character Set Identification and Use . . . . . . . . . . 21 90 6.2. Language Identification and Translation . . . . . . . . . 22 92 7. Security Considerations 22 94 8. Changes Made Since the Last Version 23 96 1. Introduction 98 This document describes a URL scheme, called service: URL, which 99 defines network access information for network services using a 100 formal notation. In addition it describes how to define a set of 101 attributes to associate with a service: URL. These attributes will 102 allow end users and programs to select between network services of 103 the same type that have different capabilities. The attributes 104 are defined in a template document that is readable by people and 105 machines. 107 A client uses attributes to select a particular service. Service 108 selection occurs by obtaining the service: URL that has the 109 configuration the client needs. Service type templates define the 110 syntax of service: URLs for a particular service type, as well as the 111 attributes which accompany a service: URL in a service advertisement. 113 Templates are used for the following distinct purposes: 115 1. Standardization 117 The template is reviewed before it is standardized. Once it is 118 standardized, all versions of the template are archived by IANA. 120 2. Service Registration 122 Servers making use of the Service Location Protocol [19] register 123 themselves and their attributes. They use the templates to 124 generate the service registrations. In registering, the service 125 must pick from among the allowable values. 127 3. Client presentation of Service Information 129 Client applications may display service information. The 130 template provides type information and explanatory text which may 131 be helpful in producing user interfaces. 133 4. Internationalization 135 If a client application has the template for a given service type 136 in two different languages, the attributes may be translated 137 between the two languages. 139 A service may register itself in more than one language 140 using templates, though it has been configured by the system 141 administrator to register in a single language. 143 All grammar encoding follows the Augmented BNF (ABNF) [9] for syntax 144 specifications. 146 1.1. Terminology 148 This section introduces some terminology for describing service: 149 URLs. 151 service scheme 153 A URL scheme whose name starts with the string "service:" and 154 is followed by the service type name, constructed according to 155 the rules in this document. An example is "service:lpr:" for 156 the lpr print service [18]. 158 service: URL 160 A URL, registered by a service agent of a particular service 161 type, that conforms to a service scheme definition. The 162 URL acts as an advertisement for the service, through 163 which potential clients can discover the service and its 164 capabilities. An example is service:lpr://server.eng/printer1. 166 service type 168 A name denoting either a particular network protocol, or an 169 abstract service associated with a variety of protocols. If 170 the service type denotes a particular protocol, then the 171 service type name should either be assigned to a particular 172 well known port [3] by convention or or be the Assigned Numbers 173 name for the service [1]. 175 abstract service type 177 A service type name which is associated with a variety of 178 different protocols. An example from [13] is "wp". Section 3 179 discusses various ways that abstract types can be accommodated. 181 service advertisement 183 A service: URL and optionally a set of attributes comprise a 184 service advertisement. This advertisement is made by or on 185 behalf of a given service. The URL syntax and attributes must 186 conform to the service template for the advertised service. 188 service template 190 A formal description of the service attributes and service 191 scheme associated with a particular service type. 193 1.2. Service Location Protocol 195 The Service Location Protocol allows service: URLs to be advertised 196 and discovered, [19], though service: URLs may be also used in other 197 contexts. 199 Client applications discover service advertisements by issuing 200 queries for services of a particular type, specifying the attributes 201 of the service: URLs to return. Clients retrieve the attributes of a 202 particular service by supplying its service: URL. Attributes for all 203 service advertisements of a particular type can also be retrieved. 205 Service may advertise themselves, or advertisements may be made on 206 their behalf. These advertisements contain a service: URL, and 207 possibly attributes and digital signatures. 209 2. Related work 211 The "Finding Stuff" work by Ryan Moats, Martin Hamilton, and 212 Paul Leach uses service: URLs to provide access information about 213 arbitrary network protocols through DNS [14]. DNS SRV Resource 214 Records are a mechanism which provides a way to obtain a service by 215 type for a given domain [10], without specifying which instance of 216 the service type would meet particular requirements. 218 3. Service URL Syntax and Semantics 220 This section describes the syntax and semantics of service: URLs. 222 3.1. Service URL Syntax 224 The syntax of the service: URL MUST conform to [6]. The only 225 exception is that the field has been omitted from the 226 production, since plain text transmission of passwords is 227 now discouraged. Note that the syntax for the field depends 228 upon the service type definition. The field is the service 229 access point, and describes how to access the service. In addition, 230 although both upper case and lower case characters are recognized in 231 the field for convenience, the name is case-folded 232 into lower case. Service types are therefore not distinguished on 233 the basis of case, so, for example, "http" and "HTTP" designate the 234 same service type. This is consistent with general URL practice, as 235 outlined in [7]. 237 The ABNF for a service: URL is: 239 service: URL = "service:" service-type ":" sap 240 service-type = abstract-type / protocol 241 abstract-type = type-name [ "." naming-auth ] 242 type-name = resname 243 naming-auth = resname 244 protocol = resname 245 ; An Assigned Numbers name [1] or 246 ; well known port name [3] for 247 ; the protocol. 248 resname = 1*[ alpha / digit / "+" / "-" ] 249 sap = "/" [ addr-family ] "/" site [ url-part ] 250 addr-family = *xchar ; depends on the address family 251 site = [ [ user "@" ] hostport ] / [ other-addr ] 252 hostport = host [ ":" port ] 253 other-addr = *xchar ; depends on the address family 254 host = hostname / hostnumber 255 hostname = *( domainlabel "." ) toplabel 256 alphanum = alpha / digit 257 domainlabel = alphanum / alphanum *[alphanum / "-"] alphanum 258 toplabel = alpha / alpha *[ alphanum / "-" ] alphanum 259 ipv4-number = 1*3digit 3*3("." 1*3digit) 260 ipv6-number = 32*hex 261 3digit = digit digit digit 262 port = 1*digit 263 user = *[ uchar / ";" / "+" / "&" / "=" ] 264 url-part = [ url-path ] [ attr-list ] 265 url-path = 1 * ( "/" *xchar ) 266 ; Each service type must define its 267 ; own syntax consistent 268 ; with [6]. 269 attr-list = 1 * ( ";" attr-asgn ) 270 attr-asgn = attr-id / attr-id "=" attr-value 271 safe = "$" / "-" / "_" / "." / "~" 272 extra = "!" / "*" / "'" / "(" / ")" / "," / "+" 273 uchar = unreserved / escaped 274 xchar = unreserved / reserved / escaped 275 escaped = "%" hex hex 276 hex "a" / "b" / "c" / "d" / "e" / digit 277 reserved = ";" / "/" / "?" / ":" / "@" / "&" / "=" / "+" 278 unreserved = alpha / digit / safe / extra 279 alpha = "a" / "b" / "c" / "d" / "e" / "f" / "g" / 280 "h" / "i" / "j" / "k" / "l" / "m" / "n" / 281 "o" / "p" / "q" / "r" / "s" / "t" / "u" / 282 "v" / "w" / "x" / "y" / "z" / 283 "A" / "B" / "C" / "D" / "E" / "F" / "G" / 284 "H" / "I" / "J" / "K" / "L" / "M" / "N" / 285 "O" / "P" / "Q" / "R" / "S" / "T" / "U" / 286 "V" / "W" / "X" / "Y" / "Z" 287 digit = "0" / "1" / "2" / "3" / "4" / "5" / "6" / 288 "7" / "8" / "9" 290 3.2. Service URL Semantics 292 The service scheme-specific information following the "service:" 293 URL scheme identifier provides information necessary to access the 294 service. As described in the previous subsection, the form of a 295 service: URL is as follows: 297 service: URL = "service:" service-spec ":" sap 299 where has the following form: 301 /addr-family/addr-spec/url-path;attr-list 303 The field includes the field. As 304 discussed in Section 1, the can be either a concrete 305 protocol name, or an abstract type name. 307 The protocol determines the semantics (for service 308 access point) field, and of attributes associated with it. 309 The field indicates the network layer protocol 310 type [2] through which the service communicates with clients. The 311 field is null by default, indicating the Internet 312 Protocol (IP), but it can be used to indicate other address families 313 such as IPX [17] or Appletalk [11]. 315 The field includes a site specification (the 316 field) in the format specified by [6]. The field 317 is typically either a domain name (DNS) or an IP or other network 318 protocol address for the service, and possibly a port number. If 319 another address family is specified in the field, the 320 exact syntax of the field depends on the address family. The 321 field can be null if other information in the service URL or 322 service attributes is sufficient to use the service. 324 The field allows more information to be provided (by way of 325 and ) that can uniquely locate the service or 326 resource if the is not sufficient for that purpose. 328 An field appears at the end of the field, 329 but is never required to exist in any service location registration. 330 The field is composed of a list of semicolon (";") 331 separated attribute assignments of the form: 333 attr-id "=" attr-value 335 or for keyword attributes: 337 attr-id 339 Attributes are part of service: URLs when the attributes are required 340 to access a particular service. For instance, an ACAP [16] service 341 might require that the client authenticate with it through Kerberos. 342 Including an attribute in the service advertisement allows the ACAP 343 client to make use of the correct SASL [15] authentication mechanism. 344 The ACAP server's advertisement might look like: 346 service:acap://some.where.net;authentication=KERBEROSV4 348 Note that there can be other attributes of an ACAP server which would 349 not be appropriate to include in the URL. For instance, the list 350 of users who have access to the server is useful for selecting an 351 ACAP server, but is not required for a client to use the advertised 352 service. 354 Attributes associated with the service: URL are not typically 355 included in the service: URL. They are stored and retrieved using 356 other mechanisms. The service: URL is uniquely identified with a 357 particular service agent or resource, and is used when registering or 358 requesting the attribute information. The Service Location Protocol 359 specifies how such information SHOULD be advertised by network 360 services and obtained by client software. 362 Attributes are associated with service: URLs for three reasons: 364 1. Attributes associated with a given URL allow for automatic 365 selection of services that have certain features. Client 366 software having particular requirements can choose services 367 based on those requirements. For example, client software may 368 require a server which has the right font, or which has access to 369 specific hardware resources. 371 2. Attributes provide a mechanism by which servers can advertise 372 optional features or dynamic qualities. Clients that require or 373 prefer to make use of optional features or dynamic information 374 can proceed to do so without protocol negotiation or feature 375 selection. Attributes serve as a mechanism for servers to 376 distribute information about a wide variety of characteristics, 377 including physical location, access restrictions and dynamic 378 characteristics such as load. 380 3. Attributes support selection of service instances by 381 characteristic as opposed to simply by name. Attributes may 382 be used to give people information enabling the selection of 383 particular service using a graphical user interface, for example. 385 3.3. Use of service: URLs 387 The service: URL is intended to allow arbitrary client/server and 388 peer to peer systems to make use of a standardized dynamic service 389 access point discovery mechanism. 391 It is intended that service: URLs be selected according to the 392 suitability of associated attributes. A client application can 393 obtain the URLs of several services of the same type and distinguish 394 the most preferable among them by means of their attributes. The 395 client uses the service: URL to bind directly to a service. 397 Attributes are specified with a formal service template syntax 398 described in Section 4. If a service: URL is stored by a client or 399 an agent representing a client, the agent SHOULD also keep track of 400 the attributes which characterize the service. 402 Registrations can be checked against the formal attribute 403 specification defined in the template by the client or agent 404 representing the client. Service advertisement may be done using the 405 Service Location Protocol [19]. 407 3.4. Specifying the Service Type-Specific URL Syntax 409 When a service type is specified, the specification includes the 410 definition of the syntax for all URLs that are registered by services 411 of that particular type. For instance, the "lpr" service type [18] 412 is defined with service: URLs in the following form: 414 service:lpr://
/ 416 The section of the URL after the address of the printer: 418 "/" 420 is specific to the lpr service type and corresponds to the 421 field of the general service: URL syntax. This part is 422 specified when the lpr service type is specified. 424 3.5. Accommodating Abstract Service Types 426 An abstract service type is a service type that can be implemented by 427 a variety of different protocols. Two kinds of advertisements for 428 abstract service types are encouraged by the standard: 430 1. Advertising arbitrary URL's but including the abstract service 431 type name in the attributes, 433 2. Advertising a service: URL with enough information, including the 434 protocol, to contact the service and use it but including the 435 protocol in the attributes, 437 Other methods of advertising for abstract service types are 438 discouraged to avoid problems with interoperability. 440 Each of the two methods is discussed in the following subsections. 442 3.5.1. Advertising Arbitrary URL's 444 An abstract service type may be associated with a collection 445 of protocols and URL's that have already been standardized or 446 are already in widespread use. In such cases, implementors are 447 encouraged to advertise the URL's directly, without creating a new 448 service: URL type. 450 An example of such an abstract service type is the "wp" service [13]. 451 In this case, "wp" (for "white pages") is an abstract service type 452 that can map into a variety of different implementation protocols, 453 for example "ldap", "whois++", etc. Each of these protocols has an 454 existing URL either standardized or in widespread use. Rather than 455 compose a new service: URL, the service SHOULD be advertised with the 456 existing URL scheme and registered under the abstract service type 457 name "wp". 459 However, in order that the URL is clearly identifiable to clients as 460 an instance of the abstract service type, the service type template 461 MUST include a required attribute "service-type" whose value is set 462 upon registration to the abstract service type name. The service 463 type name must conform to the syntactic rules for service type names 464 in the service: URL syntax. 466 3.5.2. Advertising with Contact Information 468 Some abstract service types may be associated with protocols that 469 do not have URL's in widespread use, or require more information 470 than just a standardized URL to access the service. In such cases, 471 implementors are encouraged to develop a new service: URL type 472 for the advertisement, including enough information so that an 473 application can access the service without further network traffic 474 involving service location. However, implementors SHOULD avoid 475 embedded URL's as a matter of style. 477 For example, suppose a network service is being developed for 478 dynamically loading device drivers. The client requires the 479 following three pieces of information before it can successfully load 480 and instantiate the driver: 482 1. The protocol used to load the driver code, for example, "ftp", 484 2. A pathname identifying where the driver code is located, for 485 example "/systemhost/drivers/diskdrivers.drv", 487 3. The name of the driver, for example, "scsi". 489 The temptation is to form the first two items into a URL and embed 490 that into a service: URL. Rather, the implemention SHOULD develop 491 a service type-specific service: URL consistent with the syntactic 492 rules of [6] that contains the information needed to successfully 493 use the service but avoids embedded URL's. An example might be the 494 following: 496 service:device-drivers:// 497 drivers.ra.sys/systemhost/drivers/diskdrivers.drv; 498 type=scsi;protocol=ftp 500 where the URL has been broken after the service type field and before 501 the attribute list for readability. 503 In this case, a pathname followed by the field syntax 504 has been used to include the attributes required to successfully make 505 contact with the service and use it. Other syntactic choices are 506 possible. 508 The service type template for such an abstract service type 509 MUST contain required attributes for each piece of contact 510 information beyond the pathname, and MUST, in any case, include a 511 required attribute having the identifier "protocol" that is set at 512 registration time to the protocol needed to contact the service. In 513 the above example, these attributes would be "type" and "protocol". 514 Furthermore, the "protocol" attribute definition SHOULD include a 515 list of allowed values comprising the protocols that can be used to 516 contact the service. 518 4. Syntax and Semantics of Service Type Specifications 520 Service type specifications are documents in a formal syntax defining 521 properties important to a service advertisement. These properties 522 are: 524 1. General information on the service type specification itself, 526 2. The syntax of the service type-specific part of the service URL, 528 3. The definition of attributes associated with a service. 530 The service type specification document is the service type template. 532 The following subsections describe the syntax and semantics of 533 service type templates. 535 4.1. Syntax of Service Type Templates 537 Service template documents are encoded in a simple form. They may be 538 translated into any language or character set, but the template used 539 for standardization MUST be encoded in ASCII [5] and be in English. 541 A template document begins with a block of text assigning values to 542 five template identification items. The five template identification 543 items can appear in any order within the block, but conventionally 544 the "type" item, which assigns the service type name, occurs at the 545 very top of the document in order to provide context for the rest of 546 the the document. The attribute definition item occurs after the 547 document identification items. 549 All items end with a single blank line. Reserved characters 550 encompass ";", "%", "=", ",", "#", LF, and CR. Reserved characters 551 should be escaped. The escape sequence is the same as described 552 in [6]. Values in value lists are separated by commas. A value list 553 is terminated by a newline not preceded by a comma. If the newline 554 is preceded by a comma, the value list is interpreted to continue 555 onto the next line. 557 Attribute identifiers, attribute type names, and flags are all 558 case insensitive. For ease of presentation, upper and lower case 559 characters can be used to represent these in the template document, 560 but the result should be case-folded into lower case by parsers 561 and other tools. Newlines are significant in the grammar. They 562 delimit one item from another, as well as separating parts of items 563 internally. 565 String values are considered to be a sequence of non-whitespace 566 tokens separated by whitespace. String values are trimmed on both 567 ends to remove whitespace, but interior whitespace is not touched. 568 For example: 570 " some value , another example " 572 would be trimmed to 574 "some value" and "another example". 576 Note that there can be no ambiguity in string tokenization because 577 values in value lists are separated by a comma. String tokens are 578 not delimited by double quotes (") as is usually the case with 579 programming languages. 581 Attribute tags and values can be used by some protocols for directory 582 look-up. In this case, decoding of character escapes and trimming 583 white space MUST be performed before string matching. In addition, 584 string matching SHOULD be case insensitive. 586 Templates have the following ABNF [9] grammar: 588 template = tem-attrs attr-defs 589 tem-attrs = schemetype schemevers schemelang 590 schemetext schemeurl 591 schemetype = "type" "=" scheme termdef 592 schemevers = "version" "=" version-no termdef 593 schemelang = "language" "=" isolang termdef 594 schemetext = "description" "=" newline desc-text termdef 595 schemeurl = "url-syntax" "=" newline url-bnf termdef 596 url-bnf = *[ com-chars ] 597 ; An ABNF describing the production 598 ; in the service: URL grammar of Section 3. 599 scheme = service-type [ "." naming-auth ] 600 service-type = scheme-name 601 naming-auth = scheme-name 602 scheme-name = 1*schemechar [ "." 1*schemechar ] 603 schemechar = alpha / digit / "-" / "+" / 604 version-no = 1*digit "." 1*digit 605 isolang = 2*2lower-alpha ;see [12] 606 desc-text = *[ com-chars ] 607 ; A block of free-form text for reading by 608 ; people describing the service in a short, 609 ; informative manner. 610 termdef = newline newline 611 attr-defs = *( attr-def / keydef ) 612 attr-def = id "=" attrtail 613 keydef = id "=" "keyword" newline [help-text] newline 614 attrtail = type flags newline [value-list] [help-text] 615 [value-list] newline 616 id = 1*attrchar 617 type = "string" / "integer" / "boolean" / "opaque" 618 flags = ["m"/"M"] ["l"/"L"] ["x/"X"] ["o"/"O"] 619 value-list = value newline / value "," value-list / 620 value "," newline value-list 621 help-text = 1*( "#" help-line ) 622 ; A block of free-form text for reading by 623 ; people describing the attribute and 624 ; its values. 625 help-line = *[ com-chars ] newline 626 attrchar = schemechar / ":" / "_" / "$" / "~" / "@" / "." / 627 "|" / "<" / ">" / "*" / "&" 628 value = string / integer / boolean / opaque 629 string = safe-char *[safe-char / space] safe-char 630 integer = [ "+" | "-" ] 1*digit 631 boolean = "true" / "false" 632 opaque = 1*digit ":" 4*radix64-char 633 ; The digits define the original length of 634 ; the opaque value. The restricted character 635 ; string is the radix-64 encoding of the 636 ; opaque value( [8], Sect. 5.2.) 637 ; Newlines are ignored in decoding radix-64 638 ; values. 639 com-chars = safe-char / white-sp / "," / ";"/ "%" 640 safe-char = attrchar / escaped / " " / "!" / '"' / "'" / 641 "|" / "(" / ")" / "+" / "-" / "." / ":" / 642 "=" / "?" / "[" / "]" / "{" / "/" / "{" / 643 "$" 644 ; All ASCII printable characters are 645 ; included except ",", "%", ";", and "#". 646 escaped = "%" hex hex 647 hex = digit / "A" / "B" / "C" / "D" / "E" / 648 "a" / "b" / "c" / "d" / "e" 649 white-sp = space / tab 650 newline = CR / ( CR LF ) 652 4.2. Semantics of Service Type Templates 654 The service type template defines the service attributes and service: 655 URL syntax for a particular service type. The attribute definition 656 includes the attribute type, default values, allowed values and other 657 information. 659 4.2.1. Definition of a Service Template 661 There are six items included in the service template. The semantics 662 of each item is summarized below. 664 - type 666 The scheme name of the service scheme. The scheme name consists 667 of the service type name and an optional naming authority name, 668 separated from the service type name by a period. See 4.2.2 for 669 the conventions governing service type names. 671 - version 673 The version number of the service type specification. 675 - language 677 The language of the service type specification. 679 - description 681 A description of the service suitable for inclusion in text read 682 by people. 684 - url-syntax 686 The syntax of the service type-specific URL part of the service: 687 URL. 689 - attribute definitions 691 A collection of zero or more definitions for attributes 692 associated with the service in service advertisements. 694 Each of the following subsections deals with one of these items. 696 4.2.2. Service Scheme 698 The service scheme consists of the service type name and an optional 699 naming authority name separated from the service type name by a 700 period. The service scheme is a string that is appended to the 701 'service:' URL scheme identifier, and is the value of the "type" 702 item in the template document. If the naming authority name is 703 absent it is assumed to be IANA. As discussed in Sections 1 and 3, 704 the service type name should be either a protocol name or an abstract 705 type name. 707 4.2.3. Service Type Language 709 The service type language is a two letter ISO-639 code defining the 710 language of the template [12] and is the value of the "language" 711 item. 713 4.2.4. Version Number 715 The version number of the service type template is the value of 716 the "version" item. A draft proposal starts at 0.0, and the minor 717 number increments once per revision. A standardized template starts 718 at 1.0. Additions of attributes add one to the minor number, and 719 changes of definition or removal of attributes adds one to the major 720 number. The intent is that an old service template still accurately, 721 if incompletely, defines the attributes of a service advertisement 722 if the template only differs from the advertisement in its minor 723 version. See Section 5 for more detail on how to use the version 724 attribute. 726 4.2.5. Description 728 The description is a block of text readable by people in the language 729 of the template and is the value of the "description" item. It 730 should be sufficient to identify the service to human readers and 731 provide a short, informative description of what the service does. 733 4.2.6. Syntax of the Service Type-specific URL Part 735 The syntax of the service type-specific part of the service: 736 URL is provided in the template document as the value of the 737 "url-syntax" item. The field of the service: URL is 738 designed to provide additional information to locate a service when 739 the field is not sufficient. The field 740 distinguishes URLs of a particular service type from those of another 741 service type. For instance, in the case of the lpr service type, the 742 must include the queue name [18], but other service types 743 may not require this information. 745 The syntax for the field MUST accompany the definition of 746 a new service type, unless the service advertisement is an existing 747 URL and not a service: URL. The syntax is included in the template 748 document as an ABNF [9] following the rules for URL syntax described 749 in [6]. There is no requirement for a service scheme to support 750 a . The field can be very simple, or even 751 omitted. If the service advertisement is an existing URL, the 752 "url-syntax" item SHOULD include a reference to the appropriate 753 standardization documents for the URL. 755 4.2.7. Attribute Definition 757 The bulk of the template is devoted to defining service type-specific 758 attributes. An attribute definition precisely specifies the 759 attribute's type, other restrictions on the attribute (whether it is 760 multi-valued, optional, etc), some text readable by people describing 761 the attribute, and lists of default and allowed values. The only 762 required information is the attribute's type, the rest are optional. 763 Registration, deregistration and the use of attributes in queries can 764 be accomplished using the Service Location Protocol [19] or other 765 means, and discussion of this is beyond the scope of the document. 767 Attributes are used to convey information about a given service 768 for purposes of differentiating different services of the same 769 type. They convey information to be used in the selection of a 770 particular service to bind to, either through a program offering a 771 human interface or programmatically. Attributes can be encoded in 772 different character sets and in different languages. The procedure 773 for doing this is described in Section 6. 775 An attribute definition begins with the specification of the 776 attribute's identifier and ends with a single empty line. Attributes 777 definitions have five components (in order of appearance in a 778 definition): 780 1. An attribute identifier which acts as the name of the attribute, 782 2. Attribute descriptors (type and flags), 784 3. An optional list of values which are assigned to the attribute by 785 default, 787 4. An optional block of text readable by people providing a short, 788 informative description of the attribute, 790 5. An optional list of allowed values which restrict the value or 791 values the attribute can take on. 793 4.2.7.1. The Attribute Identifier 795 An attribute definition starts with the specification of the 796 attribute's identifier. The attribute's identifier functions as the 797 name of the attribute. Note that the characters used to compose an 798 attribute identifier are restricted to those characters considered 799 unrestricted for inclusion in a URL according to [6]. The reason is 800 that services could want to display prominent attributes in their 801 service: URL advertisements. Each attribute identifier must be 802 unique in the template. Since identifiers are case folded, upper 803 case and lower case characters are the same. 805 4.2.7.2. The Attribute Type 807 Attributes can have one of five different types: string, integer, 808 boolean, opaque, or keyword. The attribute's type specification is 809 separated from the attribute's identifier by an equal sign ("=") and 810 follows the equal sign on the same line. The string, signed integer, 811 and boolean types have the standard programming language or database 812 semantics. Integers are restricted to those signed values that can 813 be represented in 32 bits. The character set used to represent 814 strings is not specified at the time the template is defined, but 815 rather is determined by the service registration. Booleans have the 816 standard syntax. Opaques are radix64 numbers [8] that can be used 817 to represent any other kind of data. Keywords are attributes that 818 have no characteristics other than their existence (and possibly the 819 descriptive text in their definition). 821 Keyword and boolean attributes impose restrictions on the following 822 parts of the attribute definition. Keyword attribute definitions 823 MUST have no flag information following the type definition, nor any 824 default or allowed values list. Boolean attributes are single value 825 only, i.e., multi-valued boolean attributes are not allowed. 827 4.2.7.3. Attribute Flags 829 Flags determine other characteristics of an attribute. With the 830 exception of keyword attributes, which may not have any flags, 831 flags follow the attribute type on the same line as the attribute 832 identifier, and are separated from each other by whitespace. Flags 833 may appear in any order after the attribute type. Other information 834 must not follow the flags, and only one flag identifier of a 835 particular flag type is allowed per attribute definition. 837 The semantics of the flags are as follows: 839 - o or O 841 Indicates that the attribute is optional. If this flag is 842 missing, the attribute is required in every service registration. 844 - m or M 846 Indicates that the attribute can take on multiple values. If 847 this flag is present, every value in a multi-valued attribute 848 has the same type as the type specified in the type part of the 849 attribute definition. Boolean attributes must not include this 850 flag. 852 - l or L 854 Indicates that attribute is literal, i.e. is not meant to be 855 translated into other languages. If this flag is present, the 856 attribute is not considered to be readable by people and should 857 not be translated when the template is translated. See Section 6 858 for more information about translation. 860 - x or X 862 Indicates that an explicit match between the attribute value and 863 a query value is required, and that partial matches are excluded. 864 An attribute which is both multi-valued and explicit (i.e. both 865 the "M" and "X" flags are set) only requires an explicit match 866 between one attribute and the query. This attribute must be 867 included in every query for the service. 869 Multi-valued attributes are an ordered set like a one-dimensional 870 array or vector in a programming language. Additions to the 871 attributes occur on the end that would have the maximum index if the 872 attribute were a vector. Deletions of individual values from the 873 attribute are not supported, and deletion of the attribute causes the 874 entire set of values to be removed. These properties allow linked 875 sets of multivalued attributes to implement lookup tables and other 876 data structures. 878 Explicit matching attributes are used for creating ACL's and other 879 purposes. As an example of using explicit matching of attributes 880 consider the following attribute definition: 882 acl = string m x #Only people whose names are on this 883 list are allowed to #access the service. george.bonner 884 charles.fowler muhammad.ali.jhin taso.fujimora 886 In this case, every query for advertisements of the service must 887 contain this attribute, and unless there is an exact match between 888 the query string and one of the allowed values, the advertisement 889 will not be returned. 891 4.2.7.4. Default Value or List 893 If the attribute definition includes a default value or, in the 894 case of multivalued attributes, a default values list, it begins on 895 the second line of the attribute definition and continues over the 896 following lines until a line ends without a comma. As a consequence, 897 newlines cannot be embedded in values. 899 Particular attribute types and definitions restrict the default 900 values list. Keyword attributes must not have a list of defaults. 901 If an optional attribute's definition has an allowed values list, 902 then a default value or list is not optional but required. The 903 motivation for this is that defining an attribute with an allowed 904 values list is meant to restrict the values the attribute can take 905 on, and requiring a default value or list assures that the default 906 value is a member of the given set of allowed values. 908 The default value or list indicates what values the attribute is 909 given if no values are assigned to the attribute when a service 910 is registered. If an optional attribute's definition includes no 911 default value or list, the following defaults are assigned: 913 1. String values are assigned the empty string, 915 2. Integer values are assigned zero, 917 3. Boolean values are assigned false, 919 4. Opaque values are assigned a byte array containing no values, 921 5. Multi-valued attributes are initialized with a single value. 923 Required attributes must always be included with the service 924 advertisement registration. 926 4.2.7.5. Descriptive Text 928 Immediately after the default values list, if any, a block of 929 descriptive text SHOULD be included in the attribute definition. 930 This text is meant to be readable by people, and should include 931 a short, informative description of the attribute. It may also 932 provide additional information, such as a description of the allowed 933 values. This text is primarily designed for display by interactive 934 browsing tools. The descriptive text is set off from the surrounding 935 definition by a crosshatch character ("#") at the beginning of 936 the line. The text should not, however, be treated as a comment 937 by parsing and other tools, since it is an integral part of the 938 attribute definition. Within the block of descriptive text, the text 939 is transferred verbatim, including indentation and line breaks, so 940 any formatting is preserved. 942 4.2.7.6. Allowed Values List 944 Finally, the attribute definition concludes with an optional 945 allowed values list. The allowed values list, if any, follows the 946 descriptive text, or, if the descriptive text is absent, the initial 947 values list. The syntax of the allowed values list is identical to 948 that of the initial values list. The allowed values list is also 949 terminated by a line that does not end in a comma. If the allowed 950 values list is present, assignment to attributes is restricted to 951 members of the list. 953 4.2.7.7. Conclusion of An Attribute Definition 955 An attribute definition concludes with a single empty line. 957 5. A Process For Standardizing New Service Types 959 New service types can be suggested simply by providing a service type 960 template and a short description for use of the service The template 961 MUST have its "version" template attribute set to 0.0. 963 The minor version number increments once with each change until it 964 achieves 1.0. There is no guarantee any version of the service 965 template is backward compatible before it reaches 1.0. 967 Once a service template has reached 1.0, the definition is "frozen" 968 for that version. New templates must be defined, of course, to 969 refine that definition, but the following rules must be followed: 971 - Any new attribute defined for the template increases the minor 972 version number by one. All other attributes for the version must 973 continue to be supported as before. A client which supports 1.x 974 can still use later versions of 1.y (where x