idnits 2.17.1 draft-ietf-svrloc-service-scheme-03.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-26) 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 4 instances of too long lines in the document, the longest one being 3 characters in excess of 72. ** 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 364: '...such information SHOULD be advertised ...' (11 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1137 has weird spacing: '...sun.com char...' -- 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' ** Obsolete normative reference: RFC 2044 (ref. '20') (Obsoleted by RFC 2279) Summary: 15 errors (**), 0 flaws (~~), 7 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 September 1997 Sun Microsystems 6 Service Templates and service: Schemes 7 draft-ietf-svrloc-service-scheme-03.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 1 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 . . . . . 9 71 3.5. Accommodating Abstract Service Types . . . . . . . . . . 9 72 3.5.1. Advertising Abstract Service Types . . . . . . . 9 74 4. Syntax and Semantics of Service Type Specifications 11 75 4.1. Syntax of Service Type Templates . . . . . . . . . . . . 11 76 4.2. Semantics of Service Type Templates . . . . . . . . . . . 14 77 4.2.1. Definition of a Service Template . . . . . . . . 14 78 4.2.2. Service Type . . . . . . . . . . . . . . . . . . 15 79 4.2.3. Service Type Language . . . . . . . . . . . . . . 15 80 4.2.4. Version Number . . . . . . . . . . . . . . . . . 15 81 4.2.5. Description . . . . . . . . . . . . . . . . . . . 15 82 4.2.6. Syntax of the Service Type-specific URL Part . . 16 83 4.2.7. Attribute Definition . . . . . . . . . . . . . . 16 85 5. A Process For Standardizing New Service Types 20 87 6. Internationalization Considerations 21 88 6.1. Language Identification and Translation . . . . . . . . . 21 90 7. Security Considerations 22 92 1. Introduction 94 This document describes a URL scheme, called service: URL, which 95 defines network access information for network services using a 96 formal notation. In addition it describes how to define a set of 97 attributes to associate with a service: URL. These attributes will 98 allow end users and programs to select between network services of 99 the same type that have different capabilities. The attributes 100 are defined in a template document that is readable by people and 101 machines. 103 A client uses attributes to select a particular service. Service 104 selection occurs by obtaining the service: URL that has the 105 configuration the client needs. Service type templates define the 106 syntax of service: URLs for a particular service type, as well as the 107 attributes which accompany a service: URL in a service advertisement. 109 Templates are used for the following distinct purposes: 111 1. Standardization 113 The template is reviewed before it is standardized. Once it is 114 standardized, all versions of the template are archived by IANA. 116 2. Service Registration 118 Servers making use of the Service Location Protocol [19] register 119 themselves and their attributes. They use the templates to 120 generate the service registrations. In registering, the service 121 must pick from among the allowable values. 123 3. Client presentation of Service Information 125 Client applications may display service information. The 126 template provides type information and explanatory text which may 127 be helpful in producing user interfaces. 129 4. Internationalization 131 If a client application has the template for a given service type 132 in two different languages, the attributes may be translated 133 between the two languages. 135 A service may register itself in more than one language using 136 templates, though it has been configured by an operator who 137 registered service attributes in a single language. 139 All grammar encoding follows the Augmented BNF (ABNF) [9] for syntax 140 specifications. 142 1.1. Terminology 144 This section introduces some terminology for describing service: 145 URLs. 147 service scheme 149 A URL scheme whose name starts with the string "service:" and 150 is followed by the service type name, constructed according to 151 the rules in this document. An example is "service:lpr:" for 152 the lpr print service [18]. 154 service: URL 156 A URL which conforms to the service scheme definition. It 157 provides at least the following: The name of an access 158 protocol, and an address where this service is active. The 159 service: URL may include url path information specific to 160 the type of service, as well as attribute information encoded 161 according to the URL grammar. The service: URL is used by 162 the Service Location Protocol to advertise and discover the 163 location of services. It may be used by other protocols and in 164 documents as well. 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 the name of a 172 particular well known port [3] by convention or or be the 173 Assigned Numbers 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 Services may advertise themselves, or advertisements may be made 206 on 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 / concrete-type 241 abstract-type = type-name [ "." naming-auth ] 242 concrete-type = protocol [ "." naming-auth ] 243 type-name = resname 244 naming-auth = resname 245 protocol = resname 246 ; An Assigned Numbers name [1] or 247 ; well known port name [3] for 248 ; the protocol. Other names may be assigned 249 ; if no prior assigned name exists. 250 resname = 1*[ alpha / digit / "+" / "-" ] 251 sap = "/" [ addr-family ] "/" site [ url-part ] 252 addr-family = *xchar ; depends on the address family 253 site = [ [ user "@" ] hostport ] / [ other-addr ] 254 hostport = host [ ":" port ] 255 other-addr = *xchar ; depends on the address family 256 host = hostname / hostnumber 257 hostname = *( domainlabel "." ) toplabel 258 alphanum = alpha / digit 259 domainlabel = alphanum / alphanum *[alphanum / "-"] alphanum 260 toplabel = alpha / alpha *[ alphanum / "-" ] alphanum 261 ipv4-number = 1*3digit 3*3("." 1*3digit) 262 ipv6-number = 32hex 263 3digit = digit digit digit 264 port = 1*digit 265 ; A port number must be included if the 266 ; protocol field does not have an IANA 267 ; assigned port number. 268 user = *[ uchar / ";" / "+" / "&" / "=" ] 269 url-part = [ url-path ] [ attr-list ] 270 url-path = 1 * ( "/" *xchar ) 271 ; Each service type must define its 272 ; own syntax consistent 273 ; with [6]. 274 attr-list = 1 * ( ";" attr-asgn ) 275 attr-asgn = attr-id / attr-id "=" attr-value 276 safe = "$" / "-" / "_" / "." / "~" 277 extra = "!" / "*" / "'" / "(" / ")" / "," / "+" 278 uchar = unreserved / escaped 279 xchar = unreserved / reserved / escaped 280 escaped = "%" hex hex 281 hex "a" / "b" / "c" / "d" / "e" / digit 282 reserved = ";" / "/" / "?" / ":" / "@" / "&" / "=" / "+" 283 unreserved = alpha / digit / safe / extra 284 alpha = "a" / "b" / "c" / "d" / "e" / "f" / "g" / 285 "h" / "i" / "j" / "k" / "l" / "m" / "n" / 286 "o" / "p" / "q" / "r" / "s" / "t" / "u" / 287 "v" / "w" / "x" / "y" / "z" / 288 "A" / "B" / "C" / "D" / "E" / "F" / "G" / 289 "H" / "I" / "J" / "K" / "L" / "M" / "N" / 290 "O" / "P" / "Q" / "R" / "S" / "T" / "U" / 291 "V" / "W" / "X" / "Y" / "Z" 292 digit = "0" / "1" / "2" / "3" / "4" / "5" / "6" / 293 "7" / "8" / "9" 295 3.2. Service URL Semantics 297 The service scheme-specific information following the "service:" 298 URL scheme identifier provides information necessary to access the 299 service. As described in the previous subsection, the form of a 300 service: URL is as follows: 302 service: URL = "service:" service-spec ":" sap 304 where has the following form: 306 /addr-family/addr-spec/url-path;attr-list 308 The field includes the field. As 309 discussed in Section 1, the can be either a concrete 310 protocol name, or an abstract type name. 312 The protocol determines the semantics of the (for service 313 access point) field, and of attributes associated with it. 314 The field indicates the network layer protocol 315 type [2] through which the service communicates with clients. The 316 field is null by default, indicating the Internet 317 Protocol (IP), but it can be used to indicate other address families 318 such as IPX [17] or Appletalk [11]. 320 The field includes a site specification (the 321 field) in the format specified by [6]. The field 322 is typically either a domain name (DNS) or an IP or other network 323 protocol address for the service, and possibly a port number. If 324 another address family is specified in the field, the 325 exact syntax of the field depends on the address family. The 326 field can be null if other information in the service URL or 327 service attributes is sufficient to use the service. 329 The field allows more information to be provided (by way of 330 and ) that can uniquely locate the service or 331 resource if the is not sufficient for that purpose. 333 An field appears at the end of the field, 334 but is never required to exist in any service location registration. 335 The field is composed of a list of semicolon (";") 336 separated attribute assignments of the form: 338 attr-id "=" attr-value 340 or for keyword attributes: 342 attr-id 344 Attributes are part of service: URLs when the attributes are required 345 to access a particular service. For instance, an ACAP [16] service 346 might require that the client authenticate with it through Kerberos. 347 Including an attribute in the service advertisement allows the ACAP 348 client to make use of the correct SASL [15] authentication mechanism. 349 The ACAP server's advertisement might look like: 351 service:acap://some.where.net;authentication=KERBEROSV4 353 Note that there can be other attributes of an ACAP server which would 354 not be appropriate to include in the URL. For instance, the list 355 of users who have access to the server is useful for selecting an 356 ACAP server, but is not required for a client to use the advertised 357 service. 359 Attributes associated with the service: URL are not typically 360 included in the service: URL. They are stored and retrieved using 361 other mechanisms. The service: URL is uniquely identified with a 362 particular service agent or resource, and is used when registering or 363 requesting the attribute information. The Service Location Protocol 364 specifies how such information SHOULD be advertised by network 365 services and obtained by client software. 367 Attributes are associated with service: URLs for three reasons: 369 1. Attributes associated with a given URL allow for automatic 370 selection of services that have certain features. Client 371 software having particular requirements can choose services 372 based on those requirements. For example, client software may 373 require a server which has the right font, or which has access to 374 specific hardware resources. 376 2. Attributes provide a mechanism by which servers can advertise 377 optional features or dynamic qualities. Clients that require or 378 prefer to make use of optional features or dynamic information 379 can proceed to do so without protocol negotiation or feature 380 selection. Attributes serve as a mechanism for servers to 381 distribute information about a wide variety of characteristics, 382 including physical location, access restrictions and dynamic 383 characteristics such as load. 385 3. Attributes support selection of service instances by 386 characteristic as opposed to simply by name. Attributes may 387 be used to give people information enabling the selection of 388 particular service using a graphical user interface, for example. 390 3.3. Use of service: URLs 392 The service: URL is intended to allow arbitrary client/server and 393 peer to peer systems to make use of a standardized dynamic service 394 access point discovery mechanism. 396 It is intended that service: URLs be selected according to the 397 suitability of associated attributes. A client application can 398 obtain the URLs of several services of the same type and distinguish 399 the most preferable among them by means of their attributes. The 400 client uses the service: URL to bind directly to a service. 402 Attributes are specified with a formal service template syntax 403 described in Section 4. If a service: URL is stored by a client or 404 an agent representing a client, the agent SHOULD also keep track of 405 the attributes which characterize the service. 407 Registrations can be checked against the formal attribute 408 specification defined in the template by the client or agent 409 representing the client. Service advertisement may be done using the 410 Service Location Protocol [19] (SLP). SLP provides a mechanism for 411 service: URLs to be obtained dynamically, according to the service's 412 attributes. 414 It is also possible to obtain service: URLs from documents and using 415 other protocols. In this case, the URL may not be accompanied by 416 the service attributes. The context in which the URL appears SHOULD 417 make it clear, if possible, when the service is appropriate to use. 418 For example, in a mail message, a service might be recommended for 419 use when the user is in a branch office. Or, an HTML document might 420 include a service: URL as a pointer to a service, describing in text 421 what the service does and who is authorized to use it. 423 3.4. Specifying the Service Type-Specific URL Syntax 425 When a service type is specified, the specification includes the 426 definition of the syntax for all URLs that are registered by services 427 of that particular type. For instance, the "lpr" service type [18] 428 is defined with service: URLs in the following form: 430 service:lpr://
/ 432 The section of the URL after the address of the printer: 434 "/" 436 is specific to the lpr service type and corresponds to the 437 field of the general service: URL syntax. This part is 438 specified when the lpr service type is specified. 440 3.5. Accommodating Abstract Service Types 442 An abstract service type is a service type that can be implemented by 443 a variety of different protocols. 445 In order to advertise an service: URL for an abstract service type 446 the 'abstract-type' grammar rule described in section 3.1 is used. 447 This will result in a URL which includes enough information to use 448 the service, namely, the protocol, address and path information. 449 Unlike 'concrete' service: URLs, however, the service type is not 450 the protocol to use. Rather it is the collective type of service. 451 This is further discussed in the section below. 453 Other methods of advertising abstract service types, such as creating 454 service type names which are compound or have their own internal 455 hierarchical convention are not encouraged. This will avoid problems 456 with interoperability. 458 Other methods of advertising for abstract service types are 459 discouraged to avoid problems with interoperability. 461 3.5.1. Advertising Abstract Service Types 463 Some services may make use of several protocols which are in common 464 use, but are distinct services in their own right. In these cases an 465 abstract service type is appropriate. What is essential is that all 466 the required information for the service be clearly defined. 468 For example, suppose a network service is being developed for 469 dynamically loading device drivers. The client requires the 470 following three pieces of information before it can successfully load 471 and instantiate the driver: 473 1. The protocol used to load the driver code, for example, "ftp", 474 "http" or "tftp" 476 2. A pathname identifying where the driver code is located, for 477 example "/systemhost/drivers/diskdrivers.drv", 479 3. The name of the driver, for example, "scsi". 481 The temptation is to form the first two items into a URL and embed 482 that into a service: URL. For example: 484 service:ftp:/x3.bean.org/drivers/diskdrivers.drv;driver=scsi 486 is a service: URL which seems to indicate where to obtain the 487 driver. 489 Rather, an abstract service-type should be used. The service type 490 which is desired is not "ftp", as the example indicates. Rather, 491 it is "device-drivers". The service: URL which should be used, 492 consistent with the rules in section [6], is the following: 494 service:device-drivers:ftp://x3.bean.org/drivers/diskdrivers.drv; 495 driver=scsi;platform=sys3.2-rs3000 497 This also supports other URLs for the same service using other 498 protocols, as in: 500 service:device-drivers:tftp://x2.bean.org/vol3/disk/drivers.drv; 501 driver=scsi;platform=sys3.2-rs3000 503 service:device-drivers:http://www.bean.org/drivers/drivpak.drv; 504 driver=scsi;platform=sys3.2-rs3000 506 Using SLP, a search for the service type "device-drivers" may return 507 all of the three URLs listed above. The client could select the most 508 appropriate access protocol for the desired resource. 510 The important thing is that the abstract service type is well 511 specified. This means that anyone who needs a resource of that type 512 will obtain all information needed to access it. In every case this 513 will include an access protocol and a network address where the 514 service is available. In the example above, there were three further 515 requirements: A URL path would have to be included for access 516 protocols indicating the document to download, and two attributes had 517 to be included to characterize the driver. 519 4. Syntax and Semantics of Service Type Specifications 521 Service type specifications are documents in a formal syntax defining 522 properties important to a service advertisement. These properties 523 are: 525 1. General information on the service type specification itself, 527 2. The syntax of the service type-specific part of the service URL, 529 3. The definition of attributes associated with a service. 531 The service type specification document is the service type template. 533 The following subsections describe the syntax and semantics of 534 service type templates. 536 4.1. Syntax of Service Type Templates 538 Service template documents are encoded in a simple form. They may 539 be translated into any language or character set, but the template 540 used for standardization MUST be encoded in UTF8 [20, 21] and be in 541 English. 543 A template document begins with a block of text assigning values to 544 five template identification items. The five template identification 545 items can appear in any order within the block, but conventionally 546 the "type" item, which assigns the service type name, occurs at the 547 very top of the document in order to provide context for the rest of 548 the the document. The attribute definition item occurs after the 549 document identification items. 551 All items end with a single blank line. Reserved characters 552 encompass ";", "%", "=", ",", "#", LF, and CR. Reserved characters 553 should be escaped. The escape sequence is the same as described 554 in [6]. Values in value lists are separated by commas. A value list 555 is terminated by a newline not preceded by a comma. If the newline 556 is preceded by a comma, the value list is interpreted to continue 557 onto the next line. 559 Attribute identifiers, attribute type names, and flags are all 560 case insensitive. For ease of presentation, upper and lower case 561 characters can be used to represent these in the template document, 562 but the result should be case-folded into lower case by parsers 563 and other tools. Newlines are significant in the grammar. They 564 delimit one item from another, as well as separating parts of items 565 internally. 567 String values are considered to be a sequence of non-whitespace 568 tokens potentially with embedded whitespace, separated from each 569 other by whitespace. Commas delimit lists of strings. String values 570 are trimmed so as to reduce any sequence of white space interior to 571 a string is reduced to a single white space. Preceding or trailing 572 white space is removed. For example: 574 " some value , another example " 576 would be trimmed to 578 "some value" and "another example". 580 Note that there can be no ambiguity in string tokenization because 581 values in value lists are separated by a comma. String tokens are 582 not delimited by double quotes (") as is usually the case with 583 programming languages. 585 Attribute tags and values can be used by some protocols for directory 586 look-up. In this case, decoding of character escapes and trimming 587 white space MUST be performed before string matching. In addition, 588 string matching SHOULD be case insensitive. 590 Templates have the following ABNF [9] grammar: 592 template = tem-attrs attr-defs 593 tem-attrs = schemetype schemevers schemelang 594 schemetext schemeurl 595 schemetype = "type" "=" scheme termdef 596 schemevers = "version" "=" version-no termdef 597 schemelang = "language" "=" isolang termdef 598 schemetext = "description" "=" newline desc-text termdef 599 schemeurl = "url-syntax" "=" newline url-bnf termdef 600 url-bnf = *[ com-chars ] 601 ; An ABNF describing the production 602 ; in the service: URL grammar of Section 3. 603 scheme = service-type [ "." naming-auth ] 604 service-type = scheme-name 605 naming-auth = scheme-name 606 scheme-name = 1*schemechar [ "." 1*schemechar ] 607 schemechar = alpha / digit / "-" / "+" / 608 version-no = 1*digit "." 1*digit 609 isolang = 2*2lower-alpha ;see [12] 610 desc-text = *[ com-chars ] 611 ; A block of free-form text for reading by 612 ; people describing the service in a short, 613 ; informative manner. 614 termdef = newline newline 615 attr-defs = *( attr-def / keydef ) 616 attr-def = id "=" attrtail 617 keydef = id "=" "keyword" newline [help-text] newline 618 attrtail = type flags newline [value-list] [help-text] 619 [value-list] newline 620 id = 1*attrchar 621 type = "string" / "integer" / "boolean" / "opaque" 622 flags = ["m"/"M"] ["l"/"L"] ["x/"X"] ["o"/"O"] 623 value-list = value newline / value "," value-list / 624 value "," newline value-list 625 help-text = 1*( "#" help-line ) 626 ; A block of free-form text for reading by 627 ; people describing the attribute and 628 ; its values. 629 help-line = *[ com-chars ] newline 630 attrchar = schemechar / ":" / "_" / "$" / "~" / "@" / "." / 631 "|" / "<" / ">" / "*" / "&" 632 value = string / integer / boolean / opaque 633 string = safe-char *[safe-char / space] safe-char 634 integer = [ "+" | "-" ] 1*digit 635 boolean = "true" / "false" 636 opaque = 1*digit ":" 4*radix64-char 637 ; The digits define the original length of 638 ; the opaque value. The restricted character 639 ; string is the radix-64 encoding of the 640 ; opaque value( [8], Sect. 5.2.) 641 ; Newlines are ignored in decoding radix-64 642 ; values. 643 com-chars = safe-char / white-sp / "," / ";"/ "%" 644 safe-char = attrchar / escaped / " " / "!" / '"' / "'" / 645 "|" / "(" / ")" / "+" / "-" / "." / ":" / 646 "=" / "?" / "[" / "]" / "{" / "/" / "{" / 647 "$" 648 ; All UTF8 printable characters are 649 ; included except ",", "%", ";", and "#". 650 escaped = "%" hex hex 651 hex = digit / "A" / "B" / "C" / "D" / "E" / 652 "a" / "b" / "c" / "d" / "e" 653 white-sp = space / tab 654 newline = CR / ( CR LF ) 656 4.2. Semantics of Service Type Templates 658 The service type template defines the service attributes and service: 659 URL syntax for a particular service type. The attribute definition 660 includes the attribute type, default values, allowed values and other 661 information. 663 4.2.1. Definition of a Service Template 665 There are six items included in the service template. The semantics 666 of each item is summarized below. 668 - type 670 The scheme name of the service scheme. The scheme name consists 671 of the service type name and an optional naming authority name, 672 separated from the service type name by a period. See 4.2.2 for 673 the conventions governing service type names. 675 - version 677 The version number of the service type specification. 679 - language 681 The language of the service type specification. 683 - description 685 A description of the service suitable for inclusion in text read 686 by people. 688 - url-syntax 690 The syntax of the service type-specific URL part of the service: 691 URL. 693 - attribute definitions 695 A collection of zero or more definitions for attributes 696 associated with the service in service advertisements. 698 Each of the following subsections deals with one of these items. 700 4.2.2. Service Type 702 The service scheme consists of the service type name and an optional 703 naming authority name separated from the service type name by a 704 period. The service scheme is a string that is appended to the 705 'service:' URL scheme identifier, and is the value of the "type" 706 item in the template document. If the naming authority name is 707 absent it is assumed to be IANA. As discussed in Sections 1 and 3, 708 the service type name should be either a protocol name or an abstract 709 type name. 711 If the service type corresponds to an abstract service type the 712 allowed protocols to satisfy it SHOULD be listed here, along with 713 their formal specifications. 715 4.2.3. Service Type Language 717 The service type language is a RFC 1766 Language Tag defining the 718 language of the template [4] and is the value of the "language" item. 720 4.2.4. Version Number 722 The version number of the service type template is the value of 723 the "version" item. A draft proposal starts at 0.0, and the minor 724 number increments once per revision. A standardized template starts 725 at 1.0. Additions of attributes add one to the minor number, and 726 changes of definition or removal of attributes adds one to the major 727 number. The intent is that an old service template still accurately, 728 if incompletely, defines the attributes of a service advertisement 729 if the template only differs from the advertisement in its minor 730 version. See Section 5 for more detail on how to use the version 731 attribute. 733 4.2.5. Description 735 The description is a block of text readable by people in the language 736 of the template and is the value of the "description" item. It 737 should be sufficient to identify the service to human readers and 738 provide a short, informative description of what the service does. 740 If the service type corresponds to a particular protocol the protocol 741 specification must be cited here. The protocol need not be a 742 standardized protocol. The template might refer to a proprietary 743 specification, and refer the reader of the template to a contact 744 person for further information. 746 4.2.6. Syntax of the Service Type-specific URL Part 748 The syntax of the service type-specific part of the service: 749 URL is provided in the template document as the value of the 750 "url-syntax" item. The field of the service: URL is 751 designed to provide additional information to locate a service when 752 the field is not sufficient. The field 753 distinguishes URLs of a particular service type from those of another 754 service type. For instance, in the case of the lpr service type, the 755 must include the queue name [18], but other service types 756 may not require this information. 758 The syntax for the field MUST accompany the definition 759 of a new service type, unless the URL scheme has already been 760 standardized and not a service: URL. The syntax is included in the 761 template document as an ABNF [9] following the rules for URL syntax 762 described in [6]. There is no requirement for a service scheme to 763 support a . The field can be very simple, 764 or even omitted. If the URL scheme has already been standardized, 765 the "url-syntax" item SHOULD include a reference to the appropriate 766 standardization documents. 768 4.2.7. Attribute Definition 770 The bulk of the template is devoted to defining service type-specific 771 attributes. An attribute definition precisely specifies the 772 attribute's type, other restrictions on the attribute (whether it is 773 multi-valued, optional, etc), some text readable by people describing 774 the attribute, and lists of default and allowed values. The only 775 required information is the attribute's type, the rest are optional. 776 Registration, deregistration and the use of attributes in queries can 777 be accomplished using the Service Location Protocol [19] or other 778 means, and discussion of this is beyond the scope of the document. 780 Attributes are used to convey information about a given service 781 for purposes of differentiating different services of the same 782 type. They convey information to be used in the selection of a 783 particular service to bind to, either through a program offering a 784 human interface or programmatically. Attributes can be encoded in 785 different character sets and in different languages. The procedure 786 for doing this is described in Section 6. 788 An attribute definition begins with the specification of the 789 attribute's identifier and ends with a single empty line. Attributes 790 definitions have five components (in order of appearance in a 791 definition): 793 1. An attribute identifier which acts as the name of the attribute, 795 2. Attribute descriptors (type and flags), 797 3. An optional list of values which are assigned to the attribute by 798 default, 800 4. An optional block of text readable by people providing a short, 801 informative description of the attribute, 803 5. An optional list of allowed values which restrict the value or 804 values the attribute can take on. 806 4.2.7.1. The Attribute Identifier 808 An attribute definition starts with the specification of the 809 attribute's identifier. The attribute's identifier functions as the 810 name of the attribute. Note that the characters used to compose an 811 attribute identifier are restricted to those characters considered 812 unrestricted for inclusion in a URL according to [6]. The reason is 813 that services could want to display prominent attributes in their 814 service: URL advertisements. Each attribute identifier must be 815 unique in the template. Since identifiers are case folded, upper 816 case and lower case characters are the same. 818 4.2.7.2. The Attribute Type 820 Attributes can have one of five different types: string, integer, 821 boolean, opaque, or keyword. The attribute's type specification is 822 separated from the attribute's identifier by an equal sign ("=") and 823 follows the equal sign on the same line. The string, signed integer, 824 and boolean types have the standard programming language or database 825 semantics. Integers are restricted to those signed values that can 826 be represented in 32 bits. The character set used to represent 827 strings is not specified at the time the template is defined, but 828 rather is determined by the service registration. Booleans have the 829 standard syntax. Opaques are radix64 numbers [8] that can be used 830 to represent any other kind of data. Keywords are attributes that 831 have no characteristics other than their existence (and possibly the 832 descriptive text in their definition). 834 Keyword and boolean attributes impose restrictions on the following 835 parts of the attribute definition. Keyword attribute definitions 836 MUST have no flag information following the type definition, nor any 837 default or allowed values list. Boolean attributes are single value 838 only, i.e., multi-valued boolean attributes are not allowed. 840 4.2.7.3. Attribute Flags 842 Flags determine other characteristics of an attribute. With the 843 exception of keyword attributes, which may not have any flags, 844 flags follow the attribute type on the same line as the attribute 845 identifier, and are separated from each other by whitespace. Flags 846 may appear in any order after the attribute type. Other information 847 must not follow the flags, and only one flag identifier of a 848 particular flag type is allowed per attribute definition. 850 The semantics of the flags are as follows: 852 - o or O 854 Indicates that the attribute is optional. If this flag is 855 missing, the attribute is required in every service registration. 857 - m or M 859 Indicates that the attribute can take on multiple values. If 860 this flag is present, every value in a multi-valued attribute 861 has the same type as the type specified in the type part of the 862 attribute definition. Boolean attributes must not include this 863 flag. 865 - l or L 867 Indicates that attribute is literal, i.e. is not meant to be 868 translated into other languages. If this flag is present, the 869 attribute is not considered to be readable by people and should 870 not be translated when the template is translated. See Section 6 871 for more information about translation. 873 The default and allowed values in the template for multivalued 874 attributes are an ordered set like an array or vector in a 875 programming language. The ordering this imposes on the attributes 876 listed in the service template allows one template to be used in 877 conjunction with another as a look-up table. This is how translation 878 between languages using templates is done, see Section 6. Note that 879 the attribute values associated with service advertisements are not 880 well ordered when retrieved from SLP, however. The order in which 881 they are stored and returned is implementation dependent. Therefore 882 one may not assume that the multiple values of a particular services' 883 attributes have any meaningful ordering. 885 4.2.7.4. Default Value or List 887 If the attribute definition includes a default value or, in the 888 case of multivalued attributes, a default values list, it begins 889 on the second line of the attribute definition and continues 890 over the following lines until a line ends without a comma. As a 891 consequence, newlines cannot be embedded in values unless escaped. 892 See Section 4.2. 894 Particular attribute types and definitions restrict the default 895 values list. Keyword attributes must not have a list of defaults. 896 If an optional attribute's definition has an allowed values list, 897 then a default value or list is not optional but required. The 898 motivation for this is that defining an attribute with an allowed 899 values list is meant to restrict the values the attribute can take 900 on, and requiring a default value or list assures that the default 901 value is a member of the given set of allowed values. 903 The default value or list indicates what values the attribute is 904 given if no values are assigned to the attribute when a service 905 is registered. If an optional attribute's definition includes no 906 default value or list, the following defaults are assigned: 908 1. String values are assigned the empty string, 910 2. Integer values are assigned zero, 912 3. Boolean values are assigned false, 914 4. Opaque values are assigned a byte array containing no values, 916 5. Multi-valued attributes are initialized with a single value. 918 Required attributes must always be included with the service 919 advertisement registration. 921 4.2.7.5. Descriptive Text 923 Immediately after the default values list, if any, a block of 924 descriptive text SHOULD be included in the attribute definition. 925 This text is meant to be readable by people, and should include 926 a short, informative description of the attribute. It may also 927 provide additional information, such as a description of the allowed 928 values. This text is primarily designed for display by interactive 929 browsing tools. The descriptive text is set off from the surrounding 930 definition by a crosshatch character ("#") at the beginning of 931 the line. The text should not, however, be treated as a comment 932 by parsing and other tools, since it is an integral part of the 933 attribute definition. Within the block of descriptive text, the text 934 is transferred verbatim, including indentation and line breaks, so 935 any formatting is preserved. 937 4.2.7.6. Allowed Values List 939 Finally, the attribute definition concludes with an optional 940 allowed values list. The allowed values list, if any, follows the 941 descriptive text, or, if the descriptive text is absent, the initial 942 values list. The syntax of the allowed values list is identical to 943 that of the initial values list. The allowed values list is also 944 terminated by a line that does not end in a comma. If the allowed 945 values list is present, assignment to attributes is restricted to 946 members of the list. 948 4.2.7.7. Conclusion of An Attribute Definition 950 An attribute definition concludes with a single empty line. 952 5. A Process For Standardizing New Service Types 954 New service types can be suggested simply by providing a service type 955 template and a short description for use of the service The template 956 MUST have its "version" template attribute set to 0.0. 958 The minor version number increments once with each change until it 959 achieves 1.0. There is no guarantee any version of the service 960 template is backward compatible before it reaches 1.0. 962 Once a service template has reached 1.0, the definition is "frozen" 963 for that version. New templates must be defined, of course, to 964 refine that definition, but the following rules must be followed: 966 - Any new optional attribute defined for the template increases 967 the minor version number by one. All other attributes for the 968 version must continue to be supported as before. A client which 969 supports 1.x can still use later versions of 1.y (where x