idnits 2.17.1 draft-ietf-appsawg-uri-get-off-my-lawn-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC3986, but the abstract doesn't seem to directly say this. It does mention RFC3986 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC3986, updated by this document, for RFC5378 checks: 2002-11-01) -- 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 (May 21, 2014) is 3621 days in the past. Is this intentional? Checking references for intended status: Best Current Practice ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Obsolete informational reference (is this intentional?): RFC 4395 (ref. 'BCP115') (Obsoleted by RFC 7595) -- Obsolete informational reference (is this intentional?): RFC 5785 (Obsoleted by RFC 8615) -- Obsolete informational reference (is this intentional?): RFC 5988 (Obsoleted by RFC 8288) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 appsawg M. Nottingham 3 Internet-Draft 4 Updates: 3986 (if approved) May 21, 2014 5 Intended status: Best Current Practice 6 Expires: November 22, 2014 8 URI Design and Ownership 9 draft-ietf-appsawg-uri-get-off-my-lawn-05 11 Abstract 13 RFC3986 Section 1.1.1 defines URI syntax as "a federated and 14 extensible naming system wherein each scheme's specification may 15 further restrict the syntax and semantics of identifiers using that 16 scheme." In other words, the structure of a URI is defined by its 17 scheme. While it is common for schemes to further delegate their 18 substructure to the URI's owner, publishing independent standards 19 that mandate particular forms of URI substructure is inappropriate, 20 because that essentially usurps ownership. This document further 21 describes this problematic practice and provides some acceptable 22 alternatives for use in standards. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on November 22, 2014. 41 Copyright Notice 43 Copyright (c) 2014 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Who This Document Is For . . . . . . . . . . . . . . . . 3 60 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4 61 2. Best Current Practices for Standardizing Structured URIs . . 4 62 2.1. URI Schemes . . . . . . . . . . . . . . . . . . . . . . . 4 63 2.2. URI Authorities . . . . . . . . . . . . . . . . . . . . . 5 64 2.3. URI Paths . . . . . . . . . . . . . . . . . . . . . . . . 5 65 2.4. URI Queries . . . . . . . . . . . . . . . . . . . . . . . 5 66 2.5. URI Fragment Identifiers . . . . . . . . . . . . . . . . 6 67 3. Alternatives to Specifying Structure in URIs . . . . . . . . 6 68 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 72 6.2. Informative References . . . . . . . . . . . . . . . . . 8 73 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 8 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 76 1. Introduction 78 URIs [RFC3986] very often include structured application data. This 79 might include artifacts from filesystems (often occurring in the path 80 component), and user information (often in the query component). In 81 some cases, there can even be application-specific data in the 82 authority component (e.g., some applications are spread across 83 several hostnames to enable a form of partitioning or dispatch). 85 Furthermore, constraints upon the structure of URIs can be imposed by 86 an implementation; for example, many Web servers use the filename 87 extension of the last path segment to determine the media type of the 88 response. Likewise, pre-packaged applications often have highly 89 structured URIs that can only be changed in limited ways (often, just 90 the hostname and port they are deployed upon). 92 Because the owner of the URI (as defined in [webarch] 93 Section 2.2.2.1) is choosing to use the server or the application, 94 this can be seen as reasonable delegation of authority. When such 95 conventions are mandated by a party other than the owner, however, it 96 can have several potentially detrimental effects: 98 o Collisions - As more ad hoc conventions for URI structure become 99 standardized, it becomes more likely that there will be collisions 100 between them (especially considering that servers, applications 101 and individual deployments will have their own conventions). 103 o Dilution - When the information added to a URI is ephemeral, this 104 dilutes its utility by reducing its stability (see [webarch] 105 Section 3.5.1), and can cause several alternate forms of the URI 106 to exist (see [webarch] Section 2.3.1). 108 o Rigidity - Fixed URI syntax often interferes with desired 109 deployment patterns. For example, if an authority wishes to offer 110 several applications on a single hostname, it becomes difficult to 111 impossible to do if their URIs do not allow the required 112 flexibility. 114 o Operational Difficulty - Supporting some URI conventions can be 115 difficult in some implementations. For example, specifying that a 116 particular query parameter be used with "HTTP" URIs precludes the 117 use of Web servers that serve the response from a filesystem. 118 Likewise, an application that fixes a base path for its operation 119 (e.g., "/v1") makes it impossible to deploy other applications 120 with the same prefix on the same host. 122 o Client Assumptions - When conventions are standardized, some 123 clients will inevitably assume that the standards are in use when 124 those conventions are seen. This can lead to interoperability 125 problems; for example, if a specification documents that the "sig" 126 URI query parameter indicates that its payload is a cryptographic 127 signature for the URI, it can lead to undesirable behavior. 129 Publishing a standard that constrains an existing URI structure in 130 ways which aren't explicitly allowed by [RFC3986] (usually, by 131 updating the URI scheme definition) is inappropriate, because the 132 structure of a URI needs to be firmly under the control of its owner, 133 and the IETF (as well as other organizations) should not usurp it. 135 This document explains some best current practices for establishing 136 URI structures, conventions and formats in standards. It also offers 137 strategies for specifications to avoid violating these guidelines in 138 Section 3. 140 1.1. Who This Document Is For 142 This document's requirements target the authors of specifications 143 that constrain the syntax or structure of URIs or parts of them. Two 144 classes of such specifications are called out specifically: 146 o Protocol Extensions ("extensions") - specifications that offer new 147 capabilities that could apply to any identifier, or to a large 148 subset of possible identifiers; e.g., a new signature mechanism 149 for 'http' URIs, or metadata for any URI. 151 o Applications Using URIs ("applications") - specifications that use 152 URIs to meet specific needs; e.g., a HTTP interface to particular 153 information on a host. 155 Requirements that target the generic class "Specifications" apply to 156 all specifications, including both those enumerated above and others. 158 Note that this specification ought not be interpreted as preventing 159 the allocation of control of URIs by parties that legitimately own 160 them, or have delegated that ownership; for example, a specification 161 might legitimately define the semantics of a URI on the IANA.ORG Web 162 site as part of the establishment of a registry. 164 There may be existing IETF specifications that already deviate from 165 the guidance in this document. In these cases, it is up to the 166 relevant communities (i.e. those of the URI scheme as well as that 167 which produced the specification in question) to determine an 168 appropriate outcome; e.g., updating the scheme definition, or 169 changing the specification. 171 1.2. Notational Conventions 173 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 174 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 175 document are to be interpreted as described in [RFC2119]. 177 2. Best Current Practices for Standardizing Structured URIs 179 This section updates [RFC3986] by setting limitations on how other 180 specifications may define structure and semantics within URIs. Best 181 practices differ depending on the URI component, as described below. 183 2.1. URI Schemes 185 Applications and extensions MAY require use of specific URI 186 scheme(s); for example, it is perfectly acceptable to require that an 187 application support 'http' and 'https' URIs. However, applications 188 SHOULD NOT preclude the use of other URI schemes in the future, 189 unless they are clearly only usable with the nominated schemes. 191 A specification that defines substructure within a specific URI 192 scheme MUST do so in the defining document for that URI scheme. A 193 specification that defines substructure for URI schemes overall MUST 194 do so by modifying [BCP115] (an exceptional circumstance). 196 2.2. URI Authorities 198 Scheme definitions define the presence, format and semantics of an 199 authority component in URIs; all other specifications MUST NOT 200 constrain, or define the structure or the semantics for URI 201 authorities, unless they update the scheme registration itself. 203 For example, an extension or application ought not say that the "foo" 204 prefix in "foo_app.example.com" is meaningful or triggers special 205 handling in URIs. 207 However, applications MAY nominate or constrain the port they use, 208 when applicable. For example, BarApp could run over port nnnn 209 (provided that it is properly registred). 211 2.3. URI Paths 213 Scheme definitions define the presence, format, and semantics of a 214 path component in URIs; all other specifications MUST NOT constrain, 215 or define the structure or the semantics for any path component. 217 The only exception to this requirement is registered "well-known" 218 URIs, as specified by [RFC5785]. See that document for a description 219 of the applicability of that mechanism. 221 For example, an application ought not specify a fixed URI path "/ 222 myapp", since this usurps the host's control of that space. 224 Specifying a fixed path relative to another (e.g., {whatever}/myapp) 225 is also bad practice (even if "whatever" is discovered as suggested 226 in Section 3); while doing so might prevent collisions, it does not 227 avoid the potential for operational difficulties (for example, an 228 implementation that prefers to use query processing instead, because 229 of implementation constraints). 231 2.4. URI Queries 233 The presence, format and semantics of the query component of URIs is 234 dependent upon many factors, and MAY be constrained by a scheme 235 definition. Often, they are determined by the implementation of a 236 resource itself. 238 Applications MUST NOT directly specify the syntax of queries, as this 239 can cause operational difficulties for deployments that do not 240 support a particular form of a query. For example, a site may wish 241 to support an application using "static" files that do not support 242 query parameters. 244 Extensions MUST NOT constrain the format or semantics of queries. 246 For example, an extension that indicates that all query parameters 247 with the name "sig" indicate a cryptographic signature would collide 248 with potentially pre-existing query parameters on sites, and lead 249 clients to assume that any matching query parameter is a signature. 251 HTML [W3C.REC-html401-19991224] constrains the syntax of query 252 strings used in form submission. New form languages SHOULD NOT 253 emulate it, but instead allow creation of a broader variety of URIs 254 (e.g., by allowing the form to create new path components, and so 255 forth). 257 Note that "well-known" URIs (see [RFC5785]) MAY constrain their own 258 query syntax, since these name spaces are effectively delegated to 259 the registering party. 261 2.5. URI Fragment Identifiers 263 Media type definitions (as per [RFC6838]) SHOULD specify the fragment 264 identifier syntax(es) to be used with them; other specifications MUST 265 NOT define structure within the fragment identifier, unless they are 266 explicitly defining one for reuse by media type definitions. 268 For example, an application that defines common fragment identifiers 269 across media types not controlled by it would engender 270 interoperability problems with handlers for those media types 271 (because the new, non-standard syntax is not expected). 273 3. Alternatives to Specifying Structure in URIs 275 Given the issues described in Section 1, the most successful strategy 276 for applications and extensions that wish to use URIs is to use them 277 in the fashion they were designed: as links that are exchanged as 278 part of the protocol, rather than statically specified syntax. 279 Several existing specifications can aid in this. 281 [RFC5988] specifies relation types for Web links. By providing a 282 framework for linking on the Web, where every link has a relation 283 type, context and target, it allows applications to define a link's 284 semantics and connectivity. 286 [RFC6570] provides a standard syntax for URI Templates that can be 287 used to dynamically insert application-specific variables into a URI 288 to enable such applications while avoiding impinging upon URI owners' 289 control of them. 291 [RFC5785] allows specific paths to be 'reserved' for standard use on 292 URI schemes that opt into that mechanism ('http' and 'https' by 293 default). Note, however, that this is not a general "escape valve" 294 for applications that need structured URIs; see that specification 295 for more information. 297 Specifying more elaborate structures in an attempt to avoid 298 collisions is not an acceptable solution, and does not address the 299 issues in Section 1. For example, prefixing query parameters with 300 "myapp_" does not help, because the prefix itself is subject to the 301 risk of collision (since it is not "reserved"). 303 4. Security Considerations 305 This document does not introduce new protocol artifacts with security 306 considerations. It prohibits some practices that might lead to 307 vulnerabilities; for example, if a security-sensitive mechanism is 308 introduced by assuming that a URI path component or query string has 309 a particular meaning, false positives might be encountered (due to 310 sites that already use the chosen string). See also [RFC6943]. 312 5. IANA Considerations 314 There are no direct IANA actions specified in this document. 316 6. References 318 6.1. Normative References 320 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 321 Requirement Levels", BCP 14, RFC 2119, March 1997. 323 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 324 Resource Identifier (URI): Generic Syntax", STD 66, RFC 325 3986, January 2005. 327 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 328 Specifications and Registration Procedures", BCP 13, RFC 329 6838, January 2013. 331 [webarch] Jacobs, I. and N. Walsh, "Architecture of the World Wide 332 Web, Volume One", December 2004, 333 . 335 6.2. Informative References 337 [BCP115] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and 338 Registration Procedures for New URI Schemes", RFC 4395, 339 BCP 115, February 2006, . 342 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 343 Uniform Resource Identifiers (URIs)", RFC 5785, April 344 2010. 346 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 348 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 349 and D. Orchard, "URI Template", RFC 6570, March 2012. 351 [RFC6943] Thaler, D., "Issues in Identifier Comparison for Security 352 Purposes", RFC 6943, May 2013. 354 [W3C.REC-html401-19991224] 355 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 356 Specification", World Wide Web Consortium Recommendation 357 REC-html401-19991224, December 1999, 358 . 360 Appendix A. Acknowledgments 362 Thanks to David Booth, Dave Crocker, Tim Bray, Anne van Kesteren, 363 Martin Thomson, Erik Wilde, Dave Thaler and Barry Leiba for their 364 suggestions and feedback. 366 Author's Address 368 Mark Nottingham 370 Email: mnot@mnot.net 371 URI: http://www.mnot.net/