idnits 2.17.1 draft-gregorio-uritemplate-08.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1034 has weird spacing: '...r}/here up/f...' == Line 1381 has weird spacing: '...| false false...' -- 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.) -- The document date (Jan 26, 2012) is 4473 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. 'UNIV6' -- Possible downref: Non-RFC (?) normative reference: ref. 'UTR15' Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 6 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 5 Expires: July 29, 2012 Adobe 6 M. Hadley 7 MITRE 8 M. Nottingham 9 Rackspace 10 D. Orchard 11 Salesforce.com 12 Jan 26, 2012 14 URI Template 15 draft-gregorio-uritemplate-08 17 Abstract 19 A URI Template is a compact sequence of characters for describing a 20 range of Uniform Resource Identifiers through variable expansion. 21 This specification defines the URI Template syntax and the process 22 for expanding a URI Template into a URI reference, along with 23 guidelines for the use of URI Templates on the Internet. 25 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on July 29, 2012. 42 Copyright Notice 44 Copyright (c) 2012 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 1.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.2. Levels and Expression Types . . . . . . . . . . . . . . . 5 62 1.3. Design Considerations . . . . . . . . . . . . . . . . . . 9 63 1.4. Limitations . . . . . . . . . . . . . . . . . . . . . . . 10 64 1.5. Notational Conventions . . . . . . . . . . . . . . . . . . 11 65 1.6. Character Encoding and Unicode Normalization . . . . . . . 12 66 2. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 67 2.1. Literals . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 2.2. Expressions . . . . . . . . . . . . . . . . . . . . . . . 13 69 2.3. Variables . . . . . . . . . . . . . . . . . . . . . . . . 14 70 2.4. Value Modifiers . . . . . . . . . . . . . . . . . . . . . 15 71 2.4.1. Prefix Values . . . . . . . . . . . . . . . . . . . . 15 72 2.4.2. Composite Values . . . . . . . . . . . . . . . . . . . 16 73 3. Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . 17 74 3.1. Literal Expansion . . . . . . . . . . . . . . . . . . . . 18 75 3.2. Expression Expansion . . . . . . . . . . . . . . . . . . . 18 76 3.2.1. Variable Expansion . . . . . . . . . . . . . . . . . . 19 77 3.2.2. Simple String Expansion: {var} . . . . . . . . . . . . 21 78 3.2.3. Reserved expansion: {+var} . . . . . . . . . . . . . . 22 79 3.2.4. Fragment expansion: {#var} . . . . . . . . . . . . . . 23 80 3.2.5. Label expansion with dot-prefix: {.var} . . . . . . . 24 81 3.2.6. Path segment expansion: {/var} . . . . . . . . . . . . 24 82 3.2.7. Path-style parameter expansion: {;var} . . . . . . . . 25 83 3.2.8. Form-style query expansion: {?var} . . . . . . . . . . 26 84 3.2.9. Form-style query continuation: {&var} . . . . . . . . 26 85 4. Security Considerations . . . . . . . . . . . . . . . . . . . 27 86 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 87 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 28 88 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 89 7.1. Normative References . . . . . . . . . . . . . . . . . . . 28 90 7.2. Informative References . . . . . . . . . . . . . . . . . . 29 91 Appendix A. Implementation Hints . . . . . . . . . . . . . . . . 29 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 32 94 1. Introduction 96 1.1. Overview 98 A Uniform Resource Identifier (URI) [RFC3986] is often used to 99 identify a specific resource within a common space of similar 100 resources (informally, a "URI space"). For example, personal web 101 spaces are often delegated using a common pattern, such as 103 http://example.com/~fred/ 104 http://example.com/~mark/ 106 or a set of dictionary entries might be grouped in a hierarchy by the 107 first letter of the term, as in 109 http://example.com/dictionary/c/cat 110 http://example.com/dictionary/d/dog 112 or a service interface might be invoked with various user input in a 113 common pattern, as in 115 http://example.com/search?q=cat&lang=en 116 http://example.com/search?q=chien&lang=fr 118 A URI Template is a compact sequence of characters for describing a 119 range of Uniform Resource Identifiers through variable expansion. 121 URI Templates provide a mechanism for abstracting a space of resource 122 identifiers such that the variable parts can be easily identified and 123 described. URI templates can have many uses, including discovery of 124 available services, configuring resource mappings, defining computed 125 links, specifying interfaces, and other forms of programmatic 126 interaction with resources. For example, the above resources could 127 be described by the following URI templates: 129 http://example.com/~{username}/ 130 http://example.com/dictionary/{term:1}/{term} 131 http://example.com/search{?q,lang} 133 We define the following terms: 134 o expression - The text between '{' and '}', including the enclosing 135 braces, as defined in Section 2. 136 o expansion - The string result obtained from a template expression 137 after processing it according to its expression type, list of 138 variable names, and value modifiers, as defined in Section 3. 139 o template processor - A program or library that, given a URI 140 Template and a set of variables with values, transforms the 141 template string into a URI-reference by parsing the template for 142 expressions and substituting each one with its corresponding 143 expansion. 145 A URI Template provides both a structural description of a URI space 146 and, when variable values are provided, machine-readable instructions 147 on how to construct a URI corresponding to those values. A URI 148 Template is transformed into a URI-reference by replacing each 149 delimited expression with its value as defined by the expression type 150 and the values of variables named within the expression. The 151 expression types range from simple string expansion to multiple 152 name=value lists. The expansions are based on the URI generic 153 syntax, allowing an implementation to process any URI Template 154 without knowing the scheme-specific requirements of every possible 155 resulting URI. 157 For example, the following URI Template includes a form-style 158 parameter expression, as indicated by the "?" operator appearing 159 before the variable names. 161 http://www.example.com/foo{?query,number} 163 The expansion process for expressions beginning with the question- 164 mark ("?") operator follows the same pattern as form-style interfaces 165 on the World Wide Web: 167 http://www.example.com/foo{?query,number} 168 \_____________/ 169 | 170 | 171 For each defined variable in [ 'query', 'number' ], 172 substitute "?" if it is the first substitution or "&" 173 thereafter, followed by the variable name, '=', and the 174 variable's value. 176 If the variables have the values 178 query := "mycelium" 179 number := 100 181 then the expansion of the above URI Template is 183 http://www.example.com/foo?query=mycelium&number=100 185 Alternatively, if 'query' is undefined, then the expansion would be 187 http://www.example.com/foo?number=100 189 or if both variables are undefined, then it would be 190 http://www.example.com/foo 192 A URI Template may be provided in absolute form, as in the examples 193 above, or in relative form. A template is expanded before the 194 resulting reference is resolved from relative to absolute form. 196 Although the URI syntax is used for the result, the template string 197 is allowed to contain the broader set of characters that can be found 198 in IRI references [RFC3987]. A URI Template is therefore also an IRI 199 template, and the result of template processing can be transformed to 200 an IRI by following the process defined in Section 3.2 of [RFC3987]. 202 1.2. Levels and Expression Types 204 URI Templates are similar to a macro language with a fixed set of 205 macro definitions: the expression type determines the expansion 206 process. The default expression type is simple string expansion, 207 wherein a single named variable is replaced by its value as a string 208 after pct-encoding any characters not in the set of unreserved URI 209 characters (Section 1.5). 211 Since most template processors implemented prior to this 212 specification have only implemented the default expression type, we 213 refer to these as Level 1 templates. 215 .-----------------------------------------------------------------. 216 | Level 1 examples, with variables having values of | 217 | | 218 | var := "value" | 219 | hello := "Hello World!" | 220 | | 221 |-----------------------------------------------------------------| 222 | Op Expression Expansion | 223 |-----------------------------------------------------------------| 224 | | Simple string expansion (Sec 3.2.2) | 225 | | | 226 | | {var} value | 227 | | {hello} Hello%20World%21 | 228 `-----------------------------------------------------------------' 230 Level 2 templates add the plus ("+") operator, for expansion of 231 values that are allowed to include reserved URI characters 232 (Section 1.5), and the crosshatch ("#") operator for expansion of 233 fragment identifiers. 235 .-----------------------------------------------------------------. 236 | Level 2 examples, with variables having values of | 237 | | 238 | var := "value" | 239 | hello := "Hello World!" | 240 | path := "/foo/bar" | 241 | | 242 |-----------------------------------------------------------------| 243 | Op Expression Expansion | 244 |-----------------------------------------------------------------| 245 | + | Reserved string expansion (Sec 3.2.3) | 246 | | | 247 | | {+var} value | 248 | | {+hello} Hello%20World! | 249 | | {+path}/here /foo/bar/here | 250 | | here?ref={+path} here?ref=/foo/bar | 251 |-----+-----------------------------------------------------------| 252 | # | Fragment expansion, crosshatch-prefixed (Sec 3.2.4) | 253 | | | 254 | | X{#var} X#value | 255 | | X{#hello} X#Hello%20World! | 256 `-----------------------------------------------------------------' 258 Level 3 templates allow multiple variables per expression, each 259 separated by a comma, and add more complex operators for dot-prefixed 260 labels, slash-prefixed path segments, semicolon-prefixed path 261 parameters, and the forms-style construction of a query syntax 262 consisting of name=value pairs that are separated by an ampersand 263 character. 265 .-----------------------------------------------------------------. 266 | Level 3 examples, with variables having values of | 267 | | 268 | var := "value" | 269 | hello := "Hello World!" | 270 | empty := "" | 271 | path := "/foo/bar" | 272 | x := "1024" | 273 | y := "768" | 274 | | 275 |-----------------------------------------------------------------| 276 | Op Expression Expansion | 277 |-----------------------------------------------------------------| 278 | | String expansion with multiple variables (Sec 3.2.2) | 279 | | | 280 | | map?{x,y} map?1024,768 | 281 | | {x,hello,y} 1024,Hello%20World%21,768 | 282 | | | 283 |-----+-----------------------------------------------------------| 284 | + | Reserved expansion with multiple variables (Sec 3.2.3) | 285 | | | 286 | | {+x,hello,y} 1024,Hello%20World!,768 | 287 | | {+path,x}/here /foo/bar,1024/here | 288 | | | 289 |-----+-----------------------------------------------------------| 290 | # | Fragment expansion with multiple variables (Sec 3.2.4) | 291 | | | 292 | | {#x,hello,y} #1024,Hello%20World!,768 | 293 | | {#path,x}/here #/foo/bar,1024/here | 294 | | | 295 |-----+-----------------------------------------------------------| 296 | . | Label expansion, dot-prefixed (Sec 3.2.5) | 297 | | | 298 | | X{.var} X.value | 299 | | X{.x,y} X.1024.768 | 300 | | | 301 |-----+-----------------------------------------------------------| 302 | / | Path segments, slash-prefixed (Sec 3.2.6) | 303 | | | 304 | | {/var} /value | 305 | | {/var,x}/here /value/1024/here | 306 | | | 307 |-----+-----------------------------------------------------------| 308 | ; | Path-style parameters, semicolon-prefixed (Sec 3.2.7) | 309 | | | 310 | | {;x,y} ;x=1024;y=768 | 311 | | {;x,y,empty} ;x=1024;y=768;empty | 312 | | | 313 |-----+-----------------------------------------------------------| 314 | ? | Form-style query, ampersand-separated (Sec 3.2.8) | 315 | | | 316 | | {?x,y} ?x=1024&y=768 | 317 | | {?x,y,empty} ?x=1024&y=768&empty= | 318 | | | 319 |-----+-----------------------------------------------------------| 320 | & | Form-style query continuation (Sec 3.2.9) | 321 | | | 322 | | ?fixed=yes{&x} ?fixed=yes&x=1024 | 323 | | {&x,y,empty} &x=1024&y=768&empty= | 324 | | | 325 `-----------------------------------------------------------------' 327 Finally, Level 4 templates add value modifiers as an optional suffix 328 to each variable name. A prefix modifier (":") indicates that only a 329 limited number of characters from the beginning of the value are used 330 by the expansion (Section 2.4.1). An explode ("*") modifier 331 indicates that the variable is to be treated as a composite value, 332 consisting of either a list of names or an associative array of 333 (name, value) pairs, that is expanded as if each member were a 334 separate variable (Section 2.4.2). 336 .-----------------------------------------------------------------. 337 | Level 4 examples, with variables having values of | 338 | | 339 | var := "value" | 340 | hello := "Hello World!" | 341 | path := "/foo/bar" | 342 | list := ("red", "green", "blue") | 343 | keys := [("semi",";"),("dot","."),("comma",",")] | 344 | | 345 | Op Expression Expansion | 346 |-----------------------------------------------------------------| 347 | | String expansion with value modifiers (Sec 3.2.2) | 348 | | | 349 | | {var:3} val | 350 | | {var:30} value | 351 | | {list} red,green,blue | 352 | | {list*} red,green,blue | 353 | | {keys} semi,%3B,dot,.,comma,%2C | 354 | | {keys*} semi=%3B,dot=.,comma=%2C | 355 | | | 356 |-----+-----------------------------------------------------------| 357 | + | Reserved expansion with value modifiers (Sec 3.2.3) | 358 | | | 359 | | {+path:6}/here /foo/b/here | 360 | | {+list} red,green,blue | 361 | | {+list*} red,green,blue | 362 | | {+keys} semi,;,dot,.,comma,, | 363 | | {+keys*} semi=;,dot=.,comma=, | 364 | | | 365 |-----+-----------------------------------------------------------| 366 | # | Fragment expansion with value modifiers (Sec 3.2.4) | 367 | | | 368 | | {#path:6}/here #/foo/b/here | 369 | | {#list} #red,green,blue | 370 | | {#list*} #red,green,blue | 371 | | {#keys} #semi,;,dot,.,comma,, | 372 | | {#keys*} #semi=;,dot=.,comma=, | 373 | | | 374 |-----+-----------------------------------------------------------| 375 | . | Label expansion, dot-prefixed (Sec 3.2.5) | 376 | | | 377 | | X{.var:3} X.val | 378 | | X{.list} X.red,green,blue | 379 | | X{.list*} X.red.green.blue | 380 | | X{.keys} X.semi,%3B,dot,.,comma,%2C | 381 | | X{.keys*} X.semi=%3B.dot=..comma=%2C | 382 | | | 383 |-----+-----------------------------------------------------------| 384 | / | Path segments, slash-prefixed (Sec 3.2.6) | 385 | | | 386 | | {/var:1,var} /v/value | 387 | | {/list} /red,green,blue | 388 | | {/list*} /red/green/blue | 389 | | {/list*,path:4} /red/green/blue/%2Ffoo | 390 | | {/keys} /semi,%3B,dot,.,comma,%2C | 391 | | {/keys*} /semi=%3B/dot=./comma=%2C | 392 | | | 393 |-----+-----------------------------------------------------------| 394 | ; | Path-style parameters, semicolon-prefixed (Sec 3.2.7) | 395 | | | 396 | | {;hello:5} ;hello=Hello | 397 | | {;list} ;list=red,green,blue | 398 | | {;list*} ;list=red;list=green;list=blue | 399 | | {;keys} ;keys=semi,%3B,dot,.,comma,%2C | 400 | | {;keys*} ;semi=%3B;dot=.;comma=%2C | 401 | | | 402 |-----+-----------------------------------------------------------| 403 | ? | Form-style query, ampersand-separated (Sec 3.2.8) | 404 | | | 405 | | {?var:3} ?var=val | 406 | | {?list} ?list=red,green,blue | 407 | | {?list*} ?list=red&list=green&list=blue | 408 | | {?keys} ?keys=semi,%3B,dot,.,comma,%2C | 409 | | {?keys*} ?semi=%3B&dot=.&comma=%2C | 410 | | | 411 |-----+-----------------------------------------------------------| 412 | & | Form-style query continuation (Sec 3.2.9) | 413 | | | 414 | | {&var:3} &var=val | 415 | | {&list} &list=red,green,blue | 416 | | {&list*} &list=red&list=green&list=blue | 417 | | {&keys} &keys=semi,%3B,dot,.,comma,%2C | 418 | | {&keys*} &semi=%3B&dot=.&comma=%2C | 419 | | | 420 `-----------------------------------------------------------------' 422 1.3. Design Considerations 424 Mechanisms similar to URI Templates have been defined within several 425 specifications, including WSDL [WSDL], WADL [WADL] and OpenSearch 426 [OpenSearch]. This specification extends and formally defines the 427 syntax so that URI Templates can be used consistently across multiple 428 Internet applications and within Internet message fields, while at 429 the same time retaining compatibility with those earlier definitions. 431 The URI Template syntax has been designed to carefully balance the 432 need for a powerful expansion mechanism with the need for ease of 433 implementation. The syntax is designed to be trivial to parse while 434 at the same time providing enough flexibility to express many common 435 template scenarios. Implementations are able to parse the template 436 and perform the expansions in a single pass. 438 Templates are simple and readable when used with common examples 439 because the single-character operators match the URI generic syntax 440 delimiters. The operator's associated delimiter (".", ";", "/", "?", 441 "&", and "#") is omitted when none of the listed variables are 442 defined. Likewise, the expansion process for ";" (path-style 443 parameters) will omit the "=" when the variable value is empty, 444 whereas the process for "?" (form-style parameters) will not omit the 445 "=" when the value is empty. Multiple variables and list values have 446 their values joined with "," if there is no predefined joining 447 mechanism for the operator. The "+" and "#" operators will 448 substitute unencoded reserved characters found inside the variable 449 values; the other operators will pct-encode reserved characters found 450 in the variable values prior to expansion. 452 The most common cases for URI spaces can be described with Level 1 453 template expressions. If we were only concerned with URI generation, 454 then the template syntax could be limited to just simple variable 455 expansion, since more complex forms could be generated by changing 456 the variable values. However, URI Templates have the additional goal 457 of describing the layout of identifiers in terms of preexisting data 458 values. The template syntax therefore includes operators that 459 reflect how resource identifiers are commonly allocated. Likewise, 460 since prefix substrings are often used to partition large spaces of 461 resources, modifiers on variable values provide a way to specify both 462 the substring and the full value string with a single variable name. 464 1.4. Limitations 466 Since a URI Template describes a superset of the identifiers, there 467 is no implication that every possible expansion for each delimited 468 variable expression corresponds to a URI of an existing resource. 469 Our expectation is that an application constructing URIs according to 470 the template will be provided with an appropriate set of values for 471 the variables being substituted, or at least a means of validating 472 user data-entry for those values. 474 URI Templates are not URIs: they do not identify an abstract or 475 physical resource, they are not parsed as URIs, and should not be 476 used in places where a URI would be expected unless the template 477 expressions will be expanded by a template processor prior to use. 478 Distinct field, element, or attribute names should be used to 479 differentiate protocol elements that carry a URI Template from those 480 that expect a URI reference. 482 Some URI Templates can be used in reverse for the purpose of variable 483 matching: comparing the template to a fully formed URI in order to 484 extract the variable parts from that URI and assign them to the named 485 variables. Variable matching only works well if the template 486 expressions are delimited by the beginning or end of the URI or by 487 characters that cannot be part of the expansion, such as reserved 488 characters surrounding a simple string expression. In general, 489 regular expression languages are better suited for variable matching. 491 1.5. Notational Conventions 493 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 494 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 495 document are to be interpreted as described in [RFC2119]. 497 This specification uses the Augmented Backus-Naur Form (ABNF) 498 notation of [RFC5234]. The following ABNF rules are imported from 499 the normative references [RFC5234], [RFC3986], and [RFC3987]. 501 ALPHA = %x41-5A / %x61-7A ; A-Z / a-z 502 DIGIT = %x30-39 ; 0-9 503 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" 504 ; case-insensitive 506 pct-encoded = "%" HEXDIG HEXDIG 507 unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" 508 reserved = gen-delims / sub-delims 509 gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" 510 sub-delims = "!" / "$" / "&" / "'" / "(" / ")" 511 / "*" / "+" / "," / ";" / "=" 513 ucschar = %xA0-D7FF / %xF900-FDCF / %xFDF0-FFEF 514 / %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD 515 / %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD 516 / %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD 517 / %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD 518 / %xD0000-DFFFD / %xE1000-EFFFD 520 iprivate = %xE000-F8FF / %xF0000-FFFFD / %x100000-10FFFD 522 1.6. Character Encoding and Unicode Normalization 524 This specification uses the terms "character", "character encoding 525 scheme", "code point", "coded character set", "glyph", "non-ASCII", 526 "normalization", "protocol element", and "regular expression" as they 527 are defined in [RFC6365]. 529 The ABNF notation defines its terminal values to be non-negative 530 integers (code points) that are a superset of the US-ASCII coded 531 character set [ASCII]. This specification defines terminal values as 532 code points within the Unicode coded character set [UNIV6]. 534 In spite of the syntax and template expansion process being defined 535 in terms of Unicode code points, it should be understood that 536 templates occur in practice as a sequence of characters in whatever 537 form or encoding is suitable for the context in which they occur, 538 whether that be octets embedded in a network protocol element or 539 glyphs painted on the side of a bus. This specification does not 540 mandate any particular character encoding scheme for mapping between 541 URI Template characters and the octets used to store or transmit 542 those characters. When a URI Template appears in a protocol element, 543 the character encoding scheme is defined by that protocol; without 544 such a definition, a URI Template is assumed to be in the same 545 character encoding scheme as the surrounding text. It is only during 546 the process of template expansion that a string of characters in a 547 URI Template is REQUIRED to be processed as a sequence of Unicode 548 code points. 550 The Unicode Standard [UNIV6] defines various equivalences between 551 sequences of characters for various purposes. Unicode Standard Annex 552 #15 [UTR15] defines various Normalization Forms for these 553 equivalences. The normalization form determines how to consistently 554 encode equivalent strings. In theory, all URI processing 555 implementations, including template processors, should use the same 556 normalization form for generating a URI reference. In practice, they 557 do not. If a value has been provided by the same server as the 558 resource, then it can be assumed that the string is already in the 559 form expected by that server. If a value is provided by a user, such 560 as via a data-entry dialog, then the string SHOULD be normalized as 561 Normalization Form C (NFC: Canonical Decomposition, followed by 562 Canonical Composition) prior to being used in expansions by a 563 template processor. 565 Likewise, when non-ASCII data that represents readable strings is 566 pct-encoded for use in a URI reference, a template processor MUST 567 first encode the string as UTF-8 [RFC3629] and then pct-encode any 568 octets that are not allowed in a URI reference. 570 2. Syntax 572 A URI Template is a string of printable Unicode characters that 573 contains zero or more embedded variable expressions, each expression 574 being delimited by a matching pair of braces ('{', '}'). 576 URI-Template = *( literals / expression ) 578 Although templates (and template processor implementations) are 579 described above in terms of four gradual levels, we define the URI- 580 Template syntax in terms of the ABNF for Level 4. A template 581 processor limited to lower level templates MAY exclude the ABNF rules 582 applicable only to higher levels. However, it is RECOMMENDED that 583 all parsers implement the full syntax such that unsupported levels 584 can be properly identified as such to the end user. 586 2.1. Literals 588 The characters outside of expressions in a URI Template string are 589 intended to be copied literally to the URI-reference if the character 590 is allowed in a URI (reserved / unreserved / pct-encoded) or, if not 591 allowed, copied to the URI-reference as the sequence of pct-encoded 592 triplets corresponding to that character's encoding in UTF-8 593 [RFC3629]. 595 literals = %x21 / %x23-24 / %x26 / %x28-3B / %x3D / %x3F-5B 596 / %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate 597 / pct-encoded 598 ; any Unicode character except: CTL, SP, 599 ; DQUOTE, "'", "%" (aside from pct-encoded), 600 ; "<", ">", "\", "^", "`", "{", "|", "}" 602 2.2. Expressions 604 Template expressions are the parameterized parts of a URI Template. 605 Each expression contains an optional operator, which defines the 606 expression type and its corresponding expansion process, followed by 607 a comma-separated list of variable specifiers (variable names and 608 optional value modifiers). If no operator is provided, the 609 expression defaults to simple variable expansion of unreserved 610 values. 612 expression = "{" [ operator ] variable-list "}" 613 operator = op-level2 / op-level3 / op-reserve 614 op-level2 = "+" / "#" 615 op-level3 = "." / "/" / ";" / "?" / "&" 616 op-reserve = "=" / "," / "!" / "@" / "|" 618 The operator characters have been chosen to reflect each of their 619 roles as reserved characters in the URI generic syntax. The 620 operators defined in Section 3 of this specification include: 622 + Reserved character strings; 624 # Fragment identifiers prefixed by "#"; 626 . Name labels or extensions prefixed by "."; 628 / Path segments prefixed by "/"; 630 ; Path parameter name or name=value pairs prefixed by ";"; 632 ? Query component beginning with "?" and consisting of 633 name=value pairs separated by "&"; and, 635 & Continuation of query-style &name=value pairs within 636 a literal query component. 638 The operator characters equals ("="), comma (","), exclamation ("!"), 639 at-sign ("@"), and pipe ("|") are reserved for future extensions. 641 The expression syntax specifically excludes use of the dollar ("$") 642 and parentheses ["(" and ")"] characters so that they remain 643 available for use outside the scope of this specification. For 644 example, a macro language might use these characters to apply macro 645 substitution to a string prior to that string being processed as a 646 URI Template. 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 literal string to use for the name in name=value 655 expansions (aside from when exploding an associative array). 656 Variable names are case-sensitive because the name might be expanded 657 within a case-sensitive URI component. 659 variable-list = varspec *( "," varspec ) 660 varspec = varname [ modifier-level4 ] 661 varname = varchar *( ["."] varchar ) 662 varchar = ALPHA / DIGIT / "_" / pct-encoded 664 A varname MAY contain one or more pct-encoded triplets. These 665 triplets are considered an essential part of the variable name and 666 are not decoded during processing. A varname containing pct-encoded 667 characters is not the same variable as a varname with those same 668 characters decoded. Applications that provide URI Templates are 669 expected to be consistent in their use of pct-encoding within 670 variable names. 672 An expression MAY reference variables that are unknown to the 673 template processor or whose value is set to a special "undefined" 674 value, such as undef or null. Such undefined variables are given 675 special treatment by the expansion process (Section 3.2.1). 677 A variable value that is a string of length zero is not considered 678 undefined; it has the defined value of an empty string. 680 In Level 4 templates, a variable may have a composite value in the 681 form of a list of values or an associative array of (name, value) 682 pairs. Such value types are not directly indicated by the template 683 syntax, but do have an impact on the expansion process 684 (Section 3.2.1). 686 A variable defined as a list value is considered undefined if the 687 list contains zero members. A variable defined as an associative 688 array of (name, value) pairs is considered undefined if the array 689 contains zero members or if all member names in the array are 690 associated with undefined values. 692 2.4. Value Modifiers 694 Each of the variables in a Level 4 template expression can have a 695 modifier indicating either that its expansion is limited to a prefix 696 of the variable's value string or that its expansion is exploded as a 697 composite value in the form of a value list or an associative array 698 of (name, value) pairs. 700 modifier-level4 = prefix / explode 702 2.4.1. Prefix Values 704 A prefix modifier indicates that the variable expansion is limited to 705 a prefix of the variable's value string. Prefix modifiers are often 706 used to partition an identifier space hierarchically, as is common in 707 reference indices and hash-based storage. It also serves to limit 708 the expanded value to a maximum number of characters. Prefix 709 modifiers are not applicable to variables that have composite values. 711 prefix = ":" max-length 712 max-length = %x31-39 0*3DIGIT ; positive integer < 10000 714 The max-length is a positive integer that refers to a maximum number 715 of characters from the beginning of the variable's value as a Unicode 716 string. Note that this numbering is in characters, not octets, in 717 order to avoid splitting between the octets of a multi-octet encoded 718 character or within a pct-encoded triplet. If the max-length is 719 greater than the length of the variable's value, then the entire 720 value string is used. 722 For example, 724 Given the variable assignments 726 var := "value" 727 semi := ";" 729 Example Template Expansion 731 {var} value 732 {var:20} value 733 {var:3} val 734 {semi} %3B 735 {semi:2} %3B 737 2.4.2. Composite Values 739 An explode ("*") modifier indicates that the variable is to be 740 treated as a composite value consisting of either a list of values or 741 an associative array of (name, value) pairs. Hence, the expansion 742 process is applied to each member of the composite as if it were 743 listed as a separate variable. This kind of variable specification 744 is significantly less self-documenting than non-exploded variables, 745 since there is less correspondence between the variable name and how 746 the URI reference appears after expansion. 748 explode = "*" 750 Since URI Templates do not contain an indication of type or schema, 751 the type for an exploded variable is assumed to be determined by 752 context. For example, the processor might be supplied values in a 753 form that differentiates values as strings, lists, or associative 754 arrays. Likewise, the context in which the template is used (script, 755 mark-up language, IDL, etc.) might define rules for associating 756 variable names with types, structures, or schema. 758 Explode modifiers improve brevity in the URI Template syntax. For 759 example, a resource that provides a geographic map for a given street 760 address might accept a hundred permutations on fields for address 761 input, including partial addresses (e.g., just the city or postal 762 code). Such a resource could be described as a template with each 763 and every address component listed in order, or with a far more 764 simple template that makes use of an explode modifier, as in 766 /mapper{?address*} 768 along with some context that defines what the variable named 769 "address" can include, such as by reference to some other standard 770 for addressing (e.g., [UPU-S42]). A recipient aware of the schema 771 can then provide appropriate expansions, such as: 773 /mapper?city=Newport%20Beach&state=CA 775 The expansion process for exploded variables is dependent on both the 776 operator being used and whether the composite value is to be treated 777 as a list of values or as an associative array of (name, value) 778 pairs. Structures are processed as if they are an associative array 779 with names corresponding to the fields in the structure definition 780 and "." separators used to indicate name hierarchy in substructures. 782 If a variable has a composite structure and only some of the fields 783 in that structure have defined values, then only the defined pairs 784 are present in the expansion. This can be useful for templates that 785 consist of a large number of potential query terms. 787 An explode modifier applied to a list variable causes the expansion 788 to iterate over the list's member values. For path and query 789 parameter expansions, each member value is paired with the variable's 790 name as a (varname, value) pair. This allows path and query 791 parameters to be repeated for multiple values, as in 793 Given the variable assignments 795 year := ("1965", "2000", "2012") 796 dom := ("example", "com") 798 Example Template Expansion 800 find{?year*} find?year=1965&year=2000&year=2012 801 www{.dom*} www.example.com 803 3. Expansion 805 The process of URI Template expansion is to scan the template string 806 from beginning to end, copying literal characters and replacing each 807 expression with the result of applying the expression's operator to 808 the value of each variable named in the expression. Each variable's 809 value MUST be formed prior to template expansion. 811 The requirements on expansion for each aspect of the URI Template 812 grammar are defined in this section. A non-normative algorithm for 813 the expansion process as a whole is provided in Appendix A. 815 If a template processor encounters a character sequence outside an 816 expression that does not match the grammar, then 817 processing of the template SHOULD cease, the URI-reference result 818 SHOULD contain the expanded part of the template followed by the 819 remainder unexpanded, and the location and type of error SHOULD be 820 indicated to the invoking application. 822 If an error is encountered in an expression, such as an operator or 823 value modifier that the template processor does not recognize or does 824 not yet support, or a character is found that is not allowed by the 825 grammar, then the unprocessed parts of the expression 826 SHOULD be copied to the result unexpanded, processing of the 827 remainder of the template SHOULD continue, and the location and type 828 of error SHOULD be indicated to the invoking application. 830 If an error occurs, the result returned might not be a valid URI 831 reference; it will be an incompletely expanded template string that 832 is only intended for diagnostic use. 834 3.1. Literal Expansion 836 If the literal character is allowed anywhere in the URI syntax 837 (unreserved / reserved / pct-encoded ), then it is copied directly to 838 the result string. Otherwise, the pct-encoded equivalent of the 839 literal character is copied to the result string by first encoding 840 the character as its sequence of octets in UTF-8 and then encoding 841 each such octet as a pct-encoded triplet. 843 3.2. Expression Expansion 845 Each expression is indicated by an opening brace ("{") character and 846 continues until the next closing brace ("}"). Expressions cannot be 847 nested. 849 An expression is expanded by determining its expression type and then 850 following that type's expansion process for each comma-separated 851 varspec in the expression. Level 1 templates are limited to the 852 default operator (simple string value expansion) and a single 853 variable per expression. Level 2 templates are limited to a single 854 varspec per expression. 856 The expression type is determined by looking at the first character 857 after the opening brace. If the character is an operator, then 858 remember the expression type associated with that operator for later 859 expansion decisions and skip to the next character for the variable- 860 list. If the first character is not an operator, then the expression 861 type is simple string expansion and the first character is the 862 beginning of the variable-list. 864 The examples in the subsections below use the following definitions 865 for variable values: 867 count := ("one", "two", "three") 868 dom := ("example", "com") 869 dub := "me/too" 870 hello := "Hello World!" 871 half := "50%" 872 var := "value" 873 who := "fred" 874 base := "http://example.com/home/" 875 path := "/foo/bar" 876 list := ("red", "green", "blue") 877 keys := [("semi",";"),("dot","."),("comma",",")] 878 v := "6" 879 x := "1024" 880 y := "768" 881 empty := "" 882 empty_keys := [] 883 undef := null 885 3.2.1. Variable Expansion 887 A variable that is undefined (Section 2.3) has no value and is 888 ignored by the expansion process. If all of the variables in an 889 expression are undefined, then the expression's expansion is the 890 empty string. 892 Variable expansion of a defined, non-empty value results in a 893 substring of allowed URI characters. As described in Section 1.6, 894 the expansion process is defined in terms of Unicode code points in 895 order to ensure that non-ASCII characters are consistently pct- 896 encoded in the resulting URI reference. One way for a template 897 processor to obtain a consistent expansion is to transcode the value 898 string to UTF-8 (if it is not already in UTF-8) and then transform 899 each octet that is not in the allowed set into the corresponding pct- 900 encoded triplet. Another is to map directly from the value's native 901 character encoding to the set of allowed URI characters, with any 902 remaining disallowed characters mapping to the sequence of pct- 903 encoded triplets that correspond to the octet(s) of that character 904 when encoded as UTF-8 [RFC3629]. 906 The allowed set for a given expansion depends on the expression type: 907 reserved ("+") and fragment ("#") expansions allow the set of 908 characters in the union of ( unreserved / reserved / pct-encoded ) to 909 be passed through without pct-encoding, whereas all other expression 910 types allow only unreserved characters to be passed through without 911 pct-encoding. Note that the percent character ("%") is only allowed 912 as part of a pct-encoded triplet and only for reserved/fragment 913 expansion: in all other cases, a value character of "%" MUST be pct- 914 encoded as "%25" by variable expansion. 916 If a variable appears more than once in an expression or within 917 multiple expressions of a URI Template, the value of that variable 918 MUST remain static throughout the expansion process (i.e., the 919 variable must have the same value for the purpose of calculating each 920 expansion). However, if reserved characters or pct-encoded triplets 921 occur in the value, they will be pct-encoded by some expression types 922 and not by others. 924 For a variable that is a simple string value, expansion consists of 925 appending the encoded value to the result string. An explode 926 modifier has no effect. A prefix modifier limits the expansion to 927 the first max-length characters of the decoded value. If the value 928 contains multi-octet or pct-encoded characters, care must be taken to 929 avoid splitting the value in mid-character: count each Unicode code 930 point as one character. 932 For a variable that is an associative array, expansion depends on 933 both the expression type and the presence of an explode modifier. If 934 there is no explode modifier, expansion consists of appending a 935 comma-separated concatenation of each (name, value) pair that has a 936 defined value. If there is an explode modifier, expansion consists 937 of appending each pair that has a defined value as either 938 "name=value" or, if the value is the empty string and the expression 939 type does not indicate form-style parameters (i.e., not a "?" or "&" 940 type), simply "name". Both name and value strings are encoded in the 941 same way as simple string values. A separator string is appended 942 between defined pairs according to the expression type, as defined by 943 the following table: 945 Type Separator 946 "," (default) 947 + "," 948 # "," 949 . "." 950 / "/" 951 ; ";" 952 ? "&" 953 & "&" 955 For a variable that is a list of values, expansion depends on both 956 the expression type and the presence of an explode modifier. If 957 there is no explode modifier, the expansion consists of a comma- 958 separated concatenation of the defined member string values. If 959 there is an explode modifier and the expression type expands named 960 parameters (";", "?", or "&"), then the list is expanded as if it 961 were an associative array in which each member value is paired with 962 the list's varname. Otherwise, the value will be expanded as if it 963 were a list of separate variable values, each value separated by the 964 expression type's associated separator as defined by the table above. 966 Example Template Expansion 968 {count} one,two,three 969 {count*} one,two,three 970 {/count} /one,two,three 971 {/count*} /one/two/three 972 {;count} ;count=one,two,three 973 {;count*} ;count=one;count=two;count=three 974 {?count} ?count=one,two,three 975 {?count*} ?count=one&count=two&count=three 976 {&count*} &count=one&count=two&count=three 978 3.2.2. Simple String Expansion: {var} 980 Simple string expansion is the default expression type when no 981 operator is given. 983 For each defined variable in the variable-list, perform variable 984 expansion, as defined in Section 3.2.1, with the allowed characters 985 being those in the unreserved set. If more than one variable has a 986 defined value, append a comma (",") to the result string as a 987 separator between variable expansions. 989 Example Template Expansion 991 {var} value 992 {hello} Hello%20World%21 993 {half} 50%25 994 O{empty}X OX 995 O{undef}X OX 996 {x,y} 1024,768 997 {x,hello,y} 1024,Hello%20World%21,768 998 ?{x,empty} ?1024, 999 ?{x,undef} ?1024 1000 ?{undef,y} ?768 1001 {var:3} val 1002 {var:30} value 1003 {list} red,green,blue 1004 {list*} red,green,blue 1005 {keys} semi,%3B,dot,.,comma,%2C 1006 {keys*} semi=%3B,dot=.,comma=%2C 1008 3.2.3. Reserved expansion: {+var} 1010 Reserved expansion, as indicated by the plus ("+") operator for Level 1011 2 and above templates, is identical to simple string expansion except 1012 that the substituted values may also contain pct-encoded triplets and 1013 characters in the reserved set. 1015 For each defined variable in the variable-list, perform variable 1016 expansion, as defined in Section 3.2.1, with the allowed characters 1017 being those in the set (unreserved / reserved / pct-encoded). If 1018 more than one variable has a defined value, append a comma (",") to 1019 the result string as a separator between variable expansions. 1021 Example Template Expansion 1023 {+var} value 1024 {+hello} Hello%20World! 1025 {+half} 50%25 1027 {base}index http%3A%2F%2Fexample.com%2Fhome%2Findex 1028 {+base}index http://example.com/home/index 1029 O{+empty}X OX 1030 O{+undef}X OX 1032 {+path}/here /foo/bar/here 1033 here?ref={+path} here?ref=/foo/bar 1034 up{+path}{var}/here up/foo/barvalue/here 1035 {+x,hello,y} 1024,Hello%20World!,768 1036 {+path,x}/here /foo/bar,1024/here 1038 {+path:6}/here /foo/b/here 1039 {+list} red,green,blue 1040 {+list*} red,green,blue 1041 {+keys} semi,;,dot,.,comma,, 1042 {+keys*} semi=;,dot=.,comma=, 1044 3.2.4. Fragment expansion: {#var} 1046 Fragment expansion, as indicated by the crosshatch ("#") operator for 1047 Level 2 and above templates, is identical to reserved expansion 1048 except that a crosshatch character (fragment delimiter) is appended 1049 first to the result string if any of the variables are defined. 1051 Example Template Expansion 1053 {#var} #value 1054 {#hello} #Hello%20World! 1055 {#half} #50%25 1056 foo{#empty} foo# 1057 foo{#undef} foo 1058 {#x,hello,y} #1024,Hello%20World!,768 1059 {#path,x}/here #/foo/bar,1024/here 1060 {#path:6}/here #/foo/b/here 1061 {#list} #red,green,blue 1062 {#list*} #red,green,blue 1063 {#keys} #semi,;,dot,.,comma,, 1064 {#keys*} #semi=;,dot=.,comma=, 1066 3.2.5. Label expansion with dot-prefix: {.var} 1068 Label expansion, as indicated by the dot (".") operator for Level 3 1069 and above templates, is useful for describing URI spaces with varying 1070 domain names or path selectors (e.g., filename extensions). 1072 For each defined variable in the variable-list, append "." to the 1073 result string and then perform variable expansion, as defined in 1074 Section 3.2.1, with the allowed characters being those in the 1075 unreserved set. 1077 Since "." is in the unreserved set, a value that contains a "." has 1078 the effect of adding multiple labels. 1080 Example Template Expansion 1082 {.who} .fred 1083 {.who,who} .fred.fred 1084 {.half,who} .50%25.fred 1085 www{.dom*} www.example.com 1086 X{.var} X.value 1087 X{.empty} X. 1088 X{.undef} X 1089 X{.var:3} X.val 1090 X{.list} X.red,green,blue 1091 X{.list*} X.red.green.blue 1092 X{.keys} X.semi,%3B,dot,.,comma,%2C 1093 X{.keys*} X.semi=%3B.dot=..comma=%2C 1094 X{.empty_keys} X 1095 X{.empty_keys*} X 1097 3.2.6. Path segment expansion: {/var} 1099 Path segment expansion, as indicated by the slash ("/") operator in 1100 Level 3 and above templates, is useful for describing URI path 1101 hierarchies. 1103 For each defined variable in the variable-list, append "/" to the 1104 result string and then perform variable expansion, as defined in 1105 Section 3.2.1, with the allowed characters being those in the 1106 unreserved set. 1108 Note that the expansion process for path segment expansion is 1109 identical to that of label expansion aside from the substitution of 1110 "/" instead of ".". However, unlike ".", a "/" is a reserved 1111 character and will be pct-encoded if found in a value. 1113 Example Template Expansion 1115 {/who} /fred 1116 {/who,who} /fred/fred 1117 {/half,who} /50%25/fred 1118 {/who,dub} /fred/me%2Ftoo 1119 {/var} /value 1120 {/var,empty} /value/ 1121 {/var,undef} /value 1122 {/var,x}/here /value/1024/here 1123 {/var:1,var} /v/value 1124 {/list} /red,green,blue 1125 {/list*} /red/green/blue 1126 {/list*,path:4} /red/green/blue/%2Ffoo 1127 {/keys} /semi,%3B,dot,.,comma,%2C 1128 {/keys*} /semi=%3B/dot=./comma=%2C 1130 3.2.7. Path-style parameter expansion: {;var} 1132 Path-style parameter expansion, as indicated by the semicolon (";") 1133 operator in Level 3 and above templates, is useful for describing URI 1134 path parameters, such as "path;property" or "path;name=value". 1136 For each defined variable in the variable-list: 1137 o append ";" to the result string; 1138 o if the variable has a simple string value or no explode modifier 1139 is given, then: 1140 * append the variable name (encoded as if it were a literal 1141 string) to the result string; 1142 * if the variable's value is not empty, append "=" to the result 1143 string; 1144 o perform variable expansion, as defined in Section 3.2.1, with the 1145 allowed characters being those in the unreserved set. 1147 Example Template Expansion 1149 {;who} ;who=fred 1150 {;half} ;half=50%25 1151 {;empty} ;empty 1152 {;v,empty,who} ;v=6;empty;who=fred 1153 {;v,bar,who} ;v=6;who=fred 1154 {;x,y} ;x=1024;y=768 1155 {;x,y,empty} ;x=1024;y=768;empty 1156 {;x,y,undef} ;x=1024;y=768 1157 {;hello:5} ;hello=Hello 1158 {;list} ;list=red,green,blue 1159 {;list*} ;list=red;list=green;list=blue 1160 {;keys} ;keys=semi,%3B,dot,.,comma,%2C 1161 {;keys*} ;semi=%3B;dot=.;comma=%2C 1163 3.2.8. Form-style query expansion: {?var} 1165 Form-style query expansion, as indicated by the question-mark ("?") 1166 operator in Level 3 and above templates, is useful for describing an 1167 entire optional query component. 1169 For each defined variable in the variable-list: 1170 o append "?" to the result string if this is the first defined value 1171 or append "&" thereafter; 1172 o if the variable has a simple string value or no explode modifier 1173 is given, append the variable name (encoded as if it were a 1174 literal string) and an equals character ("=") to the result 1175 string; and, 1176 o perform variable expansion, as defined in Section 3.2.1, with the 1177 allowed characters being those in the unreserved set. 1179 Example Template Expansion 1181 {?who} ?who=fred 1182 {?half} ?half=50%25 1183 {?x,y} ?x=1024&y=768 1184 {?x,y,empty} ?x=1024&y=768&empty= 1185 {?x,y,undef} ?x=1024&y=768 1186 {?var:3} ?var=val 1187 {?list} ?list=red,green,blue 1188 {?list*} ?list=red&list=green&list=blue 1189 {?keys} ?keys=semi,%3B,dot,.,comma,%2C 1190 {?keys*} ?semi=%3B&dot=.&comma=%2C 1192 3.2.9. Form-style query continuation: {&var} 1194 Form-style query continuation, as indicated by the ampersand ("&") 1195 operator in Level 3 and above templates, is useful for describing 1196 optional &name=value pairs in a template that already contains a 1197 literal query component with fixed parameters. 1199 For each defined variable in the variable-list: 1200 o append "&" to the result string; 1201 o if the variable has a simple string value or no explode modifier 1202 is given, append the variable name (encoded as if it were a 1203 literal string) and an equals character ("=") to the result 1204 string; and, 1205 o perform variable expansion, as defined in Section 3.2.1, with the 1206 allowed characters being those in the unreserved set. 1208 Example Template Expansion 1210 {&who} &who=fred 1211 {&half} &half=50%25 1212 ?fixed=yes{&x} ?fixed=yes&x=1024 1213 {&x,y,empty} &x=1024&y=768&empty= 1214 {&x,y,undef} &x=1024&y=768 1216 {&var:3} &var=val 1217 {&list} &list=red,green,blue 1218 {&list*} &list=red&list=green&list=blue 1219 {&keys} &keys=semi,%3B,dot,.,comma,%2C 1220 {&keys*} &semi=%3B&dot=.&comma=%2C 1222 4. Security Considerations 1224 A URI Template does not contain active or executable content. 1225 However, it might be possible to craft unanticipated URIs if an 1226 attacker is given control over the template or over the variable 1227 values within an expression that allows reserved characters in the 1228 expansion. In either case, the security considerations are largely 1229 determined by who provides the template, who provides the values to 1230 use for variables within the template, in what execution context the 1231 expansion occurs (client or server), and where the resulting URIs are 1232 used. 1234 This specification does not limit where URI Templates might be used. 1235 Current implementations exist within server-side development 1236 frameworks and within client-side javascript for computed links or 1237 forms. 1239 Within frameworks, templates usually act as guides for where data 1240 might occur within later (request-time) URIs in client requests. 1241 Hence, the security concerns are not in the templates themselves, but 1242 rather in how the server extracts and processes the user-provided 1243 data within a normal Web request. 1245 Within client-side implementations, a URI template has many of the 1246 same properties as HTML forms, except limited to URI characters and 1247 possibly included in HTTP header field values instead of just message 1248 body content. Care ought to be taken to ensure that potentially 1249 dangerous URI reference strings, such as those beginning with 1250 "javascript:", do not appear in the expansion unless both the 1251 template and the values are provided by a trusted source. 1253 Other security considerations are the same as those for URIs, as 1254 described in section 7 of [RFC3986]. 1256 5. IANA Considerations 1258 No IANA actions are required by this document. 1260 6. Acknowledgments 1262 The following people made contributions to this specification: Mike 1263 Burrows, Michaeljohn Clement, DeWitt Clinton, John Cowan, Stephen 1264 Farrell, Robbie Gates, Vijay K. Gurbani, Peter Johanson, Murray S. 1265 Kucherawy, James H. Manger, Tom Petch, Marc Portier, Pete Resnick, 1266 James Snell, and Jiankang Yao. 1268 7. References 1270 7.1. Normative References 1272 [ASCII] American National Standards Institute, "Coded Character 1273 Set - 7-bit American Standard Code for Information 1274 Interchange", ANSI X3.4, 1986. 1276 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1277 Requirement Levels", BCP 14, RFC 2119, March 1997. 1279 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1280 10646", STD 63, RFC 3629, November 2003. 1282 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1283 Resource Identifier (URI): Generic Syntax", STD 66, 1284 RFC 3986, January 2005. 1286 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 1287 Identifiers (IRIs)", RFC 3987, January 2005. 1289 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1290 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1292 [RFC6365] Hoffman, P. and J. Klensin, "Terminology Used in 1293 Internationalization in the IETF", BCP 166, RFC 6365, 1294 September 2011. 1296 [UNIV6] The Unicode Consortium, "The Unicode Standard, Version 1297 6.0.0", ISBN 978-1-936213-01-6, October 2011, 1298 . 1300 [UTR15] Davis, M. and M. Duerst, "Unicode Normalization Forms", 1301 Unicode Standard Annex # 15, April 2003, 1302 . 1305 7.2. Informative References 1307 [OpenSearch] 1308 Clinton, D., "OpenSearch 1.1", Draft 5, December 2011, 1309 . 1311 [UPU-S42] Universal Postal Union, "International Postal Address 1312 Components and Templates", UPU S42-1, November 2002, . 1315 [WADL] Hadley, M., "Web Application Description Language", World 1316 Wide Web Consortium Member Submission SUBM-wadl-20090831, 1317 August 2009, 1318 . 1320 [WSDL] Weerawarana, S., Moreau, J., Ryman, A., and R. Chinnici, 1321 "Web Services Description Language (WSDL) Version 2.0 Part 1322 1: Core Language", World Wide Web Consortium 1323 Recommendation REC-wsdl20-20070626, June 2007, 1324 . 1326 Appendix A. Implementation Hints 1328 The normative sections on expansion describe each operator with a 1329 separate expansion process for the sake of descriptive clarity. In 1330 actual implementations, we expect the expressions to be processed 1331 left-to-right using a common algorithm that has only minor variations 1332 in process per operator. This non-normative appendix describes one 1333 such algorithm. 1335 Initialize an empty result string and its non-error state. 1337 Scan the template and copy literals to the result string (as in 1338 Section 3.1) until an expression is indicated by a "{", an error is 1339 indicated by the presence of a non-literals character other than "{", 1340 or the template ends. When it ends, return the result string and its 1341 current error or non-error state. 1342 o If an expression is found, scan the template to the next "}" and 1343 extract the characters in between the braces. 1344 o If the template ends before a "}", then append the "{" and 1345 extracted characters to the result string and return with an error 1346 status indicating the expression is malformed. 1348 Examine the first character of the extracted expression for an 1349 operator. 1350 o If the expression ended (i.e., is "{}"), an operator is found that 1351 is unknown or unimplemented, or the character is not in the 1352 varchar set (Section 2.3), then append "{", the extracted 1353 expression, and "}" to the result string, remember that the result 1354 is in an error state, and then go back to scan the remainder of 1355 the template. 1356 o If a known and implemented operator is found, store the operator 1357 and skip to the next character to begin the varspec-list. 1358 o Otherwise, store the operator as NUL (simple string expansion). 1360 Use the following value table to determine the processing behavior by 1361 expression type operator. The entry for "first" is the string to 1362 append to the result first if any of the expression's variables are 1363 defined. The entry for "sep" is the separator to append to the 1364 result before any second (or subsequent) defined variable expansion. 1365 The entry for "named" is a boolean for whether or not the expansion 1366 includes the variable or key name when no explode modifier is given. 1367 The entry for "ifemp" is a string to append to the name if its 1368 corresponding value is empty. The entry for "allow" indicates what 1369 characters to allow unencoded within the value expansion: (U) means 1370 any character not in the unreserved set will be encoded; (U+R) means 1371 any character not in the union of (unreserved / reserved / pct- 1372 encoding) will be encoded; and, for both cases, each disallowed 1373 character is first encoded as its sequence of octets in UTF-8 and 1374 then each such octet is encoded as a pct-encoded triplet. 1376 .------------------------------------------------------------------. 1377 | NUL + . / ; ? & # | 1378 |------------------------------------------------------------------| 1379 | first | "" "" "." "/" ";" "?" "&" "#" | 1380 | sep | "," "," "." "/" ";" "&" "&" "," | 1381 | named | false false false false true true true false | 1382 | ifemp | "" "" "" "" "" "=" "=" "" | 1383 | allow | U U+R U U U U U U+R | 1384 `------------------------------------------------------------------' 1386 With the above table in mind, process the variable-list as follows: 1388 For each varspec, extract a variable name and optional modifier from 1389 the expression by scanning the variable-list until a character not in 1390 the varname set is found or the end of the expression is reached. 1391 o If it is the end of the expression and the varname is empty, go 1392 back to scan the remainder of the template. 1393 o If it is not the end of the expression and the last character 1394 found indicates a modifier ("*" or ":"), remember that modifier. 1395 If it is an explode ("*"), scan the next character. If it is a 1396 prefix (":"), continue scanning the next one to four characters 1397 for the max-length represented as a decimal integer and then, if 1398 it is still not the end of the expression, scan the next 1399 character. 1400 o If it is not the end of the expression and the last character 1401 found is not a comma (","), append "{", the stored operator (if 1402 any), the scanned varname and modifier, the remaining expression, 1403 and "}" to the result string, remember that the result is in an 1404 error state, and then go back to scan the remainder of the 1405 template. 1406 Lookup the value for the scanned variable name, and then 1407 o If the varname is unknown or corresponds to a variable with an 1408 undefined value (Section 2.3), then skip to the next varspec. 1409 o If this is the first defined variable for this expression, append 1410 the first string for this expression type to the result string and 1411 remember that it has been done. Otherwise, append the sep string 1412 to the result string. 1413 o If this variable's value is a string, then 1414 * if named is true, append the varname to the result string using 1415 the same encoding process as for literals, and 1416 + if the value is empty, append the ifemp string to the result 1417 string and skip to the next varspec; 1418 + otherwise, append "=" to the result string. 1419 * if a prefix modifier is present and the prefix length is less 1420 than the value string length in number of Unicode characters, 1421 append that number of characters from the beginning of the 1422 value string to the result string, after pct-encoding any 1423 characters that are not in the allow set, while taking care not 1424 to split multi-octet or pct-encoded triplet characters that 1425 represent a single Unicode code point; 1426 * otherwise, append the value to the result string after pct- 1427 encoding any characters that are not in the allow set. 1428 o else if no explode modifier is given, then 1429 * if named is true, append the varname to the result string using 1430 the same encoding process as for literals, and 1431 + if the value is empty, append the ifemp string to the result 1432 string and skip to the next varspec; 1433 + otherwise, append "=" to the result string; and 1434 * if this variable's value is a list, append each defined list 1435 member to the result string, after pct-encoding any characters 1436 that are not in the allow set, with a comma (",") appended to 1437 the result between each defined list member; 1438 * if this variable's value is an associative array or any other 1439 form of paired (name, value) structure, append each pair with a 1440 defined value to the result string as "name,value", after pct- 1441 encoding any characters that are not in the allow set, with a 1442 comma (",") appended to the result between each defined pair. 1444 o else if an explode modifier is given, then 1445 * if named is true, then for each defined list member or array 1446 (name, value) pair with a defined value, do: 1447 + if this is not the first defined member/value, append the 1448 sep string to the result string; 1449 + if this is a list, append the varname to the result string 1450 using the same encoding process as for literals; 1451 + if this is a pair, append the name to the result string 1452 using the same encoding process as for literals; 1453 + if the member/value is empty, append the ifemp string to the 1454 result string; otherwise, append "=" and the member/value to 1455 the result string, after pct-encoding any member/value 1456 characters that are not in the allow set. 1457 * else if named is false, then 1458 + if this is a list, append each defined list member to the 1459 result string, after pct-encoding any characters that are 1460 not in the allow set, with the sep string appended to the 1461 result between each defined list member. 1462 + if this is an array of (name, value) pairs, append each pair 1463 with a defined value to the result string as "name=value", 1464 after pct-encoding any characters that are not in the allow 1465 set, with the sep string appended to the result between each 1466 defined pair. 1467 When the variable-list for this expression is exhausted, go back to 1468 scan the remainder of the template. 1470 Authors' Addresses 1472 Joe Gregorio 1473 Google 1475 Email: joe@bitworking.org 1476 URI: http://bitworking.org/ 1478 Roy T. Fielding 1479 Adobe Systems Incorporated 1481 Email: fielding@gbiv.com 1482 URI: http://roy.gbiv.com/ 1483 Marc Hadley 1484 The MITRE Corporation 1486 Email: mhadley@mitre.org 1487 URI: http://mitre.org/ 1489 Mark Nottingham 1490 Rackspace 1492 Email: mnot@mnot.net 1493 URI: http://www.mnot.net/ 1495 David Orchard 1496 Salesforce.com 1498 Email: orchard@pacificspirit.com 1499 URI: http://www.pacificspirit.com/