idnits 2.17.1 draft-gregorio-uritemplate-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 278 has weird spacing: '...1}/here up/...' == Line 279 has weird spacing: '...1}/here up/...' -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (Jul 11, 2011) is 4674 days in the past. Is this intentional? -- 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. 'ASCII' -- Possible downref: Non-RFC (?) normative reference: ref. 'UNIV4' -- Possible downref: Non-RFC (?) normative reference: ref. 'UTR15' -- Possible downref: Non-RFC (?) normative reference: ref. '1' Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Gregorio 3 Internet-Draft Google 4 Intended status: Standards Track R. Fielding, Ed. 5 Expires: January 12, 2012 Adobe 6 M. Hadley 7 Oracle 8 M. Nottingham 9 D. Orchard 10 Jul 11, 2011 12 URI Template 13 draft-gregorio-uritemplate-05 15 Abstract 17 A URI Template is a compact sequence of characters for describing a 18 range of Uniform Resource Identifiers through variable expansion. 19 This specification defines the URI Template syntax and the process 20 for expanding a URI Template into a URI reference, along with 21 guidelines for the use of URI Templates on the Internet. 23 Editorial Note (to be removed by RFC Editor) 25 To provide feedback on this Internet-Draft, join the W3C URI mailing 26 list (http://lists.w3.org/Archives/Public/uri/) [1]. 28 Status of this Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on January 12, 2012. 45 Copyright Notice 47 Copyright (c) 2011 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 This document may contain material from IETF Documents or IETF 61 Contributions published or made publicly available before November 62 10, 2008. The person(s) controlling the copyright in some of this 63 material may not have granted the IETF Trust the right to allow 64 modifications of such material outside the IETF Standards Process. 65 Without obtaining an adequate license from the person(s) controlling 66 the copyright in such materials, this document may not be modified 67 outside the IETF Standards Process, and derivative works of it may 68 not be created outside the IETF Standards Process, except to format 69 it for publication as an RFC or to translate it into languages other 70 than English. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 75 1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 76 1.2. Levels and Expression Types . . . . . . . . . . . . . . . 6 77 1.3. Design Considerations . . . . . . . . . . . . . . . . . . 10 78 1.4. Limitations . . . . . . . . . . . . . . . . . . . . . . . 11 79 1.5. Notational Conventions . . . . . . . . . . . . . . . . . . 11 80 1.6. Character Encoding and Unicode Normalization . . . . . . . 12 81 2. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 82 2.1. Literals . . . . . . . . . . . . . . . . . . . . . . . . . 14 83 2.2. Expressions . . . . . . . . . . . . . . . . . . . . . . . 14 84 2.3. Variables . . . . . . . . . . . . . . . . . . . . . . . . 15 85 2.4. Value Modifiers . . . . . . . . . . . . . . . . . . . . . 16 86 2.4.1. Prefix Values . . . . . . . . . . . . . . . . . . . . 16 87 2.4.2. Component Values . . . . . . . . . . . . . . . . . . . 17 88 2.5. Value Defaults . . . . . . . . . . . . . . . . . . . . . . 17 89 3. Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . 19 90 3.1. Literal Expansion . . . . . . . . . . . . . . . . . . . . 19 91 3.2. Expression Expansion . . . . . . . . . . . . . . . . . . . 20 92 3.2.1. Undefined Variable Expansion . . . . . . . . . . . . . 20 93 3.2.2. Simple String Expansion: {var} . . . . . . . . . . . . 20 94 3.2.3. Reserved expansion: {+var} . . . . . . . . . . . . . . 21 95 3.2.4. Label expansion with dot-prefix: {.var} . . . . . . . 22 96 3.2.5. Path segment expansion: {/var} . . . . . . . . . . . . 23 97 3.2.6. Path-style parameter expansion: {;var} . . . . . . . . 25 98 3.2.7. Form-style query expansion: {?var} . . . . . . . . . . 25 99 4. Security Considerations . . . . . . . . . . . . . . . . . . . 25 100 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 101 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25 102 7. Normative References . . . . . . . . . . . . . . . . . . . . . 25 103 Appendix A. Example URI Template Parser . . . . . . . . . . . . . 26 104 Appendix B. Revision History (to be removed by RFC Editor) . . . 27 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 27 107 1. Introduction 109 1.1. Overview 111 A Uniform Resource Identifier (URI) [RFC3986] is often used to 112 identify a specific resource within a common space of similar 113 resources. For example, personal web spaces are often delegated 114 using a common pattern, such as 116 http://example.com/~fred/ 117 http://example.com/~mark/ 119 or a set of dictionary entries might be grouped in a hierarchy by the 120 first letter of the term, as in 122 http://example.com/dictionary/c/cat 123 http://example.com/dictionary/d/dog 125 or a service interface might be invoked with various user input in a 126 common pattern, as in 128 http://example.com/search?q=cat&lang=en 129 http://example.com/search?q=dog&lang=fr 131 URI Templates provide a mechanism for abstracting a space of resource 132 identifiers such that the variable parts can be easily identified and 133 described. URI templates can have many uses, including discovery of 134 available services, configuring resource mappings, defining computed 135 links, specifying interfaces, and other forms of programmatic 136 interaction with resources. For example, the above resources could 137 be described by the following URI templates: 139 http://example.com/~{username}/ 140 http://example.com/dictionary/{term:1}/{term} 141 http://example.com/search{?q,lang} 143 We define the following terms: 144 o expression - The text between '{' and '}', including the enclosing 145 braces, as defined in Section 2. 146 o expansion - The string result obtained from a template expression 147 after processing it according to its expression type, list of 148 variable names, and value modifiers, as defined in Section 3. 149 o template processor - A program or library that, given a URI 150 Template and a set of variables with values, transforms the 151 template string into a URI-reference by parsing the template for 152 expressions and substituting each one with its corresponding 153 expansion. 155 A URI Template provides both a structural description of a URI space 156 and, when variable values are provided, a simple instruction on how 157 to construct a URI corresponding to those values. A URI Template is 158 transformed into a URI-reference by replacing each delimited 159 expression with its value as defined by the expression type and the 160 values of variables named within the expression. The expression 161 types range from simple string expansion to multiple key=value lists. 162 The expansions are based on the URI generic syntax, allowing an 163 implementation to process any URI Template without knowing the 164 scheme-specific requirements of every possible resulting URI. 166 For example, the following URI Template includes a form-style 167 parameter expression, as indicated by the "?" operator appearing 168 before the variable names. 170 http://www.example.com/foo{?query,number} 172 Each template expression describes, in a machine-readable manner, how 173 a URI is to be constructed. In this example, the expansion process 174 for templates beginning with the question-mark ("?") operator follows 175 the same pattern as form-style interfaces on the World Wide Web. 177 http://www.example.com/foo{?query,number} 178 \_____________/ 179 | 180 | 181 For each defined variable in [ 'query', 'number' ], 182 substitute "?" if it is the first substitution or "&" 183 thereafter, followed by the variable name, '=', and the 184 variable's value. 186 If the variables have the values 188 query := "mycelium" 189 number := 100 191 then the expansion of the above URI Template is 193 http://www.example.com/foo?query=mycelium&number=100 195 Alternatively, if 'query' is undefined, then the expansion would be 197 http://www.example.com/foo?number=100 199 or if both variables are undefined, then it would be 201 http://www.example.com/foo 203 A URI Template may be provided in absolute form, as in the examples 204 above, or in relative form. A template MUST be expanded before the 205 resulting reference can be resolved from relative to absolute form. 207 Although the URI syntax is used for the result, the template string 208 is allowed to contain the broader set of characters that can be found 209 in IRI references [RFC3987]. A URI Template is therefore also an IRI 210 template, and the result of template processing can be rendered as an 211 IRI by transforming each of the pct-encoded sequences to their 212 corresponding Unicode character if that character is not in the 213 reserved set. 215 1.2. Levels and Expression Types 217 URI Templates are similar to a macro language with a fixed set of 218 macro definitions: the expression type determines the expansion 219 process. The default expression type is simple string expansion, 220 wherein a single named variable is replaced by its value as a string 221 after UTF-8 encoding the characters and then pct-encoding any octets 222 that are not in the unreserved set. 224 Since most template processors implemented prior to this 225 specification have only implemented the default expression type, we 226 refer to these as Level 1 templates. 228 .-----------------------------------------------------------------. 229 | Level 1 examples, with variables having values of | 230 | | 231 | var := "value" | 232 | hello := "Hello World!" | 233 | empty := "" | 234 | undef := null | 235 | | 236 |-----------------------------------------------------------------| 237 | Op Expression Expansion | 238 |-----------------------------------------------------------------| 239 | | Simple string expansion (Sec 3.2.2) | 240 | | | 241 | | {var} value | 242 | | {hello} Hello%20World%21 | 243 | | O{empty}X OX | 244 | | O{undef}X OX | 245 `-----------------------------------------------------------------' 247 Level 2 templates add the ability to define a default string, which 248 is substituted if the variable is undefined, and the plus ("+") 249 operator for expansion values that are allowed to include reserved 250 characters. 252 .-----------------------------------------------------------------. 253 | Level 2 examples, with variables having values of | 254 | | 255 | var := "value" | 256 | hello := "Hello World!" | 257 | empty := "" | 258 | undef := null | 259 | path := "/foo/bar" | 260 | | 261 |-----------------------------------------------------------------| 262 | Op Expression Expansion | 263 |-----------------------------------------------------------------| 264 | | String expansion with defaults (Sec 3.2.2) | 265 | | | 266 | | {var|default} value | 267 | | O{empty|default}X OX | 268 | | O{undef|default}X OdefaultX | 269 | | | 270 |-----+-----------------------------------------------------------| 271 | + | Reserved expansion with defaults (Sec 3.2.3) | 272 | | | 273 | | {+var} value | 274 | | {+hello} Hello%20World! | 275 | | {+path}/here /foo/bar/here | 276 | | here?ref={+path} here?ref=/foo/bar | 277 | | up{+path}{x}/here up/foo/bar1024/here | 278 | | up{+empty|/1}/here up/here | 279 | | up{+undef|/1}/here up/1/here | 280 | | | 281 `-----------------------------------------------------------------' 283 Level 3 templates add more complex operators for lists of comma- 284 separated values, dot-prefixed labels, slash-prefixed path segments, 285 semicolon-prefixed path parameters, and the forms-style construction 286 of a query syntax consisting of key=value pairs that are separated by 287 an ampersand character. 289 .-----------------------------------------------------------------. 290 | Level 3 examples, with variables having values of | 291 | | 292 | var := "value" | 293 | hello := "Hello World!" | 294 | empty := "" | 295 | undef := null | 296 | path := "/foo/bar" | 297 | x := "1024" | 298 | y := "768" | 299 | | 300 |-----------------------------------------------------------------| 301 | Op Expression Expansion | 302 |-----------------------------------------------------------------| 303 | | String expansion with multiple variables (Sec 3.2.2) | 304 | | | 305 | | {x,y} 1024,768 | 306 | | {x,hello,y} 1024,Hello%20World%21,768 | 307 | | ?{x,empty} ?1024, | 308 | | ?{x,undef} ?1024 | 309 | | ?{undef,y} ?768 | 310 | | ?{x,undef|0} ?1024,0 | 311 | | | 312 |-----+-----------------------------------------------------------| 313 | + | Reserved expansion with multiple variables (Sec 3.2.3) | 314 | | | 315 | | {+x,hello,y} 1024,Hello%20World!,768 | 316 | | {+path,x}/here /foo/bar/1024/here | 317 | | | 318 |-----+-----------------------------------------------------------| 319 | . | Label expansion, dot-prefixed (Sec 3.2.4) | 320 | | | 321 | | X{.var} X.value | 322 | | X{.empty} X. | 323 | | X{.undef} X | 324 | | | 325 |-----+-----------------------------------------------------------| 326 | / | Path segments, slash-prefixed (Sec 3.2.5) | 327 | | | 328 | | {/var} /value | 329 | | {/var,empty} /value/ | 330 | | {/var,undef} /value | 331 | | | 332 |-----+-----------------------------------------------------------| 333 | ; | Path-style parameters, semicolon-prefixed (Sec 3.2.6) | 334 | | | 335 | | {;x,y} ;x=1024;y=768 | 336 | | {;x,y,empty} ;x=1024;y=768;empty | 337 | | {;x,y,undef} ;x=1024;y=768 | 338 | | | 339 |-----+-----------------------------------------------------------| 340 | ? | Form-style query, ampersand-separated (Sec 3.2.7) | 341 | | | 342 | | {?x,y} ?x=1024&y=768 | 343 | | {?x,y,empty} ?x=1024&y=768&empty= | 344 | | {?x,y,undef} ?x=1024&y=768 | 345 | | | 346 `-----------------------------------------------------------------' 347 Finally, Level 4 templates add the ability to specify value modifiers 348 as a suffix to the variable name. The prefix modifier (":") 349 indicates that only a limited number of characters from the beginning 350 of the value are used by the expansion. The explode ("*") modifier 351 tells the expansion process to treat the value as a multivalued 352 structure --- a list of values or key=value pairs -- rather than as a 353 single string. 355 .-----------------------------------------------------------------. 356 | Level 4 examples, with variables having values of | 357 | | 358 | var := "value" | 359 | hello := "Hello World!" | 360 | path := "/foo/bar" | 361 | list := [ "red", "green", "blue" ] | 362 | keys := [("semi", ";"), ("dot", ".")] | 363 | | 364 | Op Expression Expansion | 365 |-----------------------------------------------------------------| 366 | | String expansion with value modifiers (Sec 3.2.2) | 367 | | | 368 | | {var:3} val | 369 | | {var:30} value | 370 | | {list} red,green,blue | 371 | | {list*} red,green,blue | 372 | | {keys} semi,%3B,dot,.,comma,%2C | 373 | | {keys*} semi=%3B,dot=.,comma=%2C | 374 | | | 375 |-----+-----------------------------------------------------------| 376 | + | Reserved expansion with value modifiers (Sec 3.2.3) | 377 | | | 378 | | {+path:6}/here /foo/b/here | 379 | | {+list} red,green,blue | 380 | | {+list*} red,green,blue | 381 | | {+keys} semi,;,dot,.,comma,, | 382 | | {+keys*} semi=;,dot=.,comma=, | 383 | | | 384 |-----+-----------------------------------------------------------| 385 | . | Label expansion, dot-prefixed (Sec 3.2.4) | 386 | | | 387 | | X{.var:3} X.val | 388 | | X{.list} X.red,green,blue | 389 | | X{.list*} X.red.green.blue | 390 | | X{.keys} X.semi,%3B,dot,.,comma,%2C | 391 | | X{.keys*} X.semi=%3B.dot=..comma=%2C | 392 | | | 393 |-----+-----------------------------------------------------------| 394 | / | Path segments, slash-prefixed (Sec 3.2.5) | 395 | | | 396 | | {/var:1,var} /v/value | 397 | | {/list} /red,green,blue | 398 | | {/list*} /red/green/blue | 399 | | {/list*,path:4} /red/green/blue/%2Ffoo | 400 | | {/keys} /semi,%3B,dot,.,comma,%2C | 401 | | {/keys*} /semi=%3B/dot=./comma=%2C | 402 | | | 403 |-----+-----------------------------------------------------------| 404 | ; | Path-style parameters, semicolon-prefixed (Sec 3.2.6) | 405 | | | 406 | | {;hello:5} ;hello=Hello | 407 | | {;list} ;red,green,blue | 408 | | {;list*} ;red;green;blue | 409 | | {;keys} ;semi,%3B,dot,.,comma,%2C | 410 | | {;keys*} ;semi=%3B;dot=.;comma=%2C | 411 | | | 412 |-----+-----------------------------------------------------------| 413 | ? | Form-style query, ampersand-separated (Sec 3.2.7) | 414 | | | 415 | | {?var:3} ?var=val | 416 | | {?list} ?list=red,green,blue | 417 | | {?list*} ?list=red&list=green&list=blue | 418 | | {?keys} ?keys=semi,%3B,dot,.,comma,%2C | 419 | | {?keys*} ?semi=%3B&dot=.&comma=%2C | 420 | | | 421 `-----------------------------------------------------------------' 423 1.3. Design Considerations 425 Mechanisms similar to URI Templates have been defined within several 426 specifications, including WSDL, WADL and OpenSearch. This 427 specification extends and formally defines the syntax so that URI 428 Templates can be used consistently across multiple Internet 429 applications and within Internet message fields, while at the same 430 time retaining compatibility with those earlier definitions. 432 The URI Template syntax has been designed to carefully balance the 433 need for a powerful expansion mechanism with the need for ease of 434 implementation. The syntax is designed to be trivial to parse while 435 at the same time providing enough flexibility to express many common 436 template scenarios. Implementations are able to parse the template 437 and perform the expansions in a single pass. 439 Templates are simple and readable when used with common examples 440 because the single-character operators match the URI generic syntax 441 delimiters. The operator's associated delimiter (";", "?", "/", and 442 ".") is omitted when none of the listed variables are defined. 444 Likewise, the expansion process for ";" (path-style parameters) will 445 omit the "=" when the variable value is empty, whereas the process 446 for "?" (form-style parameters) will not omit the "=" when the value 447 is empty. Multiple variables and list values have their values 448 joined with "," if there is no predefined joining mechanism for the 449 operator. Only one operator, plus ("+"), will substitute unencoded 450 reserved characters found inside the variable values; the other 451 operators will pct-encode reserved characters found in the variable 452 values prior to expansion. 454 The most common cases for URI spaces can be described with Level 1 455 template expressions. If we were only concerned with URI generation, 456 then the template syntax could be limited to just simple variable 457 expansion, since more complex forms could be generated by changing 458 the variable values. However, URI Templates have the additional goal 459 of describing the layout of identifiers in terms of preexisting data 460 values. The template syntax therefore includes operators that 461 reflect how resource identifiers are commonly allocated. Likewise, 462 since prefix substrings are often used to partition large spaces of 463 resources, modifiers on variable values provide a way to specify both 464 the substring and the full value string with a single variable name. 466 1.4. Limitations 468 Since a URI Template describes a superset of the identifiers, there 469 is no implication that every possible expansion for each delimited 470 variable expression corresponds to a URI of an existing resource. 471 Our expectation is that an application constructing URIs according to 472 the template will be provided with an appropriate set of values for 473 the variables being substituted and will be able to cope with any 474 errors that might occur when the resulting URI is used for name 475 resolution or access. 477 URI Templates are not URIs: they do not identify an abstract or 478 physical resource, they are not parsed as URIs, and should not be 479 used in places where a URI would be expected unless the template 480 expressions will be expanded by a template processor prior to use. 481 Distinct field, element, or attribute names should be used to 482 differentiate protocol elements that carry a URI Template from those 483 that expect a URI reference. 485 1.5. Notational Conventions 487 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 488 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 489 document are to be interpreted as described in [RFC2119]. 491 This specification uses the Augmented Backus-Naur Form (ABNF) 492 notation of [RFC5234]. The following ABNF rules are imported from 493 the normative references [RFC5234], [RFC3986], and [RFC3987]. 495 ALPHA = %x41-5A / %x61-7A ; A-Z / a-z 496 DIGIT = %x30-39 ; 0-9 497 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" 499 pct-encoded = "%" HEXDIG HEXDIG 500 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 501 reserved = gen-delims / sub-delims 502 gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" 503 sub-delims = "!" / "$" / "&" / "'" / "(" / ")" 504 / "*" / "+" / "," / ";" / "=" 506 ucschar = %xA0-D7FF / %xF900-FDCF / %xFDF0-FFEF 507 / %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD 508 / %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD 509 / %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD 510 / %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD 511 / %xD0000-DFFFD / %xE1000-EFFFD 513 iprivate = %xE000-F8FF / %xF0000-FFFFD / %x100000-10FFFD 515 1.6. Character Encoding and Unicode Normalization 517 This specification uses the terms "character" and "coded character 518 set" in accordance with the definitions provided in [RFC2978], and 519 "character encoding" in place of what [RFC2978] refers to as a 520 "charset". 522 The ABNF notation defines its terminal values to be non-negative 523 integers (codepoints) that are a superset of the US-ASCII coded 524 character set [ASCII]. This specification defines terminal values as 525 codepoints within the Unicode coded character set [UNIV4]. 527 In spite of the syntax and template expansion process being defined 528 in terms of Unicode codepoints, it should be understood that 529 templates occur in practice as a sequence of characters in whatever 530 form or encoding is suitable for the context in which they occur, 531 whether that be octets embedded in a network protocol element or 532 paint applied to the side of a bus. This specification does not 533 mandate any particular character encoding for mapping between URI 534 Template characters and the octets used to store or transmit those 535 characters. When a URI Template appears in a protocol element, the 536 character encoding is defined by that protocol; without such a 537 definition, a URI Template is assumed to be in the same character 538 encoding as the surrounding text. It is only during the process of 539 template expansion that a string of characters in a URI Template MUST 540 be transformed into its corresponding sequence of normalized Unicode 541 codepoints. 543 The Unicode Standard [UNIV4] defines various equivalences between 544 sequences of characters for various purposes. Unicode Standard Annex 545 #15 [UTR15] defines various Normalization Forms for these 546 equivalences, in particular Normalization Form KC (NFKC: 547 Compatibility Decomposition followed by Canonical Composition). The 548 normalization form determines how to consistently encode the 549 equivalent strings. 551 In theory, all URI processing implementations, including template 552 processors, should use the same normalization form for generating or 553 handling a URI reference. In practice, they do not. However, 554 template processors transform the template literals and variable 555 values from characters to codepoints, expand the expressions, and 556 then transform the resulting codepoints back to characters again. In 557 order to promote consistent generation of URI references from 558 templates, template processors MUST ensure that the template and each 559 variable value is in NFKC when they are transformed to a sequence of 560 Unicode codepoints. The final step of template processing will 561 encode the expanded sequence of Unicode codepoints, which should 562 still be in NFKC, as UTF-8 [RFC3629] and then further pct-encode any 563 octets within the UTF-8 string that are not allowed in a URI. 565 2. Syntax 567 A URI Template is a string of printable Unicode characters that 568 contains zero or more embedded variable expressions, each expression 569 being delimited by a matching pair of braces ('{', '}'). 571 URI-Template = *( literals / expression ) 573 Although templates (and template processor implementations) are 574 described above in terms of four gradual levels, we define the URI- 575 Template syntax in terms of the ABNF for Level 4. A template 576 processor limited to lower level templates MAY exclude the ABNF rules 577 applicable only to higher levels. However, it is RECOMMENDED that 578 all parsers implement the full syntax such that unsupported levels 579 can be properly identified as such to the end user. 581 Each character in a URI Template MUST be transcoded to an NFKC 582 Unicode codepoint prior to evaluation. If a character sequence in 583 the template consists of pct-encoded triplets corresponding to a 584 valid sequence of octets in UTF-8 that represent a character not in 585 the reserved set, then the triplets MUST be replaced with their 586 corresponding Unicode codepoint. In other words, pct-encoded UTF-8 587 found within the template is decoded prior to further processing 588 unless the corresponding character is in the reserved set. 590 2.1. Literals 592 The characters outside of expressions in a URI Template string are 593 intended to be translated literally to the URI-reference. 595 literals = %x21 / %x23-24 / %x26 / %x28-3B / %x3D / %x3F-5B 596 / %x5D-5F / %x61-7A / %x7E / ucschar / iprivate 597 / pct-encoded 598 ; any Unicode character except: CTL, SP, 599 ; DQUOTE, "'", "%" (aside from pct-encoded), 600 ; "<", ">", "\", "^", "`", "{", "|", "}" 602 A sequence of pct-encoded literals that corresponds to a UTF-8 603 encoded character that is not within the reserved set will be 604 transcoded during template processing, as describe above. If such a 605 character is not in the unreserved set, it will be re-pct-encoded 606 during the final step of template processing. Unreserved characters 607 will therefore be normalized to their unencoded form as a side-effect 608 of template processing. 610 2.2. Expressions 612 Template expressions are the parameterized parts of a URI Template. 613 Each expression contains an optional operator, which defines the 614 expression type and its corresponding expansion process, followed by 615 a comma-separated list of variable specifiers (variable names and 616 optional value modifiers). If no operator is provided, the 617 expression defaults to simple variable expansion of unreserved 618 values. 620 expression = "{" [ operator ] variable-list "}" 621 operator = "+" / "." / "/" / ";" / "?" / op-reserve 622 op-reserve = "," / "!" / "@" 623 ; reserved for local use: "$" / "(" / ")" 625 The operator characters have been chosen to reflect each of their 626 roles as reserved characters in the URI generic syntax. The 627 operators defined by this specification include: plus ("+") for 628 substituting values that may contain reserved characters; dot (".") 629 for substituting values as a sequence of name labels prefixed by "."; 630 slash ("/") for substituting values as a sequence of path segments 631 separated by "/"; semicolon (";") for substituting key=value pairs as 632 path parameters prefixed by ";"; and, question-mark ("?") for 633 substituting a query component beginning with "?" and consisting of 634 key=value pairs separated by "&". These operators will be described 635 in detail in Section 3. 637 The operator characters comma (","), exclamation ("!"), and at-sign 638 ("@") are reserved for future extensions. A processor that 639 unexpectedly encounters such an extension operator SHOULD pass the 640 expression through unexpanded and MAY also indicate a warning to the 641 invoking application. 643 The expression syntax specifically excludes use of the dollar ("$") 644 and parentheses ["(" and ")"] characters so that they remain 645 available for local language extensions outside the scope of this 646 specification. 648 2.3. Variables 650 After the operator (if any), each expression contains a list of one 651 or more comma-separated variable specifiers (varspec). The variable 652 names serve multiple purposes: documentation for what kinds of values 653 are expected, identifiers for associating values within a template 654 processor, and the string to use for each key on key=value 655 expansions. 657 variable-list = varspec *( "," varspec ) 658 varspec = varname [ modifier ] [ "|" default ] 659 varname = varchar *( varchar / "." ) 660 varchar = ALPHA / DIGIT / "_" / ucschar / iprivate 661 / pct-encoded 663 An expression MAY reference variables that are unknown to the 664 template processor or whose value is set to a special "undefined" 665 value, such as undef or null. Such undefined variables are given 666 special treatment by the expansion process. 668 A variable value that is a string of length zero is not considered 669 undefined; it has the defined value of an empty string. 671 A variable may have a composite or structured value, such as a list 672 of values, an associative array of (key, value) pairs, or a structure 673 of components defined by some separate schema. Such value types are 674 not directly indicated by the template syntax, but do have an impact 675 on the expansion process. A composite or structured value with zero 676 member values is considered undefined. 678 If a variable appears more than once in an expression or within 679 multiple expressions of a URI Template, the value of that variable 680 MUST remain static throughout the expansion process (i.e., the 681 variable must have the same value for the purpose of calculating each 682 expansion). 684 2.4. Value Modifiers 686 Each of the variables in a Level 4 template expression can have a 687 modifier indicating either that its expansion is limited to a prefix 688 of the variable's value string or that its expansion is exploded into 689 components based on an external type or schema associated with that 690 variable. 692 modifier = prefix / explode 694 2.4.1. Prefix Values 696 A prefix modifier indicates that the variable expansion is limited to 697 a prefix of the variable's value string. Prefix modifiers are often 698 used to partition an identifier space hierarchically, as is common in 699 reference indices and hash-based storage. It also serves to limit 700 the expanded value to a maximum number of characters. 702 prefix = ":" offset 703 max-length = %x31-39 *DIGIT ; positive integer 705 The max-length is a positive integer that refers to a maximum number 706 of characters from the beginning of the variable's value as a Unicode 707 string. Note that this numbering is in characters, not octets, in 708 order to avoid splitting between the octets of a multi-octet UTF-8 709 encoded character or within a pct-encoded triplet. If the max-length 710 is greater than the length of the variable's value, then the entire 711 value string is used. 713 For example, 715 Given the variable assignments 717 var := "value" 718 semi := ";" 720 Example Template Expansion 722 {var} value 723 {var:20} value 724 {var:3} val 725 {semi} %3B 726 {semi:2} %3B 728 2.4.2. Component Values 730 An explode modifier ("*") indicates that the variable represents a 731 composite value that may be substituted in full or partial forms, 732 depending on the variable's type or schema. Since URI Templates do 733 not contain an indication of type or schema, this is assumed to be 734 determined by context. An example context is a mark-up element or 735 header field that contains one attribute that is a template and one 736 or more other attributes that define the schema applicable to 737 variables found in the template. Likewise, a typed programming 738 language might differentiate variables as strings, lists, associative 739 arrays, or structures. 741 explode = "*" 743 Explode modifiers improve brevity in the URI Template syntax. For 744 example, a resource that provides a geographic map for a given street 745 address might accept a hundred permutations on fields for address 746 input, including partial addresses (e.g., just the city or postal 747 code). Such a resource could be described as a template with each 748 and every address component listed in order, or with a far more 749 simple template that makes use of an explode modifier, as in 751 /mapper{?address*} 753 along with some context that defines what the variable named 754 "address" can include, such as by reference to some other standard 755 for addressing (e.g., UPU S42 or AS/NZS 4819:2003). A recipient 756 aware of the schema can then provide appropriate expansions, such as: 758 /mapper?city=Newport%20Beach&state=CA 760 If an explode modifier is present, the expansion process for that 761 variable, as defined in Section 3, is dependent on both the operator 762 being used and the type or schema of the value being substituted. 764 2.5. Value Defaults 766 Each of the variables in Level 2 (and above) templates may also be 767 supplied with a default value to be used when a template processor 768 determines that variable to be undefined. The default value is 769 limited to unreserved characters, the equal sign ("="), and pct- 770 encoded triplets, since the default is provided in the exact form 771 that it would appear in the expanded URI reference. The default is 772 not affected by any variable modifiers, since we assume that the 773 default string provided in the expression already reflects the 774 desired value. 776 default = *( unreserved / "=" / pct-encoded ) 778 The following examples illustrate how default values work with 779 different variable types. 781 Given the variable assignments: 783 var := "value" 784 name := [ "Fred", "Wilma", "Pebbles" ] 785 favs := [("color","red"), ("volume","high")] 786 empty_keys := [] 787 empty := "" 788 undef := null 790 Example Template Expansion 792 {var|default} value 793 {undef|default} default 794 {undef:3|default} default 796 x{empty}y xy 797 x{empty|_}y xy 798 x{undef}y xy 799 x{undef|_}y x_y 801 x{.name|none} x.Fred,Wilma,Pebbles 802 x{.name*|none} x.Fred.Wilma.Pebbles 803 x{.empty} x. 804 x{.empty|none} x. 805 x{.undef} x 806 x{.undef|none} x.none 808 x{/name|none} x/Fred,Wilma,Pebbles 809 x{/name*|none} x/Fred/Wilma/Pebbles 810 x{/undef} x 811 x{/undef|none} x/none 812 x{/empty} x/ 813 x{/empty|none} x/ 814 x{/empty_keys} x 815 x{/empty_keys|none} x/none 816 x{/empty_keys*} x 817 x{/empty_keys*|none} x/none 819 x{;name|none} x;name=Fred,Wilma,Pebbles 820 x{;favs|none} x;favs=color,red,volume,high 821 x{;favs*|none} x;color=red;volume=high 822 x{;empty} x;empty 823 x{;empty|none} x;empty 824 x{;undef} x 825 x{;undef|none} x;none 826 x{;undef|foo=y} x;foo=y 828 x{?var|none} x?var=value 829 x{?favs|none} x?favs=color,red,volume,high 830 x{?favs*|none} x?color=red&volume=high 831 x{?empty} x?empty= 832 x{?empty|foo=none} x?empty= 833 x{?undef} x 834 x{?undef|foo=none} x?foo=none 835 x{?empty_keys} x 836 x{?empty_keys|none} x?none 837 x{?empty_keys|y=z} x?y=z 838 x{?empty_keys*|y=z} x?y=z 840 3. Expansion 842 The process of URI Template expansion is to scan the template string 843 from beginning to end, copying literal characters as-is and replacing 844 each expression with the result of applying the expression's operator 845 to the value of each variable named in the expression. 847 Each variable value MUST be formed as a sequence of NFKC Unicode 848 codepoints prior to template expansion. A value is assumed to be raw 849 data that might need to be encoded by the template processor during 850 expansion, depending on the expression type. 852 If a template processor encounters an error outside of an expression, 853 such as a character sequence that does not match the 854 grammar, then processing of the template SHOULD cease, the URI- 855 reference result SHOULD be undefined, and the location and type of 856 error SHOULD be indicated to the invoking application. If an error 857 is encountered inside an expression, such as an operator or value 858 modifier that it does not recognize or cannot support, then the 859 expression SHOULD be copied to the result unexpanded, processing of 860 the remainder of the template SHOULD continue, and the location and 861 type of error SHOULD be indicated to the invoking application. 863 3.1. Literal Expansion 865 If the literal character is allowed anywhere in the URI syntax 866 (unreserved / reserved), then it is copied directly to the result 867 string. Otherwise, the pct-encoded equivalent of the literal 868 character is copied to the result string by encoding the character in 869 UTF-8 (a sequence of octets) and then encoding each octet as a pct- 870 encoded triplet. 872 3.2. Expression Expansion 874 Each expression is indicated by an opening brace ("{") character and 875 continues until the next closing brace ("}"). The expression is 876 expanded by determining the expression type and then following that 877 type's expansion process for each comma-separated varspec in the 878 expression. Level 1 templates are limited to the default operator 879 (simple string value expansion) and a single variable per expression. 880 Level 2 templates are limited to a single varspec per expression. 882 The expression type is determined by looking at the first character 883 after the opening brace. If the character is an operator, then 884 remember the expression type associated with that operator for later 885 expansion decisions and skip to the next character for the varspec 886 list. If the first character is not an operator, then the expression 887 type is simple expansion and the first character is the beginning of 888 the varspec list. 890 3.2.1. Undefined Variable Expansion 892 Regardless of the expression type, a variable that is undefined has 893 no value. A variable defined as a list or structure of component 894 values is considered undefined if the list contains zero members or 895 all of the structure's components are undefined. 897 If a default value is provided for an undefined variable, as 898 described for Level 2 (and above) templates in Section 2.5, then the 899 default string is substituted in its place as the entire expansion 900 for that varspec. If all of the variables in an expression are 901 undefined and no defaults are given, then the expression's expansion 902 is the empty string. 904 3.2.2. Simple String Expansion: {var} 906 The default expression type when no operator is given is simple 907 string expansion. For each defined variable in the variable-list, 908 modify its value as indicated by the optional modifiers (if any), 909 encode the value as UTF-8, pct-encode any octets that are not in the 910 unreserved set, and then append the encoded value to the result 911 string. If more than one value is appended, separate each value with 912 a comma (","). 914 For example, 916 foo := "fred" 918 "{foo}" -> "fred" 919 "{foo,foo}" -> "fred,fred" 920 "{bar,foo}" -> "fred" 921 "{bar|wilma}" -> "wilma" 923 Level 1 templates are limited to single variable expressions with no 924 modifiers, defaults, or value structures. Simple string expansion in 925 Level 2 templates adds variable defaulting, as defined in 926 Section 2.5. Level 3 templates allow a list of variables. Level 4 927 templates add compound variable types and value modifiers, as 928 follows: 930 For a variable defined as a single value string, the explode modifier 931 has no effect. The prefix modifier limits the expansion to the first 932 max-length characters of that single value. If the value contains 933 pct-encoded triplets, multibyte UTF-8, or both, care must be taken to 934 avoid splitting the value in mid-character: count each Unicode 935 codepoint as one character. 937 For a variable defined as a list of values, when no value modifier is 938 present or the explode modifier is given, the variable's string 939 expansion consists of a concatenation of the individual values with 940 each value separated by a comma (","). A prefix modifier has no 941 effect. 943 A variable defined as an associative array is expanded as a list of 944 alternating key and value pairs, excluding any keys for which the 945 corresponding value is undefined, when no value modifier is present. 946 If the explode modifier is given, then the keys with defined values 947 are expanded as "key=value" pairs instead of "key,value". A prefix 948 modifier has no effect. 950 3.2.3. Reserved expansion: {+var} 952 Reserved expansion is identical to simple expansion except that the 953 substituted values may contain characters in the reserved set. The 954 reserved expansion operator "+" is defined for Level 2 templates (and 955 above). 957 For example, 959 foo := "That's right!" 961 "{foo}" -> "That%27s%20right%21" 962 "{+foo}" -> "That%27s%20right!" 964 base := "http://example.com/home/" 966 "{base}index" -> "http%3A%2F%2Fexample.com%2Fhome%2Findex" 967 "{+base}index" -> "http://example.com/home/index" 969 The same expansion process is followed as in Section 3.2.2 except 970 that, instead of "pct-encode any octets that are not in the 971 unreserved set", we pct-encode any octets that are not in either the 972 reserved or unreserved sets. 974 3.2.4. Label expansion with dot-prefix: {.var} 976 The dot (".") operator indicates that the expression type is label 977 expansion, which can be useful for describing URI spaces with varying 978 domain names or path selectors (e.g., filename extensions). 980 For each variable in the variable-list, do one of 982 a) if the variable has a defined value 984 1) modify its value as indicated by the optional 985 modifiers (if any); 987 2) encode the value as UTF-8; 989 3) pct-encode any octets that are not in the 990 unreserved set; 992 4) append "." to the result string; and, 994 5) append the encoded value to the result string. 996 b) if the variable is undefined and a default is given, 998 1) encode the default string as UTF-8; 1000 2) append "." to the result string; and, 1002 3) append the default to the result string. 1004 c) the variable is undefined and has no default, 1005 so ignore this variable. 1007 Since "." is not in the reserved set, a value that contains a "." has 1008 the effect of adding multiple labels. 1010 For example, 1012 foo := "fred" 1014 "{foo}" -> ".fred" 1015 "{foo,foo}" -> ".fred.fred" 1016 "{bar,foo}" -> ".fred" 1017 "{bar|wilma}" -> ".wilma" 1019 Label expansion only applies to Level 3 and Level 4 templates. Level 1020 4 templates add compound variable types and value modifiers, as 1021 follows: 1023 For a variable defined as a single value string, the explode modifier 1024 has no effect. The prefix modifier limits the expansion to the first 1025 max-length characters of that single value. If the value contains 1026 pct-encoded triplets, multibyte UTF-8, or both, care must be taken to 1027 avoid splitting the value in mid-character: count each Unicode 1028 codepoint as one character. 1030 For a variable defined as a list of values, when no value modifier is 1031 present or the explode modifier is given, the variable's string 1032 expansion consists of a concatenation of the individual defined 1033 values with each value prepended by a dot ("."). A prefix modifier 1034 has no effect. 1036 When no value modifier is present, a variable defined as an 1037 associative array is expanded by appending the (key, value) pairs as 1038 alternating labels (i.e., ".key.value"), but excluding any keys for 1039 which the corresponding value is undefined. If the explode modifier 1040 is given, then the keys with defined values are expanded as 1041 ".key=value" instead of ".key.value". A prefix modifier has no 1042 effect. 1044 3.2.5. Path segment expansion: {/var} 1046 The slash ("/") operator indicates that the expression type is 1047 hierarchical path segment expansion, which can be useful for 1048 describing URI path hierarchies. 1050 For each variable in the variable-list, do one of 1052 a) if the variable has a defined value 1054 1) modify its value as indicated by the optional 1055 modifiers (if any); 1057 2) encode the value as UTF-8; 1059 3) pct-encode any octets that are not in the 1060 unreserved set; 1062 4) append "/" to the result string; and, 1064 5) append the encoded value to the result string. 1066 b) if the variable is undefined and a default is given, 1068 1) encode the default string as UTF-8; 1070 2) append "/" to the result string; and, 1072 3) append the default to the result string. 1074 c) the variable is undefined and has no default, 1075 so ignore this variable. 1077 Note that the expansion process for path segment expansion is 1078 identical to that of label expansion aside from the substitution of 1079 "/" instead of ".". 1081 For example, 1083 foo := "fred" 1085 "{foo}" -> "/fred" 1086 "{foo,foo}" -> "/fred/fred" 1087 "{bar,foo}" -> "/fred" 1088 "{bar|wilma}" -> "/wilma" 1090 Label expansion only applies to Level 3 and Level 4 templates. Level 1091 4 templates add compound variable types and value modifiers, as 1092 follows: 1094 For a variable defined as a single value string, the explode modifier 1095 has no effect. The prefix modifier limits the expansion to the first 1096 max-length characters of that single value. If the value contains 1097 pct-encoded triplets, multibyte UTF-8, or both, care must be taken to 1098 avoid splitting the value in mid-character: count each Unicode 1099 codepoint as one character. 1101 For a variable defined as a list of values, when no value modifier is 1102 present or the explode modifier is given, the variable's string 1103 expansion consists of a concatenation of the individual defined 1104 values with each value prepended by a slash ("/"). A prefix modifier 1105 has no effect. 1107 When no value modifier is present, a variable defined as an 1108 associative array is expanded by appending the (key, value) pairs as 1109 alternating segments (i.e., "/key/value"), but excluding any keys for 1110 which the corresponding value is undefined. If the explode modifier 1111 is given, then the keys with defined values are expanded as 1112 "/key=value" instead of "/key/value". A prefix modifier has no 1113 effect. 1115 3.2.6. Path-style parameter expansion: {;var} 1117 TBD. 1119 3.2.7. Form-style query expansion: {?var} 1121 TBD. 1123 4. Security Considerations 1125 A URI Template does not contain active or executable content. Other 1126 security considerations are the same as those for URIs, as described 1127 in section 7 of [RFC3986]. 1129 5. IANA Considerations 1131 No IANA actions are required by this document. 1133 6. Acknowledgments 1135 The following people made significant contributions to this 1136 specification: Mike Burrows, Michaeljohn Clement, DeWitt Clinton, 1137 John Cowan, James H. Manger, and James Snell. 1139 7. Normative References 1141 [ASCII] American National Standards Institute, "Coded Character 1142 Set - 7-bit American Standard Code for Information 1143 Interchange", ANSI X3.4, 1986. 1145 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1146 Requirement Levels", BCP 14, RFC 2119, March 1997. 1148 [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration 1149 Procedures", BCP 19, RFC 2978, October 2000. 1151 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1152 10646", STD 63, RFC 3629, November 2003. 1154 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1155 Resource Identifier (URI): Generic Syntax", STD 66, 1156 RFC 3986, January 2005. 1158 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1159 Identifiers (IRIs)", RFC 3987, January 2005. 1161 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1162 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1164 [UNIV4] The Unicode Consortium, "The Unicode Standard, Version 1165 4.0.1, defined by: The Unicode Standard, Version 4.0 1166 (Reading, MA, Addison-Wesley, 2003. ISBN 0-321-18578-1), 1167 as amended by Unicode 4.0.1 1168 (http://www.unicode.org/versions/Unicode4.0.1/)", 1169 March 2004. 1171 [UTR15] Davis, M. and M. Duerst, "Unicode Normalization Forms", 1172 Unicode Standard Annex # 15, April 2003. 1174 [1] 1176 Appendix A. Example URI Template Parser 1178 Parsing a valid URI Template expression does not require building a 1179 parser from the given ABNF. Instead, the set of allowed characters 1180 in each part of URI Template expression has been chosen to avoid 1181 complex parsing, and breaking an expression into its component parts 1182 can be achieved by a series of splits of the character string. 1184 Here is example Python code that parses a URI Template expression and 1185 returns the operator, argument, and variables as a tuple. The 1186 variables are returned as a dictionary of variable names mapped to 1187 their default values. If no default is given then the name maps to 1188 None. 1190 TBD. 1192 Appendix B. Revision History (to be removed by RFC Editor) 1194 05 - Introduced levels to differentiate between legacy, partial, and 1195 full implementations of URI Templates. Changed the default indicator 1196 to pipe ("|") to allow the defaults to contain the equals character 1197 and thus remove the need for complex defaulting for the different 1198 variable types. Removed suffix, remainder, and labelled value 1199 expansion because there didn't seem much interest in them. Clarified 1200 that templates and values are processed as sequences of Unicode 1201 codepoints rather than prematurely encoded as UTF-8, since that is 1202 easier to explain and more consistent with common language routines 1203 for processing Unicode strings. 1205 04 - Changed the operator syntax to a single character that is 1206 analogous to its reserved role within the URI generic syntax, 1207 resulting in templates that are far more readable for the common 1208 cases. Added value modifiers for prefix and suffix expansion. Added 1209 explode modifiers to allow expansion of complex variables and lists 1210 according to (external) variable types or schema. Replaced use of 1211 "expansion" with "expression", since expansion is traditionally used 1212 to refer to the result after expanding a macro (not the macro 1213 itself). Made applicable to any hypertext reference string, such 1214 that the process for template expansion also includes transforming 1215 the surrounding string into a proper URI-reference rather than 1216 assuming it is already in absolute URI form. Rewrote the text 1217 accordingly. 1219 03 - Added more examples. Introduced error conditions and defined 1220 their handling. Changed listjoin to list. Changed -append to 1221 -suffix, and allowed -prefix and -suffix to accept list variables. 1222 Clarified the handling of unicode. 1224 02 - Added operators and came up with coherent percent-encoding and 1225 reserved character story. Added large examples section which is 1226 extracted and tested against the implementation. 1228 01 1230 00 - Initial Revision. 1232 Authors' Addresses 1234 Joe Gregorio 1235 Google 1237 Email: joe@bitworking.org 1238 URI: http://bitworking.org/ 1240 Roy T. Fielding (editor) 1241 Adobe Systems Incorporated 1243 Email: fielding@gbiv.com 1244 URI: http://roy.gbiv.com/ 1246 Marc Hadley 1247 Oracle 1249 Email: Marc.Hadley@oracle.com 1250 URI: http://oracle.com/ 1252 Mark Nottingham 1254 Email: mnot@pobox.com 1255 URI: http://mnot.net/ 1257 David Orchard 1259 URI: http://www.pacificspirit.com/