idnits 2.17.1 draft-gregorio-uritemplate-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 20. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 323. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 334. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 341. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 347. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- 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 (July 9, 2007) is 6135 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 4234 (Obsoleted by RFC 5234) ** Obsolete normative reference: RFC 4395 (Obsoleted by RFC 7595) -- Possible downref: Non-RFC (?) normative reference: ref. '1' Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Gregorio, Ed. 3 Internet-Draft 4 Intended status: Standards Track M. Hadley, Ed. 5 Expires: January 10, 2008 Sun Microsystems 6 M. Nottingham, Ed. 8 D. Orchard 9 BEA Systems, Inc. 10 July 9, 2007 12 URI Template 13 draft-gregorio-uritemplate-01 15 Status of this Memo 17 By submitting this Internet-Draft, each author represents that any 18 applicable patent or other IPR claims of which he or she is aware 19 have been or will be disclosed, and any of which he or she becomes 20 aware will be disclosed, in accordance with Section 6 of BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF), its areas, and its working groups. Note that 24 other groups may also distribute working documents as Internet- 25 Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt. 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 This Internet-Draft will expire on January 10, 2008. 40 Copyright Notice 42 Copyright (C) The IETF Trust (2007). 44 Abstract 46 URI Templates are strings that can be transformed into URIs after 47 embedded variables are substituted. This document defines the syntax 48 and processing of URI Templates. 50 Editorial Note 52 To provide feedback on this Internet-Draft, join the W3C URI mailing 53 list (http://lists.w3.org/Archives/Public/uri/) [1]. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 3 59 3. URI Template . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.1. Template Variables . . . . . . . . . . . . . . . . . . . . 4 61 3.2. URI Template Substitution . . . . . . . . . . . . . . . . . 4 62 3.3. Using URI Templates . . . . . . . . . . . . . . . . . . . . 5 63 3.3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 5 64 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 65 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 66 6. Normative References . . . . . . . . . . . . . . . . . . . . . 7 67 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . . 7 68 Appendix B. Revision History . . . . . . . . . . . . . . . . . . . 7 69 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 70 Intellectual Property and Copyright Statements . . . . . . . . . . 9 72 1. Introduction 74 URI Templates are strings that contain embedded variables that are 75 transformed into URIs after embedded variables are substituted. 77 This is useful when it's necessary to convey the structure of a URI 78 in a well-defined way. For example, documentation of an interface 79 exposed by a Web site might use a template to show people how to find 80 information about a user; 82 http://www.example.com/users/{userid} 84 URI Templates can also be thought of as the basis of a machine- 85 readable forms language; by allowing clients to form their own 86 identifiers based on templates given to them by the URI's authority, 87 it's possible to construct dynamic systems that use more of the URI 88 than traditional HTML forms are able to. For example, 90 http://www.example.org/products/{upc}/buyers?page={page_num} 92 Finally, URI Templates can be used to compose URI-centric protocols 93 without impinging on authorities' control of their URIs. For 94 example, there are many emerging conventions for passing around login 95 information between sites using URIs. Forcing people to use a well- 96 known query parameter isn't good practice, but using a URI parameter 97 allows different sites to specify local ways of conveying the same 98 information; 100 http://login.example.org/login?back={return-uri} 101 http://auth.example.com/userauth;{return-uri} 103 This specification defines the basic syntax and processing of URI 104 Templates. Each application of URI Templates will need to define its 105 own profile of this specification that indicates what template 106 variables are available, how to convey them to clients, and what 107 their appropriate use is in that context. 109 2. Notational Conventions 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in [RFC2119]. 115 This specification uses the Augmented Backus-Naur Form (ABNF) 116 notation of [RFC4234]. See [RFC3986] for the definitions of the URI- 117 reference, reserved, and unreserved rules. 119 3. URI Template 121 A URI Template is a sequence of characters that contains one or more 122 embedded template variables, see Section 3.1. A URI Template becomes 123 a URI when the template variables are substituted with their values 124 (see Section 3.2). For example: 126 http://example.com/widgets/{widget_id} 128 If the value of the widget_id variable is "xyzzy", the resulting URI 129 after substitution is: 131 http://example.com/widgets/xyzzy 133 3.1. Template Variables 135 Template variables are the parameterized components of a URI 136 Template. A template variable MUST match the template-var rule. 138 template-char = unreserved 139 template-name = 1*template-char 140 template-var = "{" template-name "}" 142 3.2. URI Template Substitution 144 Evaluating a URI Template ("substitution") consists of replacing all 145 template variables with their respective string values. 147 During substitution, the string value of a template variable MUST 148 have any characters that do not match the reserved or unreserved 149 rules (i.e., those characters not legal in URIs without percent 150 encoding) percent-encoded, as per [RFC3986], section 2.1. Specific 151 applications of URI Templates MAY specify additional constraints and 152 encoding rules in addition to this. 154 Any number of template variables MAY appear in a URI Template; a 155 single template-name MAY appear multiple times. 157 The result of substitution MUST match the URI-reference rule and 158 SHOULD also match any known rules for the scheme of the resulting 159 URI. 161 Typically, this is ensured by the definitions of the template 162 variables used. For example, they may specify that a variable's 163 value is not to contain certain characters, or that some characters 164 should be percent-encoded before substitution. 166 3.3. Using URI Templates 168 Applications using URI Templates will typically need to specify a 169 number of things, including; 171 o The template to use. 172 o What template variables are available. 173 o For each of the variables; 174 * What characters are allowed in the template's value. 175 * What encodings should be applied to the value before 176 substitutions. 177 * How to handle errors such as the output of substitution being 178 an invalid URI. 180 URI Template processors SHOULD allow applications to indicate that; 182 o A variable's value is required to contain at least one character 183 o A variable's value is required to match one of a set of supplied 184 options 185 o A variable's value is to have all reserved characters, as per 186 RFC3986, percent-escaped before substitution 188 Processors MAY make additional options available. 190 3.3.1. Examples 192 Given the following template names and values: 194 +--------+--------------------------+ 195 | Name | Value | 196 +--------+--------------------------+ 197 | a | fred | 198 | b | barney | 199 | c | cheeseburger | 200 | d | one two three | 201 | e | 20% tricky | 202 | f | | 203 | 20 | this-is-spinal-tap | 204 | scheme | https | 205 | p | quote=to+be+or+not+to+be | 206 | q | hullo#world | 207 +--------+--------------------------+ 209 Table 1 211 (Note that the name 'wilma' has not been defined, and the value of 212 'f' is the empty string.) 213 The following URI Templates will be expanded as shown: 215 http://example.org/page1#{a} 216 http://example.org/page1#fred 218 http://example.org/{a}/{b}/ 219 http://example.org/fred/barney/ 221 http://example.org/{a}{b}/ 222 http://example.org/fredbarney/ 224 http://example.com/order/{c}/{c}/{c}/ 225 http://example.com/order/cheeseburger/cheeseburger/cheeseburger/ 227 http://example.org/{d} 228 http://example.org/one%20two%20three 230 http://example.org/{e} 231 http://example.org/20%25%20tricky 233 http://example.com/{f}/ 234 http://example.com// 236 {scheme}://{20}.example.org?date={wilma}&option={a} 237 https://this-is-spinal-tap.example.org?date=&option=fred 239 http://example.org?{p} 240 http://example.org?quote=to+be+or+not+to+be 242 http://example.com/{q} 243 http://example.com/hullo#world 245 4. Security Considerations 247 A URI Template does not contain active or executable content. Other 248 security considerations are the same as those for URIs, see section 7 249 of RFC3986. 251 5. IANA Considerations 253 In common with RFC3986, URI scheme names form a registered namespace 254 that is managed by IANA according to the procedures defined in 255 [RFC4395]. No IANA actions are required by this document. 257 6. Normative References 259 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 260 Requirement Levels", BCP 14, RFC 2119, March 1997. 262 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 263 Resource Identifier (URI): Generic Syntax", STD 66, 264 RFC 3986, January 2005. 266 [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 267 Specifications: ABNF", RFC 4234, October 2005. 269 [RFC4395] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 270 Registration Procedures for New URI Schemes", BCP 115, 271 RFC 4395, February 2006. 273 [1] 275 Appendix A. Contributors 277 The following people made significant contributions to this 278 specification: DeWitt Clinton and James Snell. 280 Appendix B. Revision History 282 01 284 00 - Initial Revision. 286 Authors' Addresses 288 Joe Gregorio (editor) 290 Email: joe@bitworking.org 291 URI: http://bitworking.org/ 293 Marc Hadley (editor) 294 Sun Microsystems 296 Email: Marc.Hadley@sun.com 297 URI: http://sun.com/ 298 Mark Nottingham (editor) 300 Email: mnot@pobox.com 301 URI: http://mnot.net/ 303 David Orchard 304 BEA Systems, Inc. 306 Email: dorchard@bea.com 307 URI: http://bea.com/ 309 Full Copyright Statement 311 Copyright (C) The IETF Trust (2007). 313 This document is subject to the rights, licenses and restrictions 314 contained in BCP 78, and except as set forth therein, the authors 315 retain all their rights. 317 This document and the information contained herein are provided on an 318 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 319 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 320 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 321 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 322 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 323 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 325 Intellectual Property 327 The IETF takes no position regarding the validity or scope of any 328 Intellectual Property Rights or other rights that might be claimed to 329 pertain to the implementation or use of the technology described in 330 this document or the extent to which any license under such rights 331 might or might not be available; nor does it represent that it has 332 made any independent effort to identify any such rights. Information 333 on the procedures with respect to rights in RFC documents can be 334 found in BCP 78 and BCP 79. 336 Copies of IPR disclosures made to the IETF Secretariat and any 337 assurances of licenses to be made available, or the result of an 338 attempt made to obtain a general license or permission for the use of 339 such proprietary rights by implementers or users of this 340 specification can be obtained from the IETF on-line IPR repository at 341 http://www.ietf.org/ipr. 343 The IETF invites any interested party to bring to its attention any 344 copyrights, patents or patent applications, or other proprietary 345 rights that may cover technology that may be required to implement 346 this standard. Please address the information to the IETF at 347 ietf-ipr@ietf.org. 349 Acknowledgment 351 Funding for the RFC Editor function is provided by the IETF 352 Administrative Support Activity (IASA).