idnits 2.17.1 draft-gregorio-uritemplate-00.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 on line 342. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 314. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 321. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 327. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard 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 RFC 3978 Section 5.4 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 (October 28, 2006) is 6388 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 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2717 (Obsoleted by RFC 4395) -- Possible downref: Non-RFC (?) normative reference: ref. '1' Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 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 individual 4 Expires: May 1, 2007 M. Hadley, Ed. 5 Sun Microsystems 6 M. Nottingham 7 individual 8 D. Orchard 9 BEA Systems, Inc. 10 October 28, 2006 12 URI Template 13 draft-gregorio-uritemplate-00.txt 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 May 1, 2007. 40 Copyright Notice 42 Copyright (C) The Internet Society (2006). 44 Abstract 46 URI Templates are strings that can be transformed into URIs after 47 embedded variables are substituted. This document defines the 48 structure and syntax 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. Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 4. URI Template . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 4.1 Template Variables . . . . . . . . . . . . . . . . . . . . 4 62 4.2 URI Template Substitution . . . . . . . . . . . . . . . . 4 63 4.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 66 7. Normative References . . . . . . . . . . . . . . . . . . . . . 7 67 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 7 68 A. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 B. Revision History . . . . . . . . . . . . . . . . . . . . . . . 8 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. This 76 document defines the structure and syntax of URI Templates. 78 URI Templates are useful when it's necessary to convey the structure 79 of a URI in a well-defined way. For example, documentation of an 80 interface exposed by a Web site might use a template to show people 81 how to find information about a user; 83 http://www.example.com/users/{userid} 85 URI Templates can also be thought of as the basis of a machine- 86 readable forms language; by allowing clients to form their own 87 identifiers based on templates given to them by the URI's authority, 88 it's possible to construct dynamic systems that use more of the URI 89 than traditional HTML forms are able to. For example, 91 http://www.example.org/products/{upc}/buyers?page={page_num} 93 Finally, URI Templates can be used to compose URI-centric protocols 94 without impinging on authorities' control of their URIs. For 95 example, there are many emerging conventions for passing around login 96 information between sites using URIs. Forcing people to use a well- 97 known query parameter isn't good practice, but using a URI parameter 98 allows different sites to specify local ways of conveying the same 99 information; 101 http://login.example.org/login?back={return-uri} 102 http://auth.example.com/userauth;{return-uri} 104 This specification defines the basic syntax and processing of URI 105 Templates. Each application of URI Templates will need to define its 106 own profile of this specification that indicates what template 107 variables are available, how to convey them to clients, and what 108 their appropriate use is in that context. 110 2. Notational Conventions 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in [RFC2119]. 116 This specification uses the Augmented Backus-Naur Form (ABNF) 117 notation of [RFC2234]. See [RFC3986] for reserved and unreserved 118 productions. 120 3. Motivation 122 URI Templates are useful in a number of scenarios including web 123 service documentation and application code. A standard syntax and 124 well-defined substitution rules will improve interop. 126 4. URI Template 128 A URI Template is a sequence of characters that contains one or more 129 embedded template variables Section 4.1. A URI Template becomes a 130 URI when the template variables are substituted with the template 131 variables string values, see Section 4.2. The following shows an 132 example URI Template: 134 http://example.com/widgets/{widget_id} 136 If the value of the widget_id variable is "xyzzy", the resulting URI 137 after substitution is: 139 http://example.com/widgets/xyzzy 141 4.1 Template Variables 143 Template variables are the parameterized components of a URI 144 Template, their representation is described below. A template 145 variable MUST match the template-var production. 147 template-char = unreserved 148 template-name = 1*template-char 149 template-var = "{" template-name "}" 151 4.2 URI Template Substitution 153 Evaluating a URI Template consists of replacing each occurrence of a 154 template variable with the string value of that variable. Obtaining 155 the string value of a template variable is an application-specific 156 process, this specification places no constraints on the mechanism 157 employed. Template variables MAY appear in a URI Template any number 158 of times. 160 If the value of a template variable would conflict with a reserved 161 character's purpose as a delimiter, then the conflicting data must be 162 percent-encoded before substitution. That is, merely doing rote 163 substitution on template variables could result in the generation of 164 an invalid URI for a particular scheme. Specifications that use URI 165 Templates are expected to take this into consideration in how they 166 use such templates. 168 When the values of any template variables have been substituted into 169 a URI template, the resulting string MUST match the URI-reference 170 production of RFC 3986 and MUST also match the productions for the 171 scheme in the final URI. 173 This specification presumes that the value of a template variable 174 does not contain characters outside the allowed set for the 175 component(s) of the URI that it parameterizes. 177 4.3 Examples 179 Given the following template names and values 181 Name Value 182 ------------------------------------------------------------ 183 a fred 184 b barney 185 c cheeseburger 186 20 this-is-spinal-tap 187 a~b none%20of%20the%20above 188 schema https 189 p quote=to+bo+or+not+to+be 190 e 191 q hullo#world 193 Note that the name 'wilma' has not been defined, and the value of 'e' 194 is the empty string. 196 The following URI Templates will be expanded as shown: 198 http://example.org/{a}/{b}/ 199 http://example.org/fred/barney/ 201 http://example.org/{a}{b}/ 202 http://example.org/fredbarney/ 204 http://example.org/page1#{a} 205 http://example.org/page1#fred 207 {scheme}://{20}.example.org?date={wilma}&option={a} 208 https://this-is-spinal-tap.example.org?date=&option=fred 210 http://example.org/{a~b} 211 http://example.org/none%20of%20the%20above 213 http://example.org?{p} 214 http://example.org?quote=to+bo+or+not+to+be 216 http://example.com/order/{c}/{c}/{c}/ 217 http://example.com/order/cheeseburger/cheeseburger/cheeseburger/ 219 http://example.com/{q} 220 http://example.com/hullo#world 222 http://example.com/{e}/ 223 http://example.com// 225 The following are examples of URI Template expansions that are not 226 legal. 228 Name Value 229 ------------------------------------------------------------ 230 a fred barney 231 b % 233 The following URI Templates are expanded with the given values and do 234 not produce legal URIs. 236 http://example.org/{a} 237 http://example.org/fred barney 239 http://example.org/{b}/ 240 http://example.org/%/ 242 5. Security Considerations 244 A URI Template does not contain active or executable content. Other 245 security considerations are the same as those for URIs, see section 7 246 of RFC3986. 248 6. IANA Considerations 250 In common with RFC3986, URI scheme names form a registered namespace 251 that is managed by IANA according to the procedures defined in 252 [RFC2717]. No IANA actions are required by this document. 254 7. Normative References 256 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 257 Requirement Levels", BCP 14, RFC 2119, March 1997. 259 [RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 260 Specifications: ABNF", RFC 2234, November 1997. 262 [RFC2717] Petke, R. and I. King, "Registration Procedures for URL 263 Scheme Names", BCP 35, RFC 2717, November 1999. 265 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 266 Resource Identifier (URI): Generic Syntax", STD 66, 267 RFC 3986, January 2005. 269 [1] 271 Authors' Addresses 273 Joe Gregorio (editor) 274 individual 276 Email: joe@bitworking.org 277 URI: http://bitworking.org/ 279 Marc Hadley (editor) 280 Sun Microsystems 282 Email: Marc.Hadley@sun.com 283 URI: http://sun.com/ 284 Mark Nottingham 285 individual 287 Email: mnot@pobox.com 288 URI: http://mnot.net/ 290 David Orchard 291 BEA Systems, Inc. 293 Email: dorchard@bea.com 294 URI: http://bea.com/ 296 Appendix A. Contributors 298 The following people made significant contributions to this 299 specification: DeWitt Clinton and James Snell. 301 Appendix B. Revision History 303 00 - Initial Revision. 305 Intellectual Property Statement 307 The IETF takes no position regarding the validity or scope of any 308 Intellectual Property Rights or other rights that might be claimed to 309 pertain to the implementation or use of the technology described in 310 this document or the extent to which any license under such rights 311 might or might not be available; nor does it represent that it has 312 made any independent effort to identify any such rights. Information 313 on the procedures with respect to rights in RFC documents can be 314 found in BCP 78 and BCP 79. 316 Copies of IPR disclosures made to the IETF Secretariat and any 317 assurances of licenses to be made available, or the result of an 318 attempt made to obtain a general license or permission for the use of 319 such proprietary rights by implementers or users of this 320 specification can be obtained from the IETF on-line IPR repository at 321 http://www.ietf.org/ipr. 323 The IETF invites any interested party to bring to its attention any 324 copyrights, patents or patent applications, or other proprietary 325 rights that may cover technology that may be required to implement 326 this standard. Please address the information to the IETF at 327 ietf-ipr@ietf.org. 329 The IETF has been notified of intellectual property rights claimed in 330 regard to some or all of the specification contained in this 331 document. For more information consult the online list of claimed 332 rights. 334 Disclaimer of Validity 336 This document and the information contained herein are provided on an 337 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 338 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 339 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 340 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 341 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 342 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 344 Copyright Statement 346 Copyright (C) The Internet Society (2006). This document is subject 347 to the rights, licenses and restrictions contained in BCP 78, and 348 except as set forth therein, the authors retain all their rights. 350 Acknowledgment 352 Funding for the RFC Editor function is currently provided by the 353 Internet Society.