idnits 2.17.1 draft-ietf-svrloc-service-scheme-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 1 character 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 51: '... They SHOULD be used by administrati...' RFC 2119 keyword, line 180: '...en the service type name SHOULD either...' RFC 2119 keyword, line 221: '... The syntax of the service: URL MUST conform to [5]. Moreover, the...' RFC 2119 keyword, line 307: '...attr-list> field MAY appear at the end...' RFC 2119 keyword, line 346: '...ach service: URL SHOULD be selected ac...' (20 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1316 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. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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' ** Obsolete normative reference: RFC 1766 (ref. '3') (Obsoleted by RFC 3066, RFC 3282) -- Possible downref: Non-RFC (?) normative reference: ref. '4' ** Obsolete normative reference: RFC 1738 (ref. '5') (Obsoleted by RFC 4248, RFC 4266) ** Obsolete normative reference: RFC 2234 (ref. '7') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2222 (ref. '8') (Obsoleted by RFC 4422, RFC 4752) -- Unexpected draft version: The latest known version of draft-ietf-svrloc-lpr-scheme is -00, but you're referring to -01. -- Possible downref: Normative reference to a draft: ref. '10' ** Obsolete normative reference: RFC 2279 (ref. '12') (Obsoleted by RFC 3629) Summary: 14 errors (**), 0 flaws (~~), 3 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Service Location Working Group Erik Guttman 3 INTERNET DRAFT Charles Perkins 4 James Kempf 5 6 March 1998 Sun Microsystems 7 Service Templates and service: Schemes 8 draft-ietf-svrloc-service-scheme-08.txt 10 Status of This Memo 12 This document is a submission by the Service Location Working Group 13 of the Internet Engineering Task Force (IETF). Comments should be 14 submitted to the srvloc@corp.home.net mailing list. 16 Distribution of this memo is unlimited. 18 This document is an Internet-Draft. Internet-Drafts are working 19 documents of the Internet Engineering Task Force (IETF), its areas, 20 and its working groups. Note that other groups may also distribute 21 working documents as Internet-Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at 25 any time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as ``work in progress.'' 28 To learn the current status of any Internet-Draft, please check 29 the ``1id-abstracts.txt'' listing contained in the Internet-Drafts 30 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (North 31 Europe), ftp.nis.garr.it (South Europe), munnari.oz.au (Pacific Rim), 32 ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). 34 Abstract 36 The "service:" URL scheme name is used to define URLs (called 37 "service: URLs" in this document) that are primarily intended to 38 be used by the Service Location Protocol in order to distribute 39 service access information. These schemes provide an extensible 40 framework for client-based network software to obtain configuration 41 information required to make use of network services. When 42 registering a service: URL, the URL is accompanied by a set of 43 well-defined attributes which define the service. These attributes 44 convey configuration information to client software, or service 45 characteristics meaningful to end users. 47 This document describes a formal procedure for defining and 48 standardizing new service types and attributes for use with the 49 "service:" scheme. The formal descriptions of service types and 50 attributes are templates that are human and machine understandable. 51 They SHOULD be used by administrative tools to parse service 52 registration information and by client applications to provide 53 localized translations of service attribute strings. 55 Contents 57 Status of This Memo i 59 Abstract i 61 1. Introduction 2 62 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.2. Service Location Protocol . . . . . . . . . . . . . . . . 4 65 2. Service URL Syntax and Semantics 4 66 2.1. Service URL Syntax . . . . . . . . . . . . . . . . . . . 4 67 2.2. Service URL Semantics . . . . . . . . . . . . . . . . . . 5 68 2.3. Use of service: URLs . . . . . . . . . . . . . . . . . . 7 69 2.4. Specifying the Service Type-Specific URL Syntax . . . . . 7 70 2.5. Abstract Service Types . . . . . . . . . . . . . . . . . 8 71 2.5.1. Advertising Abstract Service Types . . . . . . . 8 73 3. Service Templates 9 74 3.1. Syntax of Service Type Templates . . . . . . . . . . . . 10 75 3.2. Semantics of Service Type Templates . . . . . . . . . . . 12 76 3.2.1. Definition of a Service Template . . . . . . . . 12 77 3.2.2. Service Type . . . . . . . . . . . . . . . . . . 13 78 3.2.3. Version Number . . . . . . . . . . . . . . . . . 13 79 3.2.4. Service Type Language . . . . . . . . . . . . . . 14 80 3.2.5. Description . . . . . . . . . . . . . . . . . . . 14 81 3.2.6. Syntax of the Service Type-specific URL Part . . 14 82 3.2.7. Attribute Definition . . . . . . . . . . . . . . 14 84 4. A Process For Standardizing New Service Types 18 86 5. IANA Considerations 20 88 6. Internationalization Considerations 21 89 6.1. Language Identification and Translation . . . . . . . . . 21 91 7. Security Considerations 22 93 A. Service Template Examples 22 94 A.1. FOO . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 95 A.2. Abstract Service Type: Net-Transducer . . . . . . . . . 23 96 A.3. Concrete Service Type: Net-Transducer:Thermometer . . . 24 97 A.4. service: URLs and SLP . . . . . . . . . . . . . . . . . . 25 99 B. Full Copyright Statement 26 101 C. Acknowledgments 26 103 1. Introduction 105 This document describes a URL scheme, called service: URL, which uses 106 a formal notation to define network access information for network 107 services. In addition it describes how to define a set of attributes 108 to associate with a service: URL. These attributes will allow end 109 users and programs to select between network services of the same 110 type that have different capabilities. The attributes are defined in 111 a template document that is readable by people and machines. 113 A client uses attributes to select a particular service. Service 114 selection occurs by obtaining the service: URL that offers the right 115 configuration for the client. Service type templates define the 116 syntax of service: URLs for a particular service type, as well as the 117 attributes which accompany a service: URL in a service registration. 119 Templates are used for the following purposes: 121 Standardization 122 The template is reviewed before it is standardized. Once 123 it is standardized, all versions of the template are 124 archived by IANA. 126 Service Registration 127 Servers making use of the Service Location Protocol [11] 128 register themselves and their attributes. They use the 129 templates to generate the service registrations. In 130 registering, the service must use the specified values 131 for its attributes. 133 Client presentation of Service Information 134 Client applications may display service information. The 135 template provides type information and explanatory text 136 which may be helpful in producing user interfaces. 138 Internationalization 139 Entities with access to the template for a given service 140 type in two different languages may translate between the 141 two languages. 143 A service may register itself in more than one language 144 using templates, though it has been configured by an 145 operator who registered service attributes in a single 146 language. 148 1.1. Terminology 150 All grammar encoding follows the Augmented BNF (ABNF) [7] for syntax 151 specifications. 153 This section introduces the following terminology: 155 service scheme 157 A URL scheme whose name starts with the string "service:" and 158 is followed by the service type name, constructed according to 159 the rules in this document. An example is "service:lpr:" for 160 the lpr print service [10]. 162 service: URL 164 A URL constructed according to the service scheme definition. 165 It typically provides at least the following: The name of an 166 access protocol, and an address locating this service. The 167 service: URL may include url path information specific to the 168 type of service, as well as attribute information encoded 169 according to the URL grammar. The service: URL is used by 170 the Service Location Protocol to register and discover the 171 location of services. It may be used by other protocols and in 172 documents as well. 174 service type 176 A name identifying the semantics by which the remainder of 177 the service: URL is to be understood. It may denote either a 178 particular network protocol, or an abstract service associated 179 with a variety of protocols. If the service type denotes a 180 particular protocol, then the service type name SHOULD either 181 be assigned the name of a particular well known port [2] by 182 convention or be the Assigned Numbers name for the service [1]. 184 abstract service type 186 A service type name which is associated with a variety of 187 different protocols. An example is given in Appendix A. 188 Section 2 discusses various ways that abstract types can be 189 accommodated. 191 service registration 193 A service: URL and optionally a set of attributes comprise 194 a service registration. This registration is made by or on 195 behalf of a given service. The URL syntax and attributes must 196 conform to the service template for the registered service. 198 service template 200 A formal description of the service attributes and service 201 scheme associated with a particular service type. 203 1.2. Service Location Protocol 205 The Service Location Protocol [11] allows service: URLs to be 206 registered and discovered. Service: URLs may be also used in other 207 contexts. Client applications discover service registrations by 208 issuing queries for services of a particular type, specifying the 209 attributes of the service: URLs to return. 211 Services may register themselves, or registrations may be made on 212 their behalf. These registrations contain a service: URL, and 213 possibly attributes and digital signatures. 215 2. Service URL Syntax and Semantics 217 This section describes the syntax and semantics of service: URLs. 219 2.1. Service URL Syntax 221 The syntax of the service: URL MUST conform to [5]. Moreover, the 222 field has been omitted from the production, since 223 plaintext transmission of passwords is discouraged. The 224 field is the service access point, and describes how to access the 225 service. Note that the syntax for the field depends upon the 226 service type definition. In addition, although both upper case and 227 lower case characters are recognized in the field 228 for convenience, the name is case-folded into lower case. Service 229 types are therefore not distinguished on the basis of case, so, for 230 example, "http" and "HTTP" designate the same service type. This is 231 consistent with general URL practice, as outlined in [5]. 233 The ABNF for a service: URL is: 235 service: URL = "service:" service-type ":" sap 236 service-type = abstract-type ":" url-scheme / concrete-type 237 abstract-type = type-name [ "." naming-auth ] 238 concrete-type = protocol [ "." naming-auth ] 239 type-name = resname 240 naming-auth = resname 241 url-scheme = resname 242 ; A recognized URL scheme name, standardized 243 ; either through common practice or through 244 ; approval of a standards body. 245 resname = alpha [ 1*(alpha / digit / "+" / "-") ] 246 sap = "//" site [ url-part ] 247 site = [ [ user "@" ] hostport ] 248 hostport = host [ ":" port ] 249 host = hostname / hostnumber 250 hostname = *( domainlabel "." ) toplabel 251 alphanum = alpha / digit 252 domainlabel = alphanum / alphanum *[alphanum / "-"] alphanum 253 toplabel = alpha / alpha *[ alphanum / "-" ] alphanum 254 hostnumber = ipv4-number / ipv6-number 255 ipv4-number = 1*3digit 3("." 1*3digit) 256 ipv6-number = 32hex 257 3digit = digit digit digit 258 port = 1*digit 259 ; A port number must be included if the 260 ; protocol field does not have an IANA 261 ; assigned port number. 262 user = *[ uchar / ";" / "+" / "&" / "=" ] 263 url-part = [ url-path ] [ attr-list ] 264 url-path = 1 * ( "/" *xchar ) 265 ; Each service type must define its own 266 ; syntax consistent with [5]. 267 attr-list = 1 * ( ";" attr-asgn ) 268 attr-asgn = attr-id / attr-id "=" attr-value 269 safe = "$" / "-" / "_" / "." / "~" 270 extra = "!" / "*" / "'" / "(" / ")" / "," / "+" 271 uchar = unreserved / escaped 272 xchar = unreserved / reserved / escaped 273 escaped = "%" hex hex 274 hex "a" / "b" / "c" / "d" / "e" / digit 275 reserved = ";" / "/" / "?" / ":" / "@" / "&" / "=" / "+" 276 unreserved = alpha / digit / safe / extra 278 Certain characters must be escaped before use. To escape any 279 character, precede the two digits indicating its ASCII value by '%'. 281 2.2. Service URL Semantics 283 The service scheme-specific information following the "service:" 284 URL scheme identifier provides information necessary to access the 285 service. As described in the previous subsection, the form of a 286 service: URL is as follows: 288 service: URL = "service:"":" 290 where has the following form: 292 ///url-path;attr-list 294 As discussed in Section 1, the can be either a 295 concrete protocol name, or an abstract type name. 297 The field includes a site specification (the 298 field) in the format specified by [5]. The field is 299 typically either a domain name (DNS) or an IP network protocol 300 address for the service, and possibly a port number. Note that use 301 of DNS hostnames is preferred for ease of renumbering. 303 The field allows more information to be provided (by way of 304 and ) that can uniquely locate the service or 305 resource if the is not sufficient for that purpose. 307 An field MAY appear at the end of the field, 308 but is never required to exist in any service location registration. 309 The field is composed of a list of semicolon (";") 310 separated attribute assignments of the form: 312 attr-id "=" attr-value 314 or for keyword attributes: 316 attr-id 318 Attributes are part of service: URLs when the attributes are required 319 to access a particular service. For instance, an ACAP [9] service 320 might require that the client authenticate with it through Kerberos. 321 Including an attribute in the service registration allows the ACAP 322 client to make use of the correct SASL [8] authentication mechanism. 323 The ACAP server's registration might look like: 325 service:acap://some.where.net;authentication=KERBEROSV4 327 Note that there can be other attributes of an ACAP server which 328 are not appropriate to include in the URL. For instance, the list 329 of users who have access to the server is useful for selecting an 330 ACAP server, but is not required for a client to use the registered 331 service. 333 Attributes associated with the service: URL are not typically 334 included in the service: URL. They are stored and retrieved using 335 other mechanisms. The service: URL is uniquely identified with a 336 particular service agent or resource, and is used when registering or 337 requesting the attribute information. The Service Location Protocol 338 specifies how such information is registered by network services and 339 obtained by client software. 341 2.3. Use of service: URLs 343 A service: URL enables application agents to use a standardized 344 dynamic service access point discovery mechanism. 346 Each service: URL SHOULD be selected according to the suitability of 347 associated attributes. A client application can distinguish the most 348 preferable among several services of the same type by means of their 349 attributes. The client then uses the service: URL to communicate 350 directly to a service. 352 Attributes are specified with a formal service template syntax 353 described in Section 3. If a service: URL registration includes 354 attributes, the registering agent SHOULD also keep track of the 355 attributes which characterize the service. Registrations can be 356 checked against the formal attribute specification defined in the 357 template by the client or agent representing the client. 359 Service registration are typically done using the Service Location 360 Protocol [11] (SLP). SLP provides a mechanism for service: URLs to be 361 obtained dynamically, according to the service's attributes. 363 It is also possible to obtain service: URLs from documents and using 364 other protocols. In this case, the URL may not be accompanied by 365 the service attributes. The context in which the URL appears should 366 make it clear, if possible, when the service is appropriate to use. 367 For example, in a mail message, a service might be recommended for 368 use when the user is in a branch office. Or, an HTML document might 369 include a service: URL as a pointer to a service, describing in text 370 what the service does and who is authorized to use it. 372 2.4. Specifying the Service Type-Specific URL Syntax 374 When a service type is specified, the specification includes the 375 definition of the syntax for all URLs that are registered by services 376 of that particular type. For instance, the "lpr" service type may be 377 defined with service: URLs in the following form: 379 service:printer:lpr://
/ 381 The section of the URL after the address of the printer: 383 "/" 385 is specific to the lpr service type and corresponds to the 386 field of the general service: URL syntax. This part is 387 specified when the lpr service type is specified. 389 2.5. Abstract Service Types 391 An abstract service type is a service type that can be implemented by 392 a variety of different service agents. 394 In order to register a service: URL for an abstract service type, the 395 'abstract-type' grammar rule described in section 3.1 is used. This 396 will result in a URL which includes enough information to use the 397 service, namely, the protocol, address and path information. Unlike 398 'concrete' service: URLs, however, the service type is not enough 399 to determine the service access. Rather, an abstract service type 400 denotes a class of service types. 402 2.5.1. Advertising Abstract Service Types 404 Some services may make use of several protocols that are in common 405 use and are distinct services in their own right. In these cases an 406 abstract service type is appropriate. What is essential is that all 407 the required information for the service is clearly defined. 409 For example, suppose a network service is being developed for 410 dynamically loading device drivers. The client requires the 411 following four pieces of information before it can successfully load 412 and execute the driver: 414 1. The protocol used to load the driver code, for example, "ftp", 415 "http" or "tftp" 417 2. A pathname identifying where the driver code is located, for 418 example "/systemhost/drivers/diskdrivers.drv", 420 3. The name of the driver, for example, "scsi". 422 4. The name of the platform, for example, "sys3.2-rs3000". 424 The temptation is to form the first two items into a URL and embed 425 that into a service: URL. As an example which should be avoided, 427 service:ftp://x3.bean.org/drivers/diskdrivers.drv;driver=scsi; 428 platform=sys3.2-rs3000 430 is a service: URL which seems to indicate where to obtain the driver. 432 Rather, an abstract service-type SHOULD be used. The service type is 433 not "ftp", as the example indicates. Rather, it is "device-drivers". 434 The service: URL that should be used, consistent with the rules in 435 section [6], is the following: 437 service:device-drivers:ftp://x3.bean.org/drivers/diskdrivers.drv; 438 driver=scsi;platform=sys3.2-rs3000 440 Other URLs for the same service using other protocols are also 441 supported, as in: 443 service:device-drivers:tftp://x2.bean.org/vol3/disk/drivers.drv; 444 driver=scsi;platform=sys3.2-rs3000 446 service:device-drivers:http://www.bean.org/drivers/drivpak.drv; 447 driver=scsi;platform=sys3.2-rs3000 449 Using Service Location Protocol, a service request for the service 450 type "device-drivers" may return all of the three URLs listed above. 451 The attributes associated with the services desired are used to 452 formulate the queries, as: 454 = service:device-drivers 455 = (& (driver=scsi)(platform=sys3.2-rs3000)) 457 This query will return all three URLs listed above. If only 458 the 'tftp' URL was desired, would be set to 459 "service:device-drivers:tftp". 461 The fundamental requirement is that the abstract service type MUST 462 specify enough information to access the service. In every case, a 463 well-specified abstract type will include either an access protocol 464 and a network address where the service is available, or an embedded 465 URL for a standardized URL scheme that describes how to access the 466 service. In the example above, there are three further requirements: 467 A URL path is included for access protocols indicating the document 468 to download, and two attributes are included to characterize the 469 driver. 471 3. Service Templates 473 Service templates are documents in a formal syntax defining 474 properties important to service registration. These properties are: 476 1. General information on the service type specification itself, 478 2. The syntax of the service type-specific part of the service URL, 480 3. The definition of attributes associated with a service. 482 The service type specification document is the service type template. 484 The following subsections describe the syntax and semantics of 485 service type templates. 487 3.1. Syntax of Service Type Templates 489 Service template documents are encoded in a simple form. They may be 490 translated into any language or character set, but the template used 491 for standardization MUST be encoded in the ASCII subset of UTF8 [12] 492 and be in English. 494 A template document begins with a block of text assigning values to 495 five document identification items. The five identification items 496 can appear in any order within the block, but conventionally the 497 "type" item, which assigns the service type name, occurs at the very 498 top of the document in order to provide context for the rest of 499 the the document. The attribute definition item occurs after the 500 document identification items. 502 All items end with a blank line. The reserved characters are ";", 503 "%", "=", ",", "#", LF, and CR. Reserved characters MUST be escaped. 504 The escape sequence is the same as described in [5]. 506 The service template is encoded in a UTF8 character set, but 507 submitted as a part of an internet-draft, which is encoded in ASCII 508 characters. All characters which are outside of the ASCII range MUST 509 be escaped using the % HEX HEX syntax. For example, the letter e 510 accent aigue would be represented as "%c3%a9". Unfortunately, this 511 will detract from the readability of the service template in the 512 internet draft. Hopefully some public domain tools will emerge for 513 translating escaped UTF8 characters into humanly readable ones. 515 Values in value lists are separated by commas. A value list is 516 terminated by a newline not preceded by a comma. If the newline is 517 preceded by a comma, the value list is interpreted to continue onto 518 the next line. 520 Attribute identifiers, attribute type names, and flags are all 521 case insensitive. For ease of presentation, upper and lower case 522 characters can be used to represent these in the template document. 523 Newlines are significant in the grammar. They delimit one item from 524 another, as well as separating parts of items internally. 526 String values are considered to be a sequence of non-whitespace 527 tokens potentially with embedded whitespace, separated from each 528 other by whitespace. Commas delimit lists of strings. String values 529 are trimmed so as to reduce any sequence of white space interior to a 530 string to a single white space. Preceding or trailing white space is 531 removed. For example: 533 " some value , another example " 535 is trimmed to 537 "some value" and "another example". 539 Note that there can be no ambiguity in string tokenization because 540 values in value lists are separated by a comma. String tokens are 541 not delimited by double quotes (") as is usually the case with 542 programming languages. 544 Attribute tags and values are useful for directory look-up. In this 545 case, decoding of character escapes and trimming white space MUST 546 be performed before string matching. In addition, string matching 547 SHOULD be case insensitive. 549 Templates obey the following ABNF [7] grammar: 551 template = tem-attrs attr-defs 552 tem-attrs = schemetype schemevers schemelang 553 schemetext schemeurl 554 schemetype = "type" "=" scheme termdef 555 schemevers = "version" "=" version-no termdef 556 schemelang = "language" "=" langtag termdef 557 schemetext = "description" "=" newline desc-text termdef 558 schemeurl = "url-syntax" "=" newline url-bnf termdef 559 url-bnf = *[ com-chars ] 560 ; An ABNF describing the production 561 ; in the service: URL grammar of Section 2.1. 562 scheme = service-type [ "." naming-auth ] 563 service-type = scheme-name 564 naming-auth = scheme-name 565 scheme-name = alpha [1*schemechar] [ "." 1*schemechar ] 566 schemechar = alpha / digit / "-" / "+" / 567 version-no = 1*digit "." 1*digit 568 langtag = 2*lower-alpha ;see [3] 569 desc-text = *[ com-chars ] 570 ; A block of free-form text for reading by 571 ; people describing the service in a short, 572 ; informative manner. 573 termdef = newline newline 574 attr-defs = *( attr-def / keydef ) 575 attr-def = id "=" attrtail 576 keydef = id "=" "keyword" newline [help-text] newline 577 attrtail = type flags newline [value-list] [help-text] 578 [value-list] newline 579 id = 1*attrchar 580 type = "string" / "integer" / "boolean" / "opaque" 581 flags = ["m"/"M"] ["l"/"L"] ["o"/"O"] ["x"/"X"] 582 value-list = value newline / value "," value-list / 583 value "," newline value-list 584 help-text = 1*( "#" help-line ) 585 ; A block of free-form text for reading by 586 ; people describing the attribute and 587 ; its values. 588 help-line = *[ com-chars ] newline 589 attrchar = schemechar / ":" / "_" / "$" / "~" / "@" / "." / 590 "|" / "<" / ">" / "*" / "&" 591 value = string / integer / boolean / opaque 592 string = safe-char *[safe-char / white-sp] safe-char 593 integer = [ "+" | "-" ] 1*digit 594 boolean = "true" / "false" 595 opaque = "\FF" 1*( "\" HEXDIGIT HEXDIGIT ) 596 ; Each byte is encoded in one HEXDIGIT pair. 597 ; The preceding escaped byte is illegal in 598 ; UTF8 encoding; it indicates binary data 599 ; follows which is not escaped UTF8 data. 600 com-chars = safe-char / white-sp / "," / ";"/ "%" 601 safe-char = attrchar / escaped / " " / "!" / '"' / "'" / 602 "|" / "(" / ")" / "+" / "-" / "." / ":" / 603 "=" / "?" / "[" / "]" / "{" / "/" / "{" / 604 "$" 605 ; All UTF8 printable characters are 606 ; included except ",", "%", ";", and "#". 607 escaped = "%" hex hex 608 hex = digit / "A" / "B" / "C" / "D" / "E" / 609 "a" / "b" / "c" / "d" / "e" 610 white-sp = space / tab 611 newline = CR / ( CR LF ) 613 3.2. Semantics of Service Type Templates 615 The service type template defines the service attributes and service: 616 URL syntax for a particular service type. The attribute definition 617 includes the attribute type, default values, allowed values and other 618 information. 620 3.2.1. Definition of a Service Template 622 There are six items included in the service template. The semantics 623 of each item is summarized below. 625 type The scheme name of the service scheme. The scheme name 626 consists of the service type name and an optional naming 627 authority name, separated from the service type name by a 628 period. See 3.2.2 for the conventions governing service 629 type names. 631 version The version number of the service type specification. 633 language The language of the service type specification. 635 description 636 A description of the service suitable for inclusion in 637 text read by people. 639 url-syntax 640 The syntax of the service type-specific URL part of the 641 service: URL. 643 attribute definitions 644 A collection of zero or more definitions for attributes 645 associated with the service in service registrations. 647 Each of the following subsections deals with one of these items. 649 3.2.2. Service Type 651 The service scheme consists of the service type name and an optional 652 naming authority name separated from the service type name by a 653 period. The service scheme is a string that is appended to the 654 'service:' URL scheme identifier, and is the value of the "type" 655 item in the template document. If the naming authority name is 656 absent it is assumed to be IANA. 658 3.2.3. Version Number 660 The version number of the service type template is the value of the 661 "version" item. A draft proposal starts at 0.0, and the minor number 662 increments once per revision. A standardized template starts at 1.0. 663 Additions of optional attributes add one to the minor number, and 664 additions of required attributes, changes of definition, or removal 665 of attributes add one to the major number. The intent is that an 666 old service template still accurately, if incompletely, defines the 667 attributes of a service registration if the template only differs 668 from the registration in its minor version. See Section 4 for more 669 detail on how to use the version attribute. 671 3.2.4. Service Type Language 673 The service type language is a RFC 1766 Language Tag defining the 674 language of the template [3] and is the value of the "language" item. 676 3.2.5. Description 678 The description is a block of text readable by people in the language 679 of the template and is the value of the "description" item. It 680 should be sufficient to identify the service to human readers and 681 provide a short, informative description of what the service does. 683 If the service type corresponds to a particular protocol, the 684 protocol specification must be cited here. The protocol need not be 685 a standardized protocol. The template might refer to a proprietary 686 specification, and refer the reader of the template to a contact 687 person for further information. 689 3.2.6. Syntax of the Service Type-specific URL Part 691 The syntax of the service type-specific part of the service: 692 URL is provided in the template document as the value of the 693 "url-syntax" item. The field of the service: URL is 694 designed to provide additional information to locate a service when 695 the field is not sufficient. The field 696 distinguishes URLs of a particular service type from those of another 697 service type. For instance, in the case of the lpr service type, the 698 must include the queue name [10], but other service types 699 may not require this information. 701 The syntax for the field MUST accompany the definition 702 of a new service type, unless the URL scheme has already been 703 standardized and is not a service: URL. The syntax is included in 704 the template document as an ABNF [7] following the rules for URL 705 syntax described in [5]. The field can be very simple, 706 or even omitted. If the URL scheme has already been standardized, 707 the "url-syntax" item SHOULD include a reference to the appropriate 708 standardization documents. Abstract service types may defer this 709 field to the template documents describing their concrete instances. 711 3.2.7. Attribute Definition 713 The bulk of the template is typically devoted to defining service 714 type-specific attributes. An attribute definition precisely 715 specifies the attribute's type, other restrictions on the attribute 716 (whether it is multi-valued, optional, etc), some text readable by 717 people describing the attribute, and lists of default and allowed 718 values. The only required information is the attribute's type, the 719 rest are optional. Registration, deregistration and the use of 720 attributes in queries can be accomplished using the Service Location 721 Protocol [11] or other means. 723 Attributes are used to convey information about a given service for 724 purposes of differentiating different services of the same type. 725 They convey information to be used in the selection of a particular 726 service to establish communicate with, either through a program 727 offering a human interface or programmatically. Attributes can be 728 encoded in different character sets and in different languages. The 729 procedure for doing this is described in Section 6. 731 An attribute definition begins with the specification of the 732 attribute's identifier and ends with a single empty line. Attributes 733 definitions have five components (in order of appearance in a 734 definition): 736 1. An attribute identifier (the name of the attribute), 738 2. Attribute descriptors (type and flags), 740 3. An optional list of values which are assigned to the attribute by 741 default, 743 4. An optional block of text readable by people providing a short, 744 informative description of the attribute, 746 5. An optional list of allowed values which restrict the value or 747 values the attribute can take on. 749 3.2.7.1. The Attribute Identifier 751 An attribute definition starts with the specification of the 752 attribute's identifier. The attribute's identifier serves as the 753 name of the attribute. Note that the characters used to compose an 754 attribute identifier are restricted to those characters considered 755 unrestricted for inclusion in a URL according to [5]. The reason 756 is that services can display prominent attributes in their service: 757 URL registrations. Each attribute identifier must be unique in the 758 template. Since identifiers are case folded, upper case and lower 759 case characters are the same. 761 3.2.7.2. The Attribute Type 763 Attributes can have one of five different types: string, signed 764 integer, boolean, opaque, or keyword. The attribute's type 765 specification is separated from the attribute's identifier by 766 an equal sign ("=") and follows the equal sign on the same line. 767 The string, signed integer, and boolean types have the standard 768 programming language or database semantics. Integers are restricted 769 to those signed values that can be represented in 32 bits. Booleans 770 are either TRUE or FALSE. Opaques are radix64 numbers [6] that can be 771 used to represent any other kind of data. Keywords are attributes 772 that have no characteristics other than their existence (and possibly 773 the descriptive text in their definition). 775 Keyword and boolean attributes impose restrictions on the following 776 parts of the attribute definition. Keyword attribute definitions 777 MUST have no flag information following the type definition, nor any 778 default or allowed values list. Boolean attributes are single value 779 only, i.e., multi-valued boolean attributes are not allowed. 781 3.2.7.3. Attribute Flags 783 Flags determine other characteristics of an attribute. With the 784 exception of keyword attributes, which may not have any flags, 785 flags follow the attribute type on the same line as the attribute 786 identifier, and are separated from each other by whitespace. Flags 787 may appear in any order after the attribute type. Other information 788 must not follow the flags, and only one flag identifier of a 789 particular flag type is allowed per attribute definition. 791 The semantics of the flags are as follows: 793 - o or O 795 Indicates that the attribute is optional. If this flag is 796 missing, the attribute is required in every service registration. 798 - m or M 800 Indicates that the attribute can take on multiple values. If 801 this flag is present, every value in a multi-valued attribute 802 has the same type as the type specified in the type part of the 803 attribute definition. Boolean attributes must not include this 804 flag. 806 - l or L 807 Indicates that attribute is literal, i.e., is not meant to be 808 translated into other languages. If this flag is present, the 809 attribute is not necessarily human-readable, and should not be 810 translated when the template is translated. See Section 6 for 811 more information about translation. 813 - x or X 815 Indicates that clients SHOULD include the indicated attribute 816 in requests for services. Neglecting to include this attribute 817 will not sufficiently differentiate the service. If services are 818 obtained without selecting this attribute they will quite likely 819 be useless to the client. 821 The values for multivalued attributes are an unordered set. 822 Deletions of individual values from a multivalued attribute are not 823 supported, and deletion of the attribute causes the entire set of 824 values to be removed. 826 3.2.7.4. Default Value or List 828 If the attribute definition includes a default value or, in the 829 case of multivalued attributes, a default values list, it begins on 830 the second line of the attribute definition and continues over the 831 following lines until a line ends without a comma. Newlines cannot 832 be embedded in values unless escaped. See Section 2.1. 834 Particular attribute types and definitions restrict the default 835 values list. Keyword attributes MUST NOT have a list of defaults. 836 If an optional attribute's definition has an allowed values list, 837 then a default value or list is REQUIRED. The motivation for this 838 is that defining an attribute with an allowed values list is meant 839 to restrict the values the attribute can take on, and requiring a 840 default value or list assures that the default value is a member of 841 the given set of allowed values. 843 The default value or list indicates what values the attribute is 844 given if no values are assigned to the attribute when a service 845 is registered. If an optional attribute's definition includes no 846 default value or list, the following defaults are assigned: 848 1. String values are assigned the empty string, 850 2. Integer values are assigned zero, 852 3. Boolean values are assigned false, 854 4. Opaque values are assigned a byte array containing no values, 855 5. Multi-valued attributes are initialized with a single value. 857 For purposes of translating nonliteral attributes, the default values 858 list is taken to be an ordered set, and translations MUST maintain 859 that order. 861 3.2.7.5. Descriptive Text 863 Immediately after the default values list, if any, a block of 864 descriptive text SHOULD be included in the attribute definition. 865 This text is meant to be readable by people, and should include 866 a short, informative description of the attribute. It may also 867 provide additional information, such as a description of the allowed 868 values. This text is primarily designed for display by interactive 869 browsing tools. The descriptive text is set off from the surrounding 870 definition by a crosshatch character ("#") at the beginning of 871 the line. The text should not, however, be treated as a comment 872 by parsing and other tools, since it is an integral part of the 873 attribute definition. Within the block of descriptive text, the text 874 is transferred verbatim, including indentation and line breaks, so 875 any formatting is preserved. 877 3.2.7.6. Allowed Values List 879 Finally, the attribute definition concludes with an optional 880 allowed values list. The allowed values list, if any, follows the 881 descriptive text, or, if the descriptive text is absent, the initial 882 values list. The syntax of the allowed values list is identical to 883 that of the initial values list. The allowed values list is also 884 terminated by a line that does not end in a comma. If the allowed 885 values list is present, assignment to attributes is restricted to 886 members of the list. 888 As with the default values list, the allowed values list is also 889 considered to be an ordered set for purposes of translation. 891 3.2.7.7. Conclusion of An Attribute Definition 893 An attribute definition concludes with a single empty line. 895 4. A Process For Standardizing New Service Types 897 New service types can be suggested simply by providing a service type 898 template and a short description about how to use the service. The 899 template MUST have its "version" template attribute set to 0.0. 901 MAJOR revision numbers come before the '.', MINOR revision numbers 902 come after the '.'. 904 The minor version number increments once with each change until it 905 achieves 1.0. There is no guarantee any version of the service 906 template is backward compatible before it reaches 1.0. 908 Once a service template has reached 1.0, the definition is "frozen" 909 for that version. New templates must be defined, of course, to 910 refine that definition, but the following rules must be followed: 912 A MINOR revision number signifies the introduction of a compatible 913 change. A MAJOR revision number signifies the introduction of an 914 incompatible change. This is formalized by the following rules: 916 - Any new optional attribute defined for the template increases 917 the minor version number by one. All other attributes for the 918 version must continue to be supported as before. A client which 919 supports 1.x can still use later versions 1.y (where x".""." 983 Each of these fields are defined in Section 2. They correspond 984 to the values of the template fields "type", "version" and 985 "lang". The files for the example templates in this 986 document are called "foo.0.0.en", "Net-Transducer.0.0.en" and 987 "Net-Transducer:Thermomoter.0.0.en". See Appendix A. 989 The reviewer will ensure that the template submission to IANA has the 990 correct version number in the "version" and "lang" fields. 992 No service type template will be accepted for inclusion in the 993 service template registry unless the Internet Draft submitted 994 includes a security considerations section and contact information 995 for the template document author. 997 The IANA will maintain a registry containing both the service type 998 templates, and the template description document containing the 999 service type template, including all previous versions. The IANA 1000 will receive notice by email from the reviewers, which will contain a 1001 reference to the Internet Draft that contains the service template. 1002 This Internet Draft will be edited to remove the Internet Draft 1003 headers and replace them with a simple header stating "This document 1004 contains a Service Type Template." 1006 Neither the reviewer nor the IANA will take any position on claims of 1007 copyright or trademark issues with regard to templates. 1009 6. Internationalization Considerations 1011 The service: URL must be encoded using the rules set forth in [5]. 1012 The character set encoding is limited to specific ranges within the 1013 US-ASCII character set [4]. 1015 The template is encoded in UTF8 characters. 1017 The template must not include any characters outside of the US-ASCII 1018 printable range unless these values are escaped. For instance, a 1019 template in Greek would encode the lower case alpha as "which is the 1020 UTF8 encoding of the Unicode value 0x03b1. Non-US-ASCII characters 1021 in templates will NOT be human readable until un-escaped. 1023 6.1. Language Identification and Translation 1025 The language used in attribute strings should be identified using the 1026 "language" template item as defined by [3]. 1028 A program can translate a service registration from one language to 1029 another provided it has both the template of the language for the 1030 registration and the template of the desired target language. All 1031 standardized attributes are in the same order in both templates, 1032 allowing one template to be used as a 'look up table' into the other. 1033 A string in one language can be translated to another by finding the 1034 string in the corresponding position in the both templates. 1036 If a template in a desired language is not available, a "best-effort" 1037 translation can always be made from an existing template. 1039 Non-literal attribute definitions, attribute identifiers, attribute 1040 type names, attribute flags, and the boolean constants "true" 1041 and "false" are never translated. Translation of attribute 1042 identifiers is prohibited because, as with domain names, they can 1043 potentially be part of a service: URL and therefore their character 1044 set is restricted. In addition, as with variable identifiers in 1045 programming languages, they could become embedded into program code. 1046 Other strings, including the descriptive help text, are directly 1047 translatable from one language to another. 1049 When the service type is standardized, more than one document can 1050 be submitted for review. One service type description is approved 1051 as a master, so that when a service type template is updated in one 1052 language, all the translations (at least eventually) reflect the same 1053 semantics. If no document exists describing the standard translation 1054 of the service type, a 'best effort' translation for strings should 1055 be done. 1057 7. Security Considerations 1059 Service type templates provide information that is used to interpret 1060 information obtained by the Service Location Protocol. If these 1061 templates are modified or false templates are distributed, services 1062 may not correctly register themselves, or clients might not be able 1063 to interpret service information. 1065 The service: URLs themselves MAY specify the service access point 1066 and protocol for a particular service type. The Service Location 1067 Protocol [11] distributes service: URLs and has an authentication 1068 mechanism that allows service: URLs of registered services to be 1069 signed and for the signatures to be verified by clients. 1071 Each Service Template will include a security considerations section 1072 which will describe security issues with using the service scheme for 1073 the specific Service Type. 1075 A. Service Template Examples 1077 The text in the template example sections is to be taken as being a 1078 single file. They are completely fictitious (i.e., the examples do 1079 not represent real services). 1081 The FOO example shows how to use service templates for an application 1082 that has very few attributes. Clients request the FOO server where 1083 their user data is located by including their user name as the value 1084 of the user attribute. 1086 The Net-Transducer example shows how abstract service types are 1087 defined and how a corresponding concrete instance is defined. A 1088 system might support any of several NetTransducer services. Here we 1089 give only one concrete instance of the abstract type. 1091 It is not necessary to register concrete templates for an abstract 1092 service type if the abstract service type template is completely 1093 clear as to what possible values can be used as a concrete type, and 1094 what their interpretation is. 1096 A.1. FOO 1098 -------------------------template begins here----------------------- 1099 type=FOO 1101 version=0.0 1103 lang=en 1105 description= 1106 The FOO service URL provides the location of an FOO service. 1108 url-syntax= 1109 url-path= ; There is no URL path defined for a FOO URL. 1111 users= string M L O 1112 # The list of all users which the FOO server supports. 1114 groups= string M L O 1115 # The list of all groups which the FOO server supports. 1116 --------------------------template ends here------------------------ 1118 The Internet Draft describing the FOO scheme template must indicate 1119 contact information and security considerations, e.g., 1121 contact="Erik Guttman" 1123 security considerations= 1124 If the USER and GROUPS attributes are included a 1125 possibility exists that the list of identities for users or groups 1126 can be discovered. This information would otherwise be difficult 1127 to discover. 1129 A.2. Abstract Service Type: Net-Transducer 1131 The Internet Draft for the service type template contains the 1132 following text: 1134 -------------------------template begins here----------------------- 1135 type=Net-Transducer 1137 version=0.0 1138 lang=en 1140 description= 1141 This is an abstract service type. The purpose of the Net- 1142 Transducer service type is to organize into a single category 1143 all network enabled Transducers which have certain properties. 1145 url-syntax= 1146 url-path= ; Depends on the concrete service type. 1147 ; See these templates. 1149 sample-units= string L 1150 # The units of sample that the Transducer provides, for instance 1151 # C (degrees Celsius), V (Volts), kg (Kilograms), etc. 1153 sample-resolution= string L 1154 # The resolution of the Transducer. For instance, 10^-3 means 1155 # that the Transducer has resolution to 0.001 unit. 1157 sample-rate= integer L 1158 # The speed at which samples are obtained per second. For 1159 # instance 1000 means that one sample is obtained every millisecond. 1161 --------------------------template ends here------------------------ 1163 In addition, the following format might be used for the needed 1164 contact and security considerations information. 1165 .......... 1167 contact="Erik Guttman" 1169 security considerations= 1170 See the security considerations of the concrete service types. 1172 A.3. Concrete Service Type: Net-Transducer:Thermometer 1174 -------------------------template begins here----------------------- 1175 type=service:Net-Transducer:Thermometer 1177 version=0.0 1179 lang=en 1181 description= 1182 The Thermometer is a Net-Transducer capable of reading temperature. 1183 The data is read by opening a TCP connection to one of the ports 1184 in the service URL and reading an ASCII string until an NULL 1185 character is encountered. The client may continue reading data at 1186 no faster than the sample-rate, or close the connection. 1188 url-syntax= 1189 url-path = ; ports 1190 port-list = ";ports=" port-list 1191 ports = port / port "," ports 1192 ; See the Service URL production rule. 1193 ; These are the ports connections can be made on. 1195 location-description=string 1196 # The location where the Thermometer is located. 1198 operator=string O 1199 # The operator to contact to have the Thermometer serviced. 1201 --------------------------template ends here------------------------ 1203 ......... 1205 contact="Erik Guttman" 1207 security considerations= 1208 There is no authentication of the Transducer output. Thus, 1209 the Thermometer output could easily be spoofed. 1211 A.4. service: URLs and SLP 1213 A user with an FOO enabled calendar application should not be 1214 bothered with knowing the address of their FOO server. The 1215 calendar client program can use SLP to obtain the FOO service: URL 1216 automatically, say 'service:foo://server1.nosuch.org', by issuing 1217 a Service Request. In the event that this FOO server failed, the 1218 Calendar client can issue the same service request again to find the 1219 backup FOO server, say 'service:foo://server2.nosuch.org'. In both 1220 cases, the service: URL conforms to the FOO service template as do 1221 the associated attributes (user and group.) 1223 A network thermometer could be advertised as: 1225 URL = service:net-transducer:thermometer://v33.test/ports=3211 1226 Attributes = (location-description=Missile bay 32), 1227 (operator=Joe Agent), (sample-units=C), 1228 (sample-resolution=10^-1),(sample-rate=10) 1230 This might be very useful for a technician who wanted to find a 1231 Thermometer in Missile bay 32, for example. 1233 B. Full Copyright Statement 1235 Copyright (C) The Internet Society (1997). All Rights Reserved. 1237 This document and translations of it may be copied and furnished to 1238 others, and derivative works that comment on or otherwise explain it 1239 or assist in its implmentation may be prepared, copied, published 1240 and distributed, in whole or in part, without restriction of any 1241 kind, provided that the above copyright notice and this paragraph 1242 are included on all such copies and derivative works. However, 1243 this document itself may not be modified in any way, such as by 1244 removing the copyright notice or references to the Internet Society 1245 or other Internet organizations, except as needed for the purpose 1246 of developing Internet standards in which case the procedures 1247 for copyrights defined in the Internet Standards process must be 1248 followed, or as required to translate it into languages other than 1249 English. 1251 The limited permissions granted above are perpetual and will not be 1252 revoked by the Internet Society or its successors or assigns. 1254 This document and the information contained herein is provided on an 1255 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1256 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1257 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1258 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1259 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." 1261 C. Acknowledgments 1263 Ryan Moats suggestions were very useful in producing this document. 1265 References 1267 [1] Protocol and service names, October 1994. 1268 ftp://ftp.isi.edu/in-notes/iana/assignments/service-names. 1270 [2] Port numbers, July 1997. 1271 ftp://ftp.isi.edu/in-notes/iana/assignments/port-numbers. 1273 [3] H. Alvestrand. Tags for the Identification of Languages. RFC 1274 1766, March 1995. 1276 [4] ANSI. Coded Character Set -- 7-bit American Standard code for 1277 Information Interchange. X3.4-1986, 1986. 1279 [5] T. Berners-Lee, L. Masinter, and M. McCahill. Uniform Resource 1280 Locators (URL). RFC 1738, December 1994. 1282 [6] N. Borenstein and N. Freed. Multipurpose Internet Mail 1283 Extensions (MIME) Part One: Format of Internet Message Bodies. 1284 RFC 2045, November 1996. 1286 [7] D. Crocker and P. Overell. Augmented BNF for Syntax 1287 Specifications: ABNF. RFC 2234, November 1997. 1289 [8] J. Myers. Simple Authentication and Security Layer (SASL). RFC 1290 2222, October 1997. 1292 [9] C. Newman and J. G. Myers. ACAP -- Application Configuration 1293 Access Prototol. RFC 2244, November 1997. 1295 [10] Pete St. Pierre. Definition of lpr: URLs for use with Service 1296 Location. draft-ietf-svrloc-lpr-scheme-01.txt, December 1997. 1297 (work in progress). 1299 [11] J. Veizades, E. Guttman, C. Perkins, and S. Kaplan. Service 1300 Location Protocol. RFC 2165, July 1997. 1302 [12] F. Yergeau. UTF-8, a transformation format of ISO 10646. RFC 1303 2279, January 1998. 1305 Authors' Addresses 1307 Questions about this memo can be directed to: 1309 Erik Guttman Charles E. Perkins James Kempf 1310 Sun Microsystems Sun Microsystems Sun Microsystems 1311 Bahnstr. 2 901 San Antonio Rd. 901 San Antonio Rd. 1312 74915 Waibstadt Palo Alto, CA, 94303 Palo Alto, CA, 94303 1313 Germany USA USA 1314 +49 7263 911484 1 650 786 6464 1 650 786 5890 1315 1 650 786 6445 (fax) 1 650 786 6445 (fax) 1316 erik.guttman@sun.com charles.perkins@sun.com james.kempf@sun.com