rfc6570

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head profile="http://dublincore.org/documents/2008/08/04/dc-html/"> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="robots" content="index,follow" /> <meta name="creator" content="rfcmarkup version 1.104" /> <link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" /> <meta name="DC.Identifier" content="urn:ietf:rfc:6570" /> <meta name="DC.Description.Abstract" content="A URI Template is a compact sequence of characters for describing a\nrange of Uniform Resource Identifiers through variable expansion. This\nspecification defines the URI Template syntax and the process for\nexpanding a URI Template into a URI reference, along with guidelines\nfor the use of URI Templates on the Internet. [STANDARDS-TRACK]" /> <meta name="DC.Creator" content="Nottingham, Mark" /> <meta name="DC.Creator" content="Hadley, Marc" /> <meta name="DC.Creator" content="Gregorio, Joe" /> <meta name="DC.Creator" content="Orchard, David" /> <meta name="DC.Creator" content="Fielding, Roy T." /> <meta name="DC.Date.Issued" content="March, 2012" /> <meta name="DC.Title" content="URI Template" /> <link rel="icon" href="/images/rfc.png" type="image/png" /> <link rel="shortcut icon" href="/images/rfc.png" type="image/png" /> <title>RFC 6570 - URI Template</title> <style type="text/css"> body { margin: 0px 8px; font-size: 1em; } h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6 { font-weight: bold; line-height: 0pt; display: inline; white-space: pre; font-family: monospace; font-size: 1em; font-weight: bold; } pre { font-size: 1em; margin-top: 0px; margin-bottom: 0px; } .pre { white-space: pre; font-family: monospace; } .header{ font-weight: bold; } .newpage { page-break-before: always; } .invisible { text-decoration: none; color: white; } a.selflink { color: black; text-decoration: none; } @media print { body { font-family: monospace; font-size: 10.5pt; } h1, h2, h3, h4, h5, h6 { font-size: 1em; } a:link, a:visited { color: inherit; text-decoration: none; } .noprint { display: none; } } @media screen { .grey, .grey a:link, .grey a:visited { color: #777; } .docinfo { background-color: #EEE; } .top { border-top: 7px solid #EEE; } .bgwhite { background-color: white; } .bgred { background-color: #F44; } .bggrey { background-color: #666; } .bgbrown { background-color: #840; } .bgorange { background-color: #FA0; } .bgyellow { background-color: #EE0; } .bgmagenta{ background-color: #F4F; } .bgblue { background-color: #66F; } .bgcyan { background-color: #4DD; } .bggreen { background-color: #4F4; } .legend { font-size: 90%; } .cplate { font-size: 70%; border: solid grey 1px; } } </style>  <script type="text/javascript"> </script> </head> <body onload="addHeaderTags()"> <div style="height: 13px;"> <div onmouseover="this.style.cursor='pointer';" onclick="showElem('legend');" onmouseout="hideElem('legend')" style="height: 6px; position: absolute;" class="pre noprint docinfo bgblue" title="Click for colour legend." > </div> <div id="legend" class="docinfo noprint pre legend" style="position:absolute; top: 4px; left: 4ex; visibility:hidden; background-color: white; padding: 4px 9px 5px 7px; border: solid #345 1px; " onmouseover="showElem('legend');" onmouseout="hideElem('legend');"> </div> </div> [<a href="../html/" title="Document search and retrieval page">Docs</a>] [<a href="/rfc/rfc6570.txt" title="Plaintext version of this document">txt</a>|<a href="/pdf/rfc6570" title="PDF version of this document">pdf</a>] [<a href="./draft-gregorio-uritemplate" title="draft-gregorio-uritemplate">draft-gregorio-ur...</a>] [<a href="/rfcdiff?difftype=--hwdiff&url2=rfc6570" title="Inline diff (wdiff)">Diff1</a>] [<a href="/rfcdiff?url2=rfc6570" title="Side-by-side diff">Diff2</a>] PROPOSED STANDARD <pre> Internet Engineering Task Force (IETF) J. Gregorio Request for Comments: 6570 Google Category: Standards Track R. Fielding ISSN: 2070-1721 Adobe M. Hadley MITRE M. Nottingham Rackspace D. Orchard Salesforce.com March 2012 URI Template Abstract A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in <a href="./rfc5741#section-2">Section 2 of RFC 5741</a>. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at <a href="http://www.rfc-editor.org/info/rfc6570">http://www.rfc-editor.org/info/rfc6570</a>. Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to <a href="./bcp78">BCP 78</a> and the IETF Trust's Legal Provisions Relating to IETF Documents (<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must Gregorio, et al. Standards Track [Page 1] </pre><pre class='newpage'><a name="page-2" id="page-2" href="#page-2" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 include Simplified BSD License text as described in <a href="#section-4">Section 4</a>.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents <a href="#section-1">1</a>. Introduction ....................................................<a href="#page-3">3</a> <a href="#section-1.1">1.1</a>. Overview ...................................................<a href="#page-3">3</a> <a href="#section-1.2">1.2</a>. Levels and Expression Types ................................<a href="#page-5">5</a> <a href="#section-1.3">1.3</a>. Design Considerations ......................................<a href="#page-9">9</a> <a href="#section-1.4">1.4</a>. Limitations ...............................................<a href="#page-10">10</a> <a href="#section-1.5">1.5</a>. Notational Conventions ....................................<a href="#page-11">11</a> <a href="#section-1.6">1.6</a>. Character Encoding and Unicode Normalization ..............<a href="#page-12">12</a> <a href="#section-2">2</a>. Syntax .........................................................<a href="#page-13">13</a> <a href="#section-2.1">2.1</a>. Literals ..................................................<a href="#page-13">13</a> <a href="#section-2.2">2.2</a>. Expressions ...............................................<a href="#page-13">13</a> <a href="#section-2.3">2.3</a>. Variables .................................................<a href="#page-14">14</a> <a href="#section-2.4">2.4</a>. Value Modifiers ...........................................<a href="#page-15">15</a> <a href="#section-2.4.1">2.4.1</a>. Prefix Values ......................................<a href="#page-15">15</a> <a href="#section-2.4.2">2.4.2</a>. Composite Values ...................................<a href="#page-16">16</a> <a href="#section-3">3</a>. Expansion ......................................................<a href="#page-18">18</a> <a href="#section-3.1">3.1</a>. Literal Expansion .........................................<a href="#page-18">18</a> <a href="#section-3.2">3.2</a>. Expression Expansion ......................................<a href="#page-18">18</a> <a href="#section-3.2.1">3.2.1</a>. Variable Expansion .................................<a href="#page-19">19</a> <a href="#section-3.2.2">3.2.2</a>. Simple String Expansion: {var} .....................<a href="#page-21">21</a> <a href="#section-3.2.3">3.2.3</a>. Reserved Expansion: {+var} .........................<a href="#page-22">22</a> <a href="#section-3.2.4">3.2.4</a>. Fragment Expansion: {#var} .........................<a href="#page-23">23</a> <a href="#section-3.2.5">3.2.5</a>. Label Expansion with Dot-Prefix: {.var} ............<a href="#page-24">24</a> <a href="#section-3.2.6">3.2.6</a>. Path Segment Expansion: {/var} .....................<a href="#page-24">24</a> <a href="#section-3.2.7">3.2.7</a>. Path-Style Parameter Expansion: {;var} .............<a href="#page-25">25</a> <a href="#section-3.2.8">3.2.8</a>. Form-Style Query Expansion: {?var} .................<a href="#page-26">26</a> <a href="#section-3.2.9">3.2.9</a>. Form-Style Query Continuation: {&var} ..............<a href="#page-27">27</a> <a href="#section-4">4</a>. Security Considerations ........................................<a href="#page-27">27</a> <a href="#section-5">5</a>. Acknowledgments ................................................<a href="#page-28">28</a> <a href="#section-6">6</a>. References .....................................................<a href="#page-28">28</a> <a href="#section-6.1">6.1</a>. Normative References ......................................<a href="#page-28">28</a> <a href="#section-6.2">6.2</a>. Informative References ....................................<a href="#page-29">29</a> <a href="#appendix-A">Appendix A</a>. Implementation Hints ..................................<a href="#page-30">30</a> Gregorio, et al. Standards Track [Page 2] </pre><pre class='newpage'><a name="page-3" id="page-3" href="#page-3" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 <a class="selflink" name="section-1" href="#section-1">1</a>. Introduction <a class="selflink" name="section-1.1" href="#section-1.1">1.1</a>. Overview A Uniform Resource Identifier (URI) [<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>] is often used to identify a specific resource within a common space of similar resources (informally, a "URI space"). For example, personal web spaces are often delegated using a common pattern, such as http://example.com/~fred/ http://example.com/~mark/ or a set of dictionary entries might be grouped in a hierarchy by the first letter of the term, as in http://example.com/dictionary/c/cat http://example.com/dictionary/d/dog or a service interface might be invoked with various user input in a common pattern, as in http://example.com/search?q=cat&lang=en http://example.com/search?q=chien&lang=fr A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. URI Templates provide a mechanism for abstracting a space of resource identifiers such that the variable parts can be easily identified and described. URI Templates can have many uses, including the discovery of available services, configuring resource mappings, defining computed links, specifying interfaces, and other forms of programmatic interaction with resources. For example, the above resources could be described by the following URI Templates: http://example.com/~{username}/ http://example.com/dictionary/{term:1}/{term} http://example.com/search{?q,lang} We define the following terms: expression: The text between '{' and '}', including the enclosing braces, as defined in <a href="#section-2">Section 2</a>. expansion: The string result obtained from a template expression after processing it according to its expression type, list of variable names, and value modifiers, as defined in <a href="#section-3">Section 3</a>. Gregorio, et al. Standards Track [Page 3] </pre><pre class='newpage'><a name="page-4" id="page-4" href="#page-4" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 template processor: A program or library that, given a URI Template and a set of variables with values, transforms the template string into a URI reference by parsing the template for expressions and substituting each one with its corresponding expansion. A URI Template provides both a structural description of a URI space and, when variable values are provided, machine-readable instructions on how to construct a URI corresponding to those values. A URI Template is transformed into a URI reference by replacing each delimited expression with its value as defined by the expression type and the values of variables named within the expression. The expression types range from simple string expansion to multiple name=value lists. The expansions are based on the URI generic syntax, allowing an implementation to process any URI Template without knowing the scheme-specific requirements of every possible resulting URI. For example, the following URI Template includes a form-style parameter expression, as indicated by the "?" operator appearing before the variable names. http://www.example.com/foo{?query,number} The expansion process for expressions beginning with the question- mark ("?") operator follows the same pattern as form-style interfaces on the World Wide Web: http://www.example.com/foo{?query,number} \_____________/ | | For each defined variable in [ 'query', 'number' ], substitute "?" if it is the first substitution or "&" thereafter, followed by the variable name, '=', and the variable's value. If the variables have the values query := "mycelium" number := 100 then the expansion of the above URI Template is http://www.example.com/foo?query=mycelium&number=100 Alternatively, if 'query' is undefined, then the expansion would be http://www.example.com/foo?number=100 Gregorio, et al. Standards Track [Page 4] </pre><pre class='newpage'><a name="page-5" id="page-5" href="#page-5" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 or if both variables are undefined, then it would be http://www.example.com/foo A URI Template may be provided in absolute form, as in the examples above, or in relative form. A template is expanded before the resulting reference is resolved from relative to absolute form. Although the URI syntax is used for the result, the template string is allowed to contain the broader set of characters that can be found in Internationalized Resource Identifier (IRI) references [<a href="./rfc3987" title=""Internationalized Resource Identifiers (IRIs)"">RFC3987</a>]. Therefore, a URI Template is also an IRI template, and the result of template processing can be transformed to an IRI by following the process defined in <a href="./rfc3987#section-3.2">Section 3.2 of [RFC3987]</a>. <a class="selflink" name="section-1.2" href="#section-1.2">1.2</a>. Levels and Expression Types URI Templates are similar to a macro language with a fixed set of macro definitions: the expression type determines the expansion process. The default expression type is simple string expansion, wherein a single named variable is replaced by its value as a string after pct-encoding any characters not in the set of unreserved URI characters (<a href="#section-1.5">Section 1.5</a>). Since most template processors implemented prior to this specification have only implemented the default expression type, we refer to these as Level 1 templates. .-----------------------------------------------------------------. | Level 1 examples, with variables having values of | | | | var := "value" | | hello := "Hello World!" | | | |-----------------------------------------------------------------| | Op Expression Expansion | |-----------------------------------------------------------------| | | Simple string expansion (Sec 3.2.2) | | | | | | {var} value | | | {hello} Hello%20World%21 | `-----------------------------------------------------------------' Level 2 templates add the plus ("+") operator, for expansion of values that are allowed to include reserved URI characters (<a href="#section-1.5">Section 1.5</a>), and the crosshatch ("#") operator for expansion of fragment identifiers. Gregorio, et al. Standards Track [Page 5] </pre><pre class='newpage'><a name="page-6" id="page-6" href="#page-6" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 .-----------------------------------------------------------------. | Level 2 examples, with variables having values of | | | | var := "value" | | hello := "Hello World!" | | path := "/foo/bar" | | | |-----------------------------------------------------------------| | Op Expression Expansion | |-----------------------------------------------------------------| | + | Reserved string expansion (Sec 3.2.3) | | | | | | {+var} value | | | {+hello} Hello%20World! | | | {+path}/here /foo/bar/here | | | here?ref={+path} here?ref=/foo/bar | |-----+-----------------------------------------------------------| | # | Fragment expansion, crosshatch-prefixed (Sec 3.2.4) | | | | | | X{#var} X#value | | | X{#hello} X#Hello%20World! | `-----------------------------------------------------------------' Level 3 templates allow multiple variables per expression, each separated by a comma, and add more complex operators for dot-prefixed labels, slash-prefixed path segments, semicolon-prefixed path parameters, and the form-style construction of a query syntax consisting of name=value pairs that are separated by an ampersand character. .-----------------------------------------------------------------. | Level 3 examples, with variables having values of | | | | var := "value" | | hello := "Hello World!" | | empty := "" | | path := "/foo/bar" | | x := "1024" | | y := "768" | | | |-----------------------------------------------------------------| | Op Expression Expansion | |-----------------------------------------------------------------| | | String expansion with multiple variables (Sec 3.2.2) | | | | | | map?{x,y} map?1024,768 | | | {x,hello,y} 1024,Hello%20World%21,768 | | | | Gregorio, et al. Standards Track [Page 6] </pre><pre class='newpage'><a name="page-7" id="page-7" href="#page-7" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 |-----+-----------------------------------------------------------| | + | Reserved expansion with multiple variables (Sec 3.2.3) | | | | | | {+x,hello,y} 1024,Hello%20World!,768 | | | {+path,x}/here /foo/bar,1024/here | | | | |-----+-----------------------------------------------------------| | # | Fragment expansion with multiple variables (Sec 3.2.4) | | | | | | {#x,hello,y} #1024,Hello%20World!,768 | | | {#path,x}/here #/foo/bar,1024/here | | | | |-----+-----------------------------------------------------------| | . | Label expansion, dot-prefixed (Sec 3.2.5) | | | | | | X{.var} X.value | | | X{.x,y} X.1024.768 | | | | |-----+-----------------------------------------------------------| | / | Path segments, slash-prefixed (Sec 3.2.6) | | | | | | {/var} /value | | | {/var,x}/here /value/1024/here | | | | |-----+-----------------------------------------------------------| | ; | Path-style parameters, semicolon-prefixed (Sec 3.2.7) | | | | | | {;x,y} ;x=1024;y=768 | | | {;x,y,empty} ;x=1024;y=768;empty | | | | |-----+-----------------------------------------------------------| | ? | Form-style query, ampersand-separated (Sec 3.2.8) | | | | | | {?x,y} ?x=1024&y=768 | | | {?x,y,empty} ?x=1024&y=768&empty= | | | | |-----+-----------------------------------------------------------| | & | Form-style query continuation (Sec 3.2.9) | | | | | | ?fixed=yes{&x} ?fixed=yes&x=1024 | | | {&x,y,empty} &x=1024&y=768&empty= | | | | `-----------------------------------------------------------------' Finally, Level 4 templates add value modifiers as an optional suffix to each variable name. A prefix modifier (":") indicates that only a limited number of characters from the beginning of the value are used by the expansion (<a href="#section-2.4.1">Section 2.4.1</a>). An explode ("*") modifier Gregorio, et al. Standards Track [Page 7] </pre><pre class='newpage'><a name="page-8" id="page-8" href="#page-8" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 indicates that the variable is to be treated as a composite value, consisting of either a list of names or an associative array of (name, value) pairs, that is expanded as if each member were a separate variable (<a href="#section-2.4.2">Section 2.4.2</a>). .-----------------------------------------------------------------. | Level 4 examples, with variables having values of | | | | var := "value" | | hello := "Hello World!" | | path := "/foo/bar" | | list := ("red", "green", "blue") | | keys := [("semi",";"),("dot","."),("comma",",")] | | | | Op Expression Expansion | |-----------------------------------------------------------------| | | String expansion with value modifiers (Sec 3.2.2) | | | | | | {var:3} val | | | {var:30} value | | | {list} red,green,blue | | | {list*} red,green,blue | | | {keys} semi,%3B,dot,.,comma,%2C | | | {keys*} semi=%3B,dot=.,comma=%2C | | | | |-----+-----------------------------------------------------------| | + | Reserved expansion with value modifiers (Sec 3.2.3) | | | | | | {+path:6}/here /foo/b/here | | | {+list} red,green,blue | | | {+list*} red,green,blue | | | {+keys} semi,;,dot,.,comma,, | | | {+keys*} semi=;,dot=.,comma=, | | | | |-----+-----------------------------------------------------------| | # | Fragment expansion with value modifiers (Sec 3.2.4) | | | | | | {#path:6}/here #/foo/b/here | | | {#list} #red,green,blue | | | {#list*} #red,green,blue | | | {#keys} #semi,;,dot,.,comma,, | | | {#keys*} #semi=;,dot=.,comma=, | | | | |-----+-----------------------------------------------------------| | . | Label expansion, dot-prefixed (Sec 3.2.5) | | | | | | X{.var:3} X.val | | | X{.list} X.red,green,blue | Gregorio, et al. Standards Track [Page 8] </pre><pre class='newpage'><a name="page-9" id="page-9" href="#page-9" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 | | X{.list*} X.red.green.blue | | | X{.keys} X.semi,%3B,dot,.,comma,%2C | | | X{.keys*} X.semi=%3B.dot=..comma=%2C | | | | |-----+-----------------------------------------------------------| | / | Path segments, slash-prefixed (Sec 3.2.6) | | | | | | {/var:1,var} /v/value | | | {/list} /red,green,blue | | | {/list*} /red/green/blue | | | {/list*,path:4} /red/green/blue/%2Ffoo | | | {/keys} /semi,%3B,dot,.,comma,%2C | | | {/keys*} /semi=%3B/dot=./comma=%2C | | | | |-----+-----------------------------------------------------------| | ; | Path-style parameters, semicolon-prefixed (Sec 3.2.7) | | | | | | {;hello:5} ;hello=Hello | | | {;list} ;list=red,green,blue | | | {;list*} ;list=red;list=green;list=blue | | | {;keys} ;keys=semi,%3B,dot,.,comma,%2C | | | {;keys*} ;semi=%3B;dot=.;comma=%2C | | | | |-----+-----------------------------------------------------------| | ? | Form-style query, ampersand-separated (Sec 3.2.8) | | | | | | {?var:3} ?var=val | | | {?list} ?list=red,green,blue | | | {?list*} ?list=red&list=green&list=blue | | | {?keys} ?keys=semi,%3B,dot,.,comma,%2C | | | {?keys*} ?semi=%3B&dot=.&comma=%2C | | | | |-----+-----------------------------------------------------------| | & | Form-style query continuation (Sec 3.2.9) | | | | | | {&var:3} &var=val | | | {&list} &list=red,green,blue | | | {&list*} &list=red&list=green&list=blue | | | {&keys} &keys=semi,%3B,dot,.,comma,%2C | | | {&keys*} &semi=%3B&dot=.&comma=%2C | | | | `-----------------------------------------------------------------' <a class="selflink" name="section-1.3" href="#section-1.3">1.3</a>. Design Considerations Mechanisms similar to URI Templates have been defined within several specifications, including WSDL [<a href="#ref-WSDL" title=""Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language"">WSDL</a>], WADL [<a href="#ref-WADL" title=""Web Application Description Language"">WADL</a>], and OpenSearch [<a href="#ref-OpenSearch" title=""OpenSearch 1.1"">OpenSearch</a>]. This specification extends and formally defines the Gregorio, et al. Standards Track [Page 9] </pre><pre class='newpage'><a name="page-10" id="page-10" href="#page-10" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 syntax so that URI Templates can be used consistently across multiple Internet applications and within Internet message fields, while at the same time retaining compatibility with those earlier definitions. The URI Template syntax has been designed to carefully balance the need for a powerful expansion mechanism with the need for ease of implementation. The syntax is designed to be trivial to parse while at the same time providing enough flexibility to express many common template scenarios. Implementations are able to parse the template and perform the expansions in a single pass. Templates are simple and readable when used with common examples because the single-character operators match the URI generic syntax delimiters. The operator's associated delimiter (".", ";", "/", "?", "&", and "#") is omitted when none of the listed variables are defined. Likewise, the expansion process for ";" (path-style parameters) will omit the "=" when the variable value is empty, whereas the process for "?" (form-style parameters) will not omit the "=" when the value is empty. Multiple variables and list values have their values joined with "," if there is no predefined joining mechanism for the operator. The "+" and "#" operators will substitute unencoded reserved characters found inside the variable values; the other operators will pct-encode reserved characters found in the variable values prior to expansion. The most common cases for URI spaces can be described with Level 1 template expressions. If we were only concerned with URI generation, then the template syntax could be limited to just simple variable expansion, since more complex forms could be generated by changing the variable values. However, URI Templates have the additional goal of describing the layout of identifiers in terms of preexisting data values. Therefore, the template syntax includes operators that reflect how resource identifiers are commonly allocated. Likewise, since prefix substrings are often used to partition large spaces of resources, modifiers on variable values provide a way to specify both the substring and the full value string with a single variable name. <a class="selflink" name="section-1.4" href="#section-1.4">1.4</a>. Limitations Since a URI Template describes a superset of the identifiers, there is no implication that every possible expansion for each delimited variable expression corresponds to a URI of an existing resource. Our expectation is that an application constructing URIs according to the template will be provided with an appropriate set of values for the variables being substituted, or at least a means of validating user data-entry for those values. Gregorio, et al. Standards Track [Page 10] </pre><pre class='newpage'><a name="page-11" id="page-11" href="#page-11" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 URI Templates are not URIs: they do not identify an abstract or physical resource, they are not parsed as URIs, and they should not be used in places where a URI would be expected unless the template expressions will be expanded by a template processor prior to use. Distinct field, element, or attribute names should be used to differentiate protocol elements that carry a URI Template from those that expect a URI reference. Some URI Templates can be used in reverse for the purpose of variable matching: comparing the template to a fully formed URI in order to extract the variable parts from that URI and assign them to the named variables. Variable matching only works well if the template expressions are delimited by the beginning or end of the URI or by characters that cannot be part of the expansion, such as reserved characters surrounding a simple string expression. In general, regular expression languages are better suited for variable matching. <a class="selflink" name="section-1.5" href="#section-1.5">1.5</a>. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [<a href="./rfc2119" title=""Key words for use in RFCs to Indicate Requirement Levels"">RFC2119</a>]. This specification uses the Augmented Backus-Naur Form (ABNF) notation of [<a href="./rfc5234" title=""Augmented BNF for Syntax Specifications: ABNF"">RFC5234</a>]. The following ABNF rules are imported from the normative references [<a href="./rfc5234" title=""Augmented BNF for Syntax Specifications: ABNF"">RFC5234</a>], [<a href="./rfc3986" title=""Uniform Resource Identifier (URI): Generic Syntax"">RFC3986</a>], and [<a href="./rfc3987" title=""Internationalized Resource Identifiers (IRIs)"">RFC3987</a>]. ALPHA = %x41-5A / %x61-7A ; A-Z / a-z DIGIT = %x30-39 ; 0-9 HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" ; case-insensitive pct-encoded = "%" HEXDIG HEXDIG unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" reserved = gen-delims / sub-delims gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" ucschar = %xA0-D7FF / %xF900-FDCF / %xFDF0-FFEF / %x10000-1FFFD / %x20000-2FFFD / %x30000-3FFFD / %x40000-4FFFD / %x50000-5FFFD / %x60000-6FFFD / %x70000-7FFFD / %x80000-8FFFD / %x90000-9FFFD / %xA0000-AFFFD / %xB0000-BFFFD / %xC0000-CFFFD / %xD0000-DFFFD / %xE1000-EFFFD iprivate = %xE000-F8FF / %xF0000-FFFFD / %x100000-10FFFD Gregorio, et al. Standards Track [Page 11] </pre><pre class='newpage'><a name="page-12" id="page-12" href="#page-12" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 <a class="selflink" name="section-1.6" href="#section-1.6">1.6</a>. Character Encoding and Unicode Normalization This specification uses the terms "character", "character encoding scheme", "code point", "coded character set", "glyph", "non-ASCII", "normalization", "protocol element", and "regular expression" as they are defined in [<a href="./rfc6365" title=""Terminology Used in Internationalization in the IETF"">RFC6365</a>]. The ABNF notation defines its terminal values to be non-negative integers (code points) that are a superset of the US-ASCII coded character set [<a href="#ref-ASCII" title=""Coded Character Set - 7-bit American Standard Code for Information Interchange"">ASCII</a>]. This specification defines terminal values as code points within the Unicode coded character set [<a href="#ref-UNIV6" title=""The Unicode Standard, Version 6.0.0"">UNIV6</a>]. In spite of the syntax and template expansion process being defined in terms of Unicode code points, it should be understood that templates occur in practice as a sequence of characters in whatever form or encoding is suitable for the context in which they occur, whether that be octets embedded in a network protocol element or glyphs painted on the side of a bus. This specification does not mandate any particular character encoding scheme for mapping between URI Template characters and the octets used to store or transmit those characters. When a URI Template appears in a protocol element, the character encoding scheme is defined by that protocol; without such a definition, a URI Template is assumed to be in the same character encoding scheme as the surrounding text. It is only during the process of template expansion that a string of characters in a URI Template is REQUIRED to be processed as a sequence of Unicode code points. The Unicode Standard [<a href="#ref-UNIV6" title=""The Unicode Standard, Version 6.0.0"">UNIV6</a>] defines various equivalences between sequences of characters for various purposes. Unicode Standard Annex #15 [<a href="#ref-UTR15" title=""Unicode Normalization Forms"">UTR15</a>] defines various Normalization Forms for these equivalences. The normalization form determines how to consistently encode equivalent strings. In theory, all URI processing implementations, including template processors, should use the same normalization form for generating a URI reference. In practice, they do not. If a value has been provided by the same server as the resource, then it can be assumed that the string is already in the form expected by that server. If a value is provided by a user, such as via a data-entry dialog, then the string SHOULD be normalized as Normalization Form C (NFC: Canonical Decomposition, followed by Canonical Composition) prior to being used in expansions by a template processor. Likewise, when non-ASCII data that represents readable strings is pct-encoded for use in a URI reference, a template processor MUST first encode the string as UTF-8 [<a href="./rfc3629" title=""UTF-8, a transformation format of ISO 10646"">RFC3629</a>] and then pct-encode any octets that are not allowed in a URI reference. Gregorio, et al. Standards Track [Page 12] </pre><pre class='newpage'><a name="page-13" id="page-13" href="#page-13" class="invisible"> </a> <a href="./rfc6570">RFC 6570</a> URI Template March 2012 <a class="selflink" name="section-2" href="#section-2">2</a>. Syntax A URI Template is a string of printable Unicode characters that contains zero or more embedded variable expressions, each expression being delimited by a matching pair of braces ('{', '}'). URI-Template = *( literals / expression ) Although templates (and template processor implementations) are described above in terms of four gradual levels, we define the URI- Template syntax in terms of the ABNF for Level 4. A template processor limited to lower-level templates MAY exclude the ABNF rules applicable only to higher levels. However, it is RECOMMENDED that all parsers implement the full syntax such that unsupported levels can be properly identified as such to the end user. <a class="selflink" name="section-2.1" href="#section-2.1">2.1</a>. Literals The characters outside of expressions in a URI Template string are intended to be copied literally to the URI reference if the character is allowed in a URI (reserved / unreserved / pct-encoded) or, if not allowed, copied to the URI reference as the sequence of pct-encoded triplets corresponding to that character's encoding in UTF-8 [<a href="./rfc3629" title=""UTF-8, a transformation format of ISO 10646"">RFC3629</a>]. literals = %x21 / %x23-24 / %x26 / %x28-3B / %x3D / %x3F-5B / %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate / pct-encoded ; any Unicode character except: CTL, SP, ; DQUOTE, "'", "%" (aside from pct-encoded), ; "<", ">", "\", "^", "`", "{", "|", "}" <a class="selflink" name="section-2.2" href="#section-2.2">2.2</a>. Expressions Template expressions are the parameter