idnits 2.17.1 draft-wilde-template-desc-00.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 abstract seems to contain references ([9]), 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 and authors Copyright Line does not match the current year -- The document date (December 7, 2012) is 4156 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) == Unused Reference: '7' is defined on line 346, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '2' -- Possible downref: Non-RFC (?) normative reference: ref. '3' -- Possible downref: Non-RFC (?) normative reference: ref. '4' ** Obsolete normative reference: RFC 5988 (ref. '6') (Obsoleted by RFC 8288) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft C. Davis 4 Intended status: Standards Track EMC Corporation 5 Expires: June 10, 2013 Y. Liu 6 UC Berkeley 7 December 7, 2012 9 URI Template Descriptions 10 draft-wilde-template-desc-00 12 Abstract 14 Interactions with many resources on the Web are driven by and/or can 15 be described by URI Templates. RFC 6570 says that "a URI Template is 16 a compact sequence of characters for describing a range of Uniform 17 Resource Identifiers through variable expansion." This specification 18 defines Template Descriptions, a schema and a media type that can be 19 used to document and describe a URI Template by supporting 20 descriptive markup that allows variables to be associated with 21 documentation (human-oriented) and/or descriptions (machine- 22 oriented). Template Descriptions can be used by media types (by 23 inclusion or by reference) that seek to make URI Templates self- 24 describing, without having to create their own representation. 26 Note to Readers 28 Please discuss this draft on the rest-discuss mailing list [9]. 30 Status of this Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on June 10, 2013. 47 Copyright Notice 48 Copyright (c) 2012 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. URI Template . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.2. Describing Variables . . . . . . . . . . . . . . . . . . . 4 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. Template Descriptions . . . . . . . . . . . . . . . . . . . . . 5 68 3.1. General Concepts . . . . . . . . . . . . . . . . . . . . . 5 69 3.2. Template Description Structure . . . . . . . . . . . . . . 5 70 3.3. Variable Description Structure . . . . . . . . . . . . . . 5 71 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 72 4.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . . 5 73 4.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . . 6 74 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 75 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 76 6.1. OpenSearch . . . . . . . . . . . . . . . . . . . . . . . . 7 77 6.2. Atom Feeds . . . . . . . . . . . . . . . . . . . . . . . . 7 78 7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . . 7 79 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 80 8.1. Normative References . . . . . . . . . . . . . . . . . . . 8 81 8.2. Informative References . . . . . . . . . . . . . . . . . . 8 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 8 84 1. Introduction 86 Simple interactions with resources on the Web often are driven by 87 simply following links, but in many other cases, interactions with 88 resources require clients to provide information in addition to just 89 using a fixed URI in a request. In these cases, information can 90 provided in any way supported by the interaction protocol, and in 91 case of HTTP, this often means that information is either embedded in 92 the URI, and/or in the body of the request. For the first case, the 93 "URI Template" standard Section 1.1 provides a standard that allows 94 servers and clients to exchange information about the URIs that a 95 service accepts. 97 1.1. URI Template 99 The "URI Template" standard RFC 6570 [1] specifies "a compact 100 sequence of characters for describing a range of Uniform Resource 101 Identifiers through variable expansion." It allows servers to 102 publish their expectation how a URI should be created by substituting 103 variables with values. Consider the following URI Template: 104 http://www.example.com/feed{?pagesize,page} 106 This URI Template allows clients to expand two variables to end up 107 with a concrete URI such as the following: 108 http://www.example.com/feed?pagesize=10&page=42 110 URI Templates cover the aspect of starting with a template with 111 variables in it, assigning values to these variables, and then 112 expanding the template into a URI that can be used for sending a 113 request. URI Templates make no assumptions or statements about the 114 value range of the variables, except for those aspects which are 115 required to cover the process of expanding the template. In 116 particular, for the example given above, there is no indication that 117 the values are supposed to be positive integers (the simple data 118 type), nor is there any indication that the service may apply certain 119 limits such as a maximum page size (which may change depending on 120 which paged resource is being accessed). As a side note, even if 121 this information was known, URI template expansion could still result 122 in URIs that would not yield successful requests, such as when asking 123 for a page that is beyond the number of pages that a feed has (in a 124 given page size). 126 The goal of Templates Descriptions as defined here is to allow 127 servers to expose a description resource that provides support both 128 at development time (when a developer looks at a media type that uses 129 URI Templates) and at runtime (when a client wants to use a URI 130 template as part of its application flow). 132 1.2. Describing Variables 134 Variables can be described in a variety of ways when using Template 135 Descriptions. For each variable in the URI Template, it is possible 136 to use the following description methods: 138 Domain Concept: It is possible to associate a variable with a 139 domain concept, so that media types and applications can make an 140 association between the concepts they are defining/exposing, and 141 where they are represented in URI Tenplates. Concepts can be 142 referred to by URI, or by using a QName [2]. 144 Datatype: Variables can be described in terms of using certain 145 datatypes, and the datatype vocabulary is that of XML Schema Part 146 2 [3], plus all of the applicable facets of those datatypes. This 147 allows Template Descriptions to constrain the set of allowed 148 values. 150 Documentation: Documentation constructs can be associated with 151 variables, which allows Template Descriptions to attach human- 152 readable information to individual variables. The documentation 153 constructs use the documentation design of XML Schema Part 1 [4]. 155 Application Information: Application information constructs can be 156 associated with variables, which allows Template Descriptions to 157 attach machine-readable information to individual variables. The 158 application information constructs use the application information 159 design of XML Schema Part 1 [4]. 161 For the purpose of this specification, the term "description" should 162 be interpreted loosely. Some aspects of descriptions can be formal, 163 such as the datatypes of variables. Thus, such a description can be 164 used to drive general-purpose logic that knows nothing but this 165 specification. However, for most other description aspects (domain 166 concepts, documentation, and application information), this 167 specification does not prescribe a description framework; it simply 168 provides a structure how to deliver these descriptions. 170 2. Terminology 172 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 173 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 174 document are to be interpreted as described in RFC 2119 [5]. 176 3. Template Descriptions 178 Template Descriptions are based on a URI Template, and add 179 descriptive elements that allow publishers of URI Templates to 180 describe the URI Template as a whole, and to add individual 181 descriptions of all variables in the template. 183 3.1. General Concepts 185 As mentioned in Section 1.1, most of the descriptions in this spec to 186 not prescribe a specific description framework. While variables 187 (Section 3.3) can be described with a built-in vocabulary of 188 datatypes, most other descriptions are either for human consumption, 189 or do rely on some external description framework. To attach these 190 descriptions to both the template as a whole, and individual 191 variables, this specification reuses the "appinfo" and 192 "documentation" elements from XML Schema Part 1 [4]. These elements 193 carry a "source" attribute which is used (quoting from [4]) "to 194 supplement the local information." 196 3.2. Template Description Structure 198 A template is described by including the URI Template itself, and 199 optionally adding documentation and/or appinfo elements to add human- 200 or machine-readable descriptions. 202 3.3. Variable Description Structure 204 A variable is described by specifying the variable name. Variables 205 can refer to a "concept" associated with a variable, which can by 206 identified by URI, or by a QName (at most one of these SHALL be 207 present). This specification makes no provision how such a concept 208 is defined or described, but it allows consumers of a Template 209 Description to match their understanding of certain concepts to those 210 identifiers, which then establishes a binding between the concept, 211 and the variable it has been bound to. 213 Variable descriptions can optionally add documentation and/or appinfo 214 elements to add human- or machine-readable descriptions. 216 4. IANA Considerations 218 4.1. Media Type 220 The Internet media type for a Template Description document is 221 application/td+xml. 223 Type name: application 225 Subtype name: td+xml 227 Required parameters: none 229 Optional parameters: none 231 Encoding considerations: binary 233 Security considerations: See Security Considerations in Section 5. 235 Interoperability considerations: N/A 237 Published specification: [[ This document ]] 239 Applications that use this media type: Applications that publish 240 descriptions of URI Templates. 242 Additional information: 244 Magic number(s): N/A 246 File extension(s): .tdx 248 Macintosh file type code(s): TEXT 250 Person & email address to contact for further information: Erik 251 Wilde 253 Intended usage: COMMON 255 Restrictions on usage: none 257 Author: Erik Wilde 259 Change controller: IETF 261 4.2. Link Relation 263 The link relation type below will be registered by IANA per Section 264 6.2.1 of RFC 5988 [6]: 266 Relation Name: query-template 268 Description: Linking to a resource that can be used as a template 269 description for creating a request URI for the context resource. 271 Reference: [[ This document ]] 273 Notes: Template Descriptions can be used in all scenarios where 274 clients want to create requests that represent a query into the 275 context resource. The media type of the context resource and the 276 media type of the template description resource are not 277 constrained by this specification. 279 5. Security Considerations 281 ... 283 6. Examples 285 ... 287 6.1. OpenSearch 289 ... 291 6.2. Atom Feeds 293 ... 295 "Feed Paging and Archiving" specified in RFC 5005 [8] 297 Maybe suggest to use profiles? 299 7. Open Issues 301 If and how to use profiles (example in Section 6); if profile use 302 is recommended, define a suggested profile URI for other specs to 303 use? 305 Should we support other ways how URIs could be generated, most 306 importantly the application/x-www-form-urlencoded method of HTML 307 forms? 309 How to handle variables in Level 4 templates that are supposed to 310 have composite values? 312 Should there be some way how default values can be exposed/ 313 documented? 314 If a template is refined in an incremental process, does it make 315 sense to be able to add a "back" link and/or "home" link, so that 316 clients can find the "most general" version easily? 318 8. References 320 8.1. Normative References 322 [1] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. 323 Orchard, "URI Template", RFC 6570, March 2012. 325 [2] Hollander, D., Layman, A., Thompson, H., Tobin, R., and T. Bray, 326 "Namespaces in XML 1.0 (Third Edition)", World Wide Web 327 Consortium Recommendation REC-xml-names-20091208, December 2009, 328 . 330 [3] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes Second 331 Edition", World Wide Web Consortium Recommendation REC- 332 xmlschema-2-20041028, October 2004, 333 . 335 [4] Thompson, H., Beech, D., Mendelsohn, N., and M. Maloney, "XML 336 Schema Part 1: Structures Second Edition", World Wide Web 337 Consortium Recommendation REC-xmlschema-1-20041028, 338 October 2004, 339 . 341 [5] Bradner, S., "Key words for use in RFCs to Indicate Requirement 342 Levels", RFC 2119, March 1997. 344 [6] Nottingham, M., "Web Linking", RFC 5988, October 2010. 346 [7] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom Syndication 347 Format", RFC 4287, December 2005. 349 8.2. Informative References 351 [8] Nottingham, M., "Feed Paging and Archiving", RFC 5005, 352 September 2007. 354 URIs 356 [9] 358 Authors' Addresses 360 Erik Wilde 361 EMC Corporation 362 6801 Koll Center Parkway 363 Pleasanton, CA 94566 364 U.S.A. 366 Phone: +1-925-6006244 367 Email: erik.wilde@emc.com 368 URI: http://dret.net/netdret/ 370 Cornelia Davis 371 EMC Corporation 373 Email: cornelia.davis@emc.com 375 Yiming Liu 376 UC Berkeley 377 South Hall 378 Berkeley, CA 94720 379 U.S.A. 381 Email: yliu@ischool.berkeley.edu