forked from jcgregorio/uri-templates
-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathdraft-gregorio-uritemplate-02.html
445 lines (409 loc) · 37.1 KB
/
draft-gregorio-uritemplate-02.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>URI Template</title><style type="text/css" title="Xml2Rfc (sans serif)">
a {
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
a:active {
text-decoration: underline;
}
address {
margin-top: 1em;
margin-left: 2em;
font-style: normal;
}
body {
color: #000000;
font-family: verdana, helvetica, arial, sans-serif;
font-size: 10pt;
}
cite {
font-style: normal;
}
dl {
margin-left: 2em;
}
dl.empty dd {
margin-top: .5em;
}
dt {
margin-top: .5em;
}
h1 {
color: #333333;
font-size: 14pt;
line-height: 21pt;
page-break-after: avoid;
}
h1.np {
page-break-before: always;
}
h1 a {
color: #333333;
}
h2 {
color: #000000;
font-size: 12pt;
line-height: 15pt;
page-break-after: avoid;
}
h2 a {
color: #000000;
}
h3 {
color: #000000;
font-size: 10pt;
page-break-after: avoid;
}
h3 a {
color: #000000;
}
h4 {
color: #000000;
font-size: 10pt;
page-break-after: avoid;
}
h4 a {
color: #000000;
}
h5 {
color: #000000;
font-size: 10pt;
page-break-after: avoid;
}
h5 a {
color: #000000;
}
img {
margin-left: 3em;
}
li {
margin-left: 2em;
margin-right: 2em;
}
ol {
margin-left: 2em;
margin-right: 2em;
}
p {
margin-left: 2em;
margin-right: 2em;
}
pre {
margin-left: 3em;
background-color: lightyellow;
padding: .25em;
}
pre.text2 {
border-style: dotted;
border-width: 1px;
background-color: #f0f0f0;
width: 69em;
}
pre.inline {
background-color: white;
padding: 0em;
}
pre.text {
border-style: dotted;
border-width: 1px;
background-color: #f8f8f8;
width: 69em;
}
pre.drawing {
border-style: solid;
border-width: 1px;
background-color: #f8f8f8;
padding: 2em;
}
table {
margin-left: 2em;
}
table.tt {
vertical-align: top;
}
table.full {
border-style: outset;
border-width: 1px;
}
table.headers {
border-style: outset;
border-width: 1px;
}
table.tt td {
vertical-align: top;
}
table.full td {
border-style: inset;
border-width: 1px;
}
table.tt th {
vertical-align: top;
}
table.full th {
border-style: inset;
border-width: 1px;
}
table.headers th {
border-style: none none inset none;
border-width: 1px;
}
table.header {
width: 95%;
font-size: 10pt;
color: white;
}
td.top {
vertical-align: top;
}
td.topnowrap {
vertical-align: top;
white-space: nowrap;
}
td.front {
background-color: gray;
width: 50%;
}
thead {
display:table-header-group;
}
ul.toc {
list-style: none;
margin-left: 1.5em;
margin-right: 0em;
padding-left: 0em;
}
li.tocline0 {
line-height: 150%;
font-weight: bold;
font-size: 10pt;
margin-left: 0em;
margin-right: 0em;
}
li.tocline1 {
line-height: normal;
font-weight: normal;
font-size: 9pt;
margin-left: 0em;
margin-right: 0em;
}
li.tocline2 {
font-size: 0pt;
}
ul.ind {
list-style: none;
margin-left: 1.5em;
margin-right: 0em;
padding-left: 0em;
}
li.indline0 {
font-weight: bold;
line-height: 200%;
margin-left: 0em;
margin-right: 0em;
}
li.indline1 {
font-weight: normal;
line-height: 150%;
margin-left: 0em;
margin-right: 0em;
}
.comment {
background-color: yellow;
}
.center {
text-align: center;
}
.error {
font-size: 14pt;
background-color: red;
}
.figure {
font-weight: bold;
text-align: center;
font-size: 9pt;
}
.filename {
color: #333333;
font-weight: bold;
font-size: 12pt;
line-height: 21pt;
text-align: center;
}
.fn {
font-weight: bold;
}
.hidden {
display: none;
}
.left {
text-align: left;
}
.right {
text-align: right;
}
.title {
color: #990000;
font-size: 18pt;
line-height: 18pt;
font-weight: bold;
text-align: center;
margin-top: 36pt;
}
.vcardline {
display: block;
}
.warning {
font-size: 14pt;
background-color: yellow;
}
@media print {
.noprint {
display: none;
}
table.header {
width: 90%;
}
td.header-l {
width: 50%;
color: black;
background-color: white;
vertical-align: top;
font-size: 10pt;
}
td.header-r {
width: 33%;
color: black;
background-color: white;
vertical-align: top;
text-align: right;
font-size: 10pt;
}
ul.toc a::after {
content: leader('.') target-counter(attr(href), page);
}
a.iref {
content: target-counter(attr(href), page);
}
.print2col {
column-count: 2;
-moz-column-count: 2;
}
}
@page {
@top-left {
content: "INTERNET DRAFT";
}
@top-right {
content: "Nov 2007";
}
@top-center {
content: "URI Template";
}
@bottom-left {
content: "Gregorio, et al.";
}
@bottom-center {
content: "Standards Track";
}
@bottom-right {
content: "[Page " counter(page) "]";
}
}
@page:first {
@top-left {
content: normal;
}
@top-right {
content: normal;
}
@top-center {
content: normal;
}
}
</style><link rel="Contents" href="#rfc.toc"><link rel="Author" href="#rfc.authors"><link rel="Copyright" href="#rfc.copyright"><link rel="Chapter" title="1 Introduction" href="#rfc.section.1"><link rel="Chapter" title="2 Characters" href="#rfc.section.2"><link rel="Chapter" title="3 URI Template" href="#rfc.section.3"><link rel="Chapter" title="4 Security Considerations" href="#rfc.section.4"><link rel="Chapter" title="5 IANA Considerations" href="#rfc.section.5"><link rel="Chapter" title="6 Appendix A - Parsing URI Template Expansions" href="#rfc.section.6"><link rel="Chapter" href="#rfc.section.7" title="7 Normative References"><link rel="Appendix" title="A Contributors" href="#rfc.section.A"><link rel="Appendix" title="B Revision History" href="#rfc.section.B"><meta name="generator" content="http://greenbytes.de/tech/webdav/rfc2629.xslt, Revision 1.310, 2007/01/07 13:32:43, XSLT vendor: libxslt http://xmlsoft.org/XSLT/"><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/"><meta name="DC.Creator" content="Gregorio, J.C."><meta name="DC.Creator" content="Hadley, M.H."><meta name="DC.Creator" content="Nottingham, M.N."><meta name="DC.Creator" content="Orchard, D.O."><meta name="DC.Identifier" content="urn:ietf:id:draft-gregorio-uritemplate-02"><meta name="DC.Date.Issued" scheme="ISO8601" content="2007-WRONG SYNTAX FOR MONTH"><meta name="DC.Description.Abstract" content="A URI Template is a compact sequence of characters used for the construction of URIs. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI, along with guidelines and security considerations for the use of URI Templates on the Internet. The URI Template syntax allows for the construction of strings that are a superset of URIs, allowing an implementation to process any URI Template without knowing the scheme-specific requirements of every possible resulting URI."></head><body><table summary="header information" class="header" border="0" cellpadding="1" cellspacing="1"><tr><td class="front left">Network Working Group</td><td class="front right">J.C. Gregorio, Editor</td></tr><tr><td class="front left">Internet Draft</td><td class="front right">Google</td></tr><tr><td class="front left">
<draft-gregorio-uritemplate-02>
</td><td class="front right">M.H. Hadley, Editor</td></tr><tr><td class="front left">Intended status: Standards Track</td><td class="front right">Sun Microsystems</td></tr><tr><td class="front left">Expires: WRONG SYNTAX FOR MONTH</td><td class="front right">M.N. Nottingham, Editor</td></tr><tr><td class="front left"></td><td class="front right"></td></tr><tr><td class="front left"></td><td class="front right">D.O. Orchard</td></tr><tr><td class="front left"></td><td class="front right">BEA Systems, Inc.</td></tr><tr><td class="front left"></td><td class="front right">Nov 2007</td></tr></table><p class="title">URI Template<br><span class="filename">draft-gregorio-uritemplate-02</span></p><h1><a id="rfc.status" href="#rfc.status">Status of this Memo</a></h1><p>By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.</p><p>Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.</p><p>Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress”.</p><p>The list of current Internet-Drafts can be accessed at <<a href="http://www.ietf.org/ietf/1id-abstracts.txt">http://www.ietf.org/ietf/1id-abstracts.txt</a>>.</p><p>The list of Internet-Draft Shadow Directories can be accessed at <<a href="http://www.ietf.org/shadow.html">http://www.ietf.org/shadow.html</a>>.</p><p>This Internet-Draft will expire in WRONG SYNTAX FOR MONTH.</p><h1><a id="rfc.copyrightnotice" href="#rfc.copyrightnotice">Copyright Notice</a></h1><p>Copyright © The IETF Trust (2007). All Rights Reserved.</p><h1 id="rfc.abstract"><a href="#rfc.abstract">Abstract</a></h1> <p>A URI Template is a compact sequence of characters used for the construction of URIs. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI, along with guidelines and security considerations for the use of URI Templates on the Internet. The URI Template syntax allows for the construction of strings that are a superset of URIs, allowing an implementation to process any URI Template without knowing the scheme-specific requirements of every possible resulting URI.</p> <h1 id="rfc.note.1"><a href="#rfc.note.1">Editorial Note</a></h1> <p>To provide feedback on this Internet-Draft, join the <a href="http://lists.w3.org/Archives/Public/uri/">W3C URI mailing list (http://lists.w3.org/Archives/Public/uri/)</a>.</p> <hr class="noprint"><h1 class="np" id="rfc.toc"><a href="#rfc.toc">Table of Contents</a></h1><ul class="toc"><li class="tocline0">1. <a href="#rfc.section.1">Introduction</a><ul class="toc"><li class="tocline1">1.1 <a href="#rfc.section.1.1">Overview</a></li><li class="tocline1">1.2 <a href="#rfc.section.1.2">Design Considerations</a></li><li class="tocline1">1.3 <a href="#rfc.section.1.3">Notational Conventions</a></li></ul></li><li class="tocline0">2. <a href="#rfc.section.2">Characters</a></li><li class="tocline0">3. <a href="#rfc.section.3">URI Template</a><ul class="toc"><li class="tocline1">3.1 <a href="#variables">Variables</a></li><li class="tocline1">3.2 <a href="#expansions">Template Expansions</a></li><li class="tocline1">3.3 <a href="#evaluating">URI Template Substitution</a><ul class="toc"><li class="tocline1">3.3.1 <a href="#opt">The 'opt' operator</a></li><li class="tocline1">3.3.2 <a href="#neg">The 'neg' operator</a></li><li class="tocline1">3.3.3 <a href="#prefix">The 'prefix' operator</a></li><li class="tocline1">3.3.4 <a href="#append">The 'append' operator</a></li><li class="tocline1">3.3.5 <a href="#join">The 'join' operator</a></li><li class="tocline1">3.3.6 <a href="#listjoin">The 'listjoin' operator</a></li></ul></li><li class="tocline1">3.4 <a href="#examples">Examples</a></li></ul></li><li class="tocline0">4. <a href="#rfc.section.4">Security Considerations</a></li><li class="tocline0">5. <a href="#iana">IANA Considerations</a></li><li class="tocline0">6. <a href="#appendix_a">Appendix A - Parsing URI Template Expansions</a></li><li class="tocline0">7. <a href="#rfc.references">Normative References</a></li><li class="tocline0"><a href="#rfc.authors">Authors' Addresses</a></li><li class="tocline0">A. <a href="#rfc.section.A">Contributors</a></li><li class="tocline0">B. <a href="#rfc.section.B">Revision History</a></li><li class="tocline0"><a href="#rfc.ipr">Intellectual Property and Copyright Statements</a></li></ul><h1 id="rfc.section.1" class="np"><a href="#rfc.section.1">1.</a> Introduction</h1><p id="rfc.section.1.p.1">A URI Template provides a simple and extensible format for URI construction. A URI Template is a string that contains embedded expansions, text marked off in matching braces ('{', '}'), that denotes a part of the string that is to be substituted by a template processor to produce a URI. A URI Template is transformed into a URI by substituting the expansions with their calculated value.</p><p id="rfc.section.1.p.2">Several specifications have defined URI Templates with varying levels of formality, such as WSDL, WADL and OpenSearch. This specification is derived from these concepts, giving a rigorous definition to such templates.</p><p id="rfc.section.1.p.3">This specification uses the terms "character" and "coded character set" in accordance with the definitions provided in <a href="#RFC2978"><cite title="IANA Charset Registration Procedures">[RFC2978]</cite></a>, and "character encoding" in place of what <a href="#RFC2978"><cite title="IANA Charset Registration Procedures">[RFC2978]</cite></a> refers to as a "charset".</p><h2 id="rfc.section.1.1"><a href="#rfc.section.1.1">1.1</a> Overview</h2><p id="rfc.section.1.1.p.1">A URI Template allows a structural description of URIs while allowing a consumer of the template to construct a final URI by providing the values of the expansion variables. For example, given the following URI Template:</p><div id="rfc.figure.u.1"></div><pre>
http://www.example.com/users/{userid}</pre><p id="rfc.section.1.1.p.3">And the following variable value</p><div id="rfc.figure.u.2"></div><pre>
userid := fred</pre><p id="rfc.section.1.1.p.5">The expansion of the URI Template is:</p><div id="rfc.figure.u.3"></div><pre>
http://www.example.com/users/fred</pre><p id="rfc.section.1.1.p.7">URI Templates can be used as a machine-readable forms language. By allowing clients to form their own identifiers based on templates given to them by the URI's authority it's possible to construct dynamic systems that use more of the URI than traditional HTML forms. For example:</p><div id="rfc.figure.u.4"></div><pre>
http://www.example.org/products/{upc}/buyers?page={page_num}</pre> <p id="rfc.section.1.1.p.9">URI Templates can also be used to compose URI-centric protocols without impinging on authorities' control of their URI space. For example, there are many emerging conventions for passing around login information between sites using URIs. Forcing people to use a well-known query parameter isn't good practice, but using URI Templates allows different sites to specify local ways of conveying the same information:</p><div id="rfc.figure.u.5"></div><pre>
http://auth.example.com/userauth;{return-uri}</pre><div id="rfc.figure.u.6"></div><pre>
http://login.example.org/login?back={return-uri}</pre><h2 id="rfc.section.1.2"><a href="#rfc.section.1.2">1.2</a> Design Considerations</h2><p id="rfc.section.1.2.p.1">The URI Template syntax has been designed to carefully balance the need for a powerful substitution mechanism with ease of implementation and security. The syntax is designed to be easy to parse while at the same time providing enough flexibility to express many common templating scenarios. On the balance, the template processing is not Turing complete, thus avoiding a number of security issues, ala the billion-laughs attack of XML DTDs.</p><p id="rfc.section.1.2.p.2">Another consideration was to keep the syntax and processing in-line with the pre-existing templating schemes present in OpenSearch, WSDL and WADL.</p><p id="rfc.section.1.2.p.3">The final design consideration was control over the placement of reserved characters in the URI generated from a URI Template. The reserved characters in a URI Template can only appear in the non-expansion text, or in the argument to an operator, both locations are dictated by the URI Template author. Given the percent-encoding rules for variable values this means that the source of all structure, i.e reserved characters, in a URI generated from a URI Template is decided by the URI Template author.</p><h2 id="rfc.section.1.3"><a href="#rfc.section.1.3">1.3</a> Notational Conventions</h2><p id="rfc.section.1.3.p.1">This specification uses the Augmented Backus-Naur Form (ABNF) notation of <a href="#RFC4234"><cite title="Augmented BNF for Syntax Specifications: ABNF">[RFC4234]</cite></a>, including the following core ABNF syntax rules defined by that specification: ALPHA (letters) and DIGIT (decimal digits). See <a href="#RFC3986"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a> for the definitions of the URI-reference, percent-encoded, reserved, and unreserved rules.</p><p id="rfc.section.1.3.p.2">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"><cite title="Key words for use in RFCs to Indicate Requirement Levels">[RFC2119]</cite></a>.</p><h1 id="rfc.section.2"><a href="#rfc.section.2">2.</a> Characters</h1><p id="rfc.section.2.p.1">A URI Template is a sequence of characters, and has the same issues as URIs with regard to codepoints and character sets. That is, URI Template characters are frequently encoded as octets for transport or presentation. This specification does not mandate any particular character encoding for mapping between URI characters and the octets used to store or transmit those characters. When a URI appears in a protocol element, the character encoding is defined by that protocol; without such a definition, a URI is assumed to be in the same character encoding as the surrounding text.</p><p id="rfc.section.2.p.2">The ABNF notation defines its terminal values to be non-negative integers (codepoints) based on the US-ASCII coded character set <a href="#ASCII"><cite title="Coded Character Set - 7-bit American Standard Code for Information Interchange">[ASCII]</cite></a>. Because a URI is a sequence of characters, we must invert that relation in order to understand the URI syntax. Therefore, the integer values used by the ABNF must be mapped back to their corresponding characters via US-ASCII in order to complete the syntax rules.</p><h1 id="rfc.section.3"><a href="#rfc.section.3">3.</a> URI Template</h1><p id="rfc.section.3.p.1">A URI Template is a sequence of characters that contains one or more embedded template expansions, see <a href="#expansions" title="Template Expansions">Section 3.2</a>. Each expansion references one or more variables whose values are used in when determining the substition value for an expansion. A URI Template becomes a URI when the template expansions are substituted with their values (see <a href="#evaluating" title="URI Template Substitution">Section 3.3</a>). The generated URI will be a URI-reference, i.e. either an absolute URI or a relative reference.</p><h2 id="rfc.section.3.1"><a href="#rfc.section.3.1">3.1</a> <a id="variables" href="#variables">Variables</a></h2><p id="rfc.section.3.1.p.1">The value of every non-list variable, and the individual values in list variables, must come from ( unreserved / pct-encoded ). For variable values that are strings that have characters outside that range, the entire string must be converted into UTF-8 <a href="#RFC3629"><cite title="UTF-8, a transformation format of ISO 10646">[RFC3629]</cite></a>, and then every octet of the UTF-8 string that falls outside of ( unreserved / pct-encoded ) MUST be percent-encoded, as per <a href="#RFC3986"><cite title="Uniform Resource Identifier (URI): Generic Syntax">[RFC3986]</cite></a>, section 2.1.</p><p id="rfc.section.3.1.p.2">This does not imply that every variable value can be decoded into a Unicode string. For example, a variable value may be a binary blob that has been percent-encoded before being passed into the template processor.</p><p id="rfc.section.3.1.p.3">The Unicode Standard <a href="#UNIV4"><cite title="The Unicode Standard, Version 4.0.1, defined by: The Unicode Standard, Version 4.0 (Reading, MA, Addison-Wesley, 2003. ISBN 0-321-18578-1), as amended by Unicode 4.0.1 (http://www.unicode.org/versions/Unicode4.0.1/)">[UNIV4]</cite></a> defines various equivalences between sequences of characters for various purposes. Unicode Standard Annex #15 <a href="#UTR15"><cite title="Unicode Normalization Forms">[UTR15]</cite></a> defines various Normalization Forms for these equivalences, in particular Normalization Form C (NFC, Canonical Decomposition, followed by Canonical Composition) and Normalization Form KC (NFKC, Compatibility Decomposition, followed by Canonical Composition). Since different Normalized Forms unicode strings will have different UTF-8 represenations it is RECOMMEDED that unicode strings use Normalized Form NFC.</p><p id="rfc.section.3.1.p.4">The meaning of 'defined' for a variable is progamming language and library specific and beyond the scope of this specification. Also beyond the scope of this specification is the allowable programming constructs that can be used for a list variable used in the 'listjoin' operator. For example, a Python implementation might allow only built-in list types, or it may allow any iterable to be used as the source for a list variable.</p><p id="rfc.section.3.1.p.5">A variable may appear in more than one expansion in a URI Template. The value used for that variable must remain the same for every template expansion when converting a URI Template into a URI.</p><h2 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2</a> <a id="expansions" href="#expansions">Template Expansions</a></h2><p id="rfc.section.3.2.p.1">Template expansions are the parameterized components of a URI Template. A template expansion MUST match the 'expansion' rule.</p><div id="rfc.figure.u.7"></div> <pre>
op = 1*ALPHA
arg = *(reserved / unreserved / pct-encoded)
var = varname [ '=' vardefault ]
vars = var [ *("," var) ]
varname = (ALPHA / DIGIT)*(ALPHA / DIGIT / "." / "_" / "-" )
vardefault = *(unreserved / pct-encoded)
operator = "-" op "|" arg "|" vars
expansion = "{" ( var / operator ) "}"
</pre> <h2 id="rfc.section.3.3"><a href="#rfc.section.3.3">3.3</a> <a id="evaluating" href="#evaluating">URI Template Substitution</a></h2><p id="rfc.section.3.3.p.1">Template substitution is the process of turning a URI Template into a URI given definitions for the variables used in the template. Substitution replaces each expansion with its calculated value.</p><p id="rfc.section.3.3.p.2">Every expansion consists of either a variable ('var') or an operator expression. In a variable ('var') expansion, if the variable is defined and non-empty then substitute the value of the variable, otherwise substitute the default value. If no default value is given then substitute with the empty string.</p><p id="rfc.section.3.3.p.3">If the expansion is an operator then the substitution value is determined by the given operator. Each operator works only on the variables that are defined within their expansion.</p><h3 id="rfc.section.3.3.1"><a href="#rfc.section.3.3.1">3.3.1</a> <a id="opt" href="#opt">The 'opt' operator</a></h3><p id="rfc.section.3.3.1.p.1">If the one or more of the variables are defined and non-empty then substitute the value of 'arg', otherwise substitute the empty string.</p><h3 id="rfc.section.3.3.2"><a href="#rfc.section.3.3.2">3.3.2</a> <a id="neg" href="#neg">The 'neg' operator</a></h3><p id="rfc.section.3.3.2.p.1">If all of the variables are un-defined or empty then substitute the value of arg, otherwise substitute the empty string.</p><h3 id="rfc.section.3.3.3"><a href="#rfc.section.3.3.3">3.3.3</a> <a id="prefix" href="#prefix">The 'prefix' operator</a></h3><p id="rfc.section.3.3.3.p.1">The prefix operator MUST only have one variable in its expansion. If the variable is defined and non-empty then substitute the value of arg followed by the value of the variable, otherwise substitute the empty string.</p><h3 id="rfc.section.3.3.4"><a href="#rfc.section.3.3.4">3.3.4</a> <a id="append" href="#append">The 'append' operator</a></h3><p id="rfc.section.3.3.4.p.1">The append operator MUST only have one variable in its expansion. If the variable is defined and non-empty then substitute the value of the variable followed by the value of arg, otherwise substitute the empty string.</p><h3 id="rfc.section.3.3.5"><a href="#rfc.section.3.3.5">3.3.5</a> <a id="join" href="#join">The 'join' operator</a></h3><p id="rfc.section.3.3.5.p.1">For each variable that is defined and non-empty create a keyvalue string that is the concatenation of the variable name, "=", and the variable value. Concatenate more than one keyvalue string with intervening values of arg to create the substitution value.</p><h3 id="rfc.section.3.3.6"><a href="#rfc.section.3.3.6">3.3.6</a> <a id="listjoin" href="#listjoin">The 'listjoin' operator</a></h3><p id="rfc.section.3.3.6.p.1">The listjoin operator MUST have only one variable in its expansion and that variable must be a list. If the list is non-empty then substitute the concatenation of all the list members with intevening values of arg.</p><p id="rfc.section.3.3.p.4">The result of substitution MUST match the URI-reference rule and SHOULD also match any known rules for the scheme of the resulting URI.</p><h2 id="rfc.section.3.4"><a href="#rfc.section.3.4">3.4</a> <a id="examples" href="#examples">Examples</a></h2><div id="rfc.table.1"><div id="example-table"></div><p>Given the following template variable names and values:</p><table summary="
Given the following template variable names and
values:
" class="tt full" cellpadding="3" cellspacing="0"><thead><tr><th class="left">Name</th><th class="left">Value</th></tr></thead><tbody><tr><td>a</td><td>foo</td></tr><tr><td>b</td><td>bar</td></tr><tr><td>data</td><td>10,20,30</td></tr><tr><td>points</td><td>["10","20", "30"]</td></tr><tr><td>list0</td><td>[]</td></tr><tr><td>str0</td><td></td></tr><tr><td>reserved</td><td>:/?#[]@!$&'()*+,;=</td></tr><tr><td>u</td><td>\u2654\u2655</td></tr><tr><td>a_b</td><td>baz</td></tr></tbody></table><p class="figure">Table 1</p></div><p id="rfc.section.3.4.p.1">The name 'foo' has not been defined, the value of 'str0' is the empty string, and both list0 and points are lists. The variable 'u' is a string of two unicode characters, the WHITE CHESS KING (0x2654) and the WHITE CHESS QUEEN (0x2655).</p><p id="rfc.section.3.4.p.2">The following URI Templates will be expanded as shown:</p><p id="rfc.section.3.4.p.3">----</p><div id="rfc.figure.u.8"></div> <pre>
http://example.org/?q={a}
http://example.org/?q=foo
http://example.org/{foo}
http://example.org/
relative/{reserved}/
relative/%3A%2F%3F%23%5B%5D%40%21%24%26%27%28%29%2A%2B%2C%3B%3D/
http://example.org/{foo=fred}
http://example.org/fred
http://example.org/{foo=%25}/
http://example.org/%25/
/{-prefix|#|foo}
/
./{-prefix|#|str0}
./
/{-append|/|a}{-opt|data|points}{-neg|@|a}{-prefix|#|b}
/foo/data#bar
http://example.org/q={u}
http://example.org/q=%E2%99%94%E2%99%95
http://example.org/?{-join|&|a,data}
http://example.org/?a=foo&data=10%2C20%2C30
http://example.org/?d={-listjoin|,|points}&{-join|&|a,b}
http://example.org/?d=10,20,30&a=foo&b=bar
http://example.org/?d={-listjoin|,|list0}&{-join|&|foo}
http://example.org/?d=&
http://example.org/?d={-listjoin|&d=|points}
http://example.org/?d=10&d=20&d=30
http://example.org/{a}{b}/{a_b}
http://example.org/foobar/baz
http://example.org/{a}{-prefix|/-/|a}/
http://example.org/foo/-/foo/
</pre> <p id="rfc.section.3.4.p.5">----</p><h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a> Security Considerations</h1><p id="rfc.section.4.p.1">A URI Template does not contain active or executable content. Other security considerations are the same as those for URIs, see section 7 of RFC3986.</p><h1 id="rfc.section.5"><a href="#rfc.section.5">5.</a> <a id="iana" href="#iana">IANA Considerations</a></h1><p id="rfc.section.5.p.1">In common with RFC3986, URI scheme names form a registered namespace that is managed by IANA according to the procedures defined in <a href="#RFC4395"><cite title="Guidelines and Registration Procedures for New URI Schemes">[RFC4395]</cite></a>. No IANA actions are required by this document.</p><h1 id="rfc.section.6"><a href="#rfc.section.6">6.</a> <a id="appendix_a" href="#appendix_a">Appendix A - Parsing URI Template Expansions</a></h1><p id="rfc.section.6.p.1">Parsing a valid URI Template expansion does not require building a parser from the given ABNF. Instead, the set of allowed characters in each part of URI Template expansion has been chosen to avoid complex parsing, and breaking an expansion into its component parts can be achieved by a series of splits of the character string.</p><p id="rfc.section.6.p.2">Here is example Python code that parses a URI Template expansion and returns the operator, argument, and variables as a tuple. The variables are returned as a dictionary of variable names mapped to their default values. If no default is given then the name maps to None.</p><div id="rfc.figure.u.9"></div><pre>
def parse_expansion(expansion):
if "|" in expansion:
(op, arg, vars_) = expansion.split("|")
op = op[1:]
else:
(op, arg, vars_) = (None, None, expansion)
vars_ = vars_.split(",")
variables = {}
for var in vars_:
if "=" in var:
(varname, vardefault) = var.split("=")
else:
(varname, vardefault) = (var, None)
variables[varname] = vardefault
return (op, arg, variables)
</pre><p id="rfc.section.6.p.4">And here is an example of the parse_expansion() function being used.</p><div id="rfc.figure.u.10"></div><pre>
>>> parse_expansion("-join|&|a,b,c=1")
('join', '&', {'a': None, 'c': '1', 'b': None})
>>> parse_expansion("c=1")
(None, None, {'c': '1'})
</pre><h1 id="rfc.references"><a href="#rfc.section.7">7.</a> Normative References</h1><table summary="Normative References" border="0" cellpadding="2"> <tr><td class="topnowrap"><b id="ASCII">[ASCII]</b></td><td class="top">American National Standards Institute, “Coded Character Set - 7-bit American Standard Code for Information Interchange”, ANSI X3.4, 1986.</td></tr><tr><td class="topnowrap"><b id="RFC2119">[RFC2119]</b></td><td class="top"><a href="mailto:sob@harvard.edu" title="Harvard University">Bradner, S.</a>, “<a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a>”, BCP 14, RFC 2119, March 1997.</td></tr><tr><td class="topnowrap"><b id="RFC2978">[RFC2978]</b></td><td class="top">Freed, N. and J. Postel, “<a href="http://tools.ietf.org/html/rfc2978">IANA Charset Registration Procedures</a>”, BCP 19, RFC 2978, October 2000.</td></tr><tr><td class="topnowrap"><b id="RFC3629">[RFC3629]</b></td><td class="top">Yergeau, F., “<a href="http://tools.ietf.org/html/rfc3629">UTF-8, a transformation format of ISO 10646</a>”, STD 63, RFC 3629, November 2003.</td></tr><tr><td class="topnowrap"><b id="RFC3986">[RFC3986]</b></td><td class="top">Berners-Lee, T., Fielding, R., and L. Masinter, “<a href="http://tools.ietf.org/html/rfc3986">Uniform Resource Identifier (URI): Generic Syntax</a>”, STD 66, RFC 3986, January 2005.</td></tr><tr><td class="topnowrap"><b id="RFC4234">[RFC4234]</b></td><td class="top"><a href="mailto:dcrocker@bbiw.net" title="Brandenburg InternetWorking">Crocker, D., Ed.</a> and <a href="mailto:paul.overell@thus.net" title="THUS plc.">P. Overell</a>, “<a href="http://tools.ietf.org/html/rfc4234">Augmented BNF for Syntax Specifications: ABNF</a>”, RFC 4234, October 2005.</td></tr><tr><td class="topnowrap"><b id="RFC4395">[RFC4395]</b></td><td class="top">Hansen, T., Hardie, T., and L. Masinter, “<a href="http://tools.ietf.org/html/rfc4395">Guidelines and Registration Procedures for New URI Schemes</a>”, BCP 115, RFC 4395, February 2006.</td></tr><tr><td class="topnowrap"><b id="UNIV4">[UNIV4]</b></td><td class="top">The Unicode Consortium, “The Unicode Standard, Version
4.0.1, defined by: The Unicode Standard, Version 4.0
(Reading, MA, Addison-Wesley, 2003. ISBN
0-321-18578-1), as amended by Unicode 4.0.1
(http://www.unicode.org/versions/Unicode4.0.1/)”, March 2004.</td></tr><tr><td class="topnowrap"><b id="UTR15">[UTR15]</b></td><td class="top">Davis, M. and M. Duerst, “ Unicode Normalization Forms
”, Unicode Standard Annex # 15, April 2003.</td></tr></table><h1 id="rfc.authors">Authors' Addresses</h1><address class="vcard"><span class="vcardline"><span class="fn">Joe Gregorio</span>
(editor)
<span class="n hidden"><span class="family-name">Gregorio</span><span class="given-name">Joe</span></span></span><span class="org vcardline">Google</span><span class="vcardline">EMail: <a href="mailto:joe@bitworking.org"><span class="email">joe@bitworking.org</span></a></span><span class="vcardline">URI: <a href="http://bitworking.org/" class="url">http://bitworking.org/</a></span></address><address class="vcard"><span class="vcardline"><span class="fn">Marc Hadley</span>
(editor)
<span class="n hidden"><span class="family-name">Hadley</span><span class="given-name">Marc</span></span></span><span class="org vcardline">Sun Microsystems</span><span class="vcardline">EMail: <a href="mailto:Marc.Hadley@sun.com"><span class="email">Marc.Hadley@sun.com</span></a></span><span class="vcardline">URI: <a href="http://sun.com/" class="url">http://sun.com/</a></span></address><address class="vcard"><span class="vcardline"><span class="fn">Mark Nottingham</span>
(editor)
<span class="n hidden"><span class="family-name">Nottingham</span><span class="given-name">Mark</span></span></span><span class="vcardline">EMail: <a href="mailto:mnot@pobox.com"><span class="email">mnot@pobox.com</span></a></span><span class="vcardline">URI: <a href="http://mnot.net/" class="url">http://mnot.net/</a></span></address><address class="vcard"><span class="vcardline"><span class="fn">David Orchard</span><span class="n hidden"><span class="family-name">Orchard</span><span class="given-name">David</span></span></span><span class="org vcardline">BEA Systems, Inc.</span><span class="vcardline">EMail: <a href="mailto:dorchard@bea.com"><span class="email">dorchard@bea.com</span></a></span><span class="vcardline">URI: <a href="http://bea.com/" class="url">http://bea.com/</a></span></address><h1 id="rfc.section.A"><a href="#rfc.section.A">A.</a> Contributors</h1><p id="rfc.section.A.p.1">The following people made significant contributions to this specification: DeWitt Clinton and James Snell.</p><h1 id="rfc.section.B"><a href="#rfc.section.B">B.</a> Revision History</h1><p id="rfc.section.B.p.1">02 - Added operators and came up with coherent percent-encoding and reserved character story. Added large examples section which is extracted and tested against the implementation.</p><p id="rfc.section.B.p.2">01</p><p id="rfc.section.B.p.3">00 - Initial Revision.</p><h1><a id="rfc.copyright" href="#rfc.copyright">Full Copyright Statement</a></h1><p>Copyright © The IETF Trust (2007).</p><p>This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.</p><p>This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</p><h1><a id="rfc.ipr" href="#rfc.ipr">Intellectual Property</a></h1><p>The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.</p><p>Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at <<a href="http://www.ietf.org/ipr">http://www.ietf.org/ipr</a>>.</p><p>The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at <a href="mailto:ietf-ipr@ietf.org">ietf-ipr@ietf.org</a>.</p><h1>Acknowledgement</h1><p>Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA).</p></body></html>