idnits 2.17.1 draft-wilde-link-desc-01.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 : ---------------------------------------------------------------------------- ** There are 63 instances of too long lines in the document, the longest one being 243 characters in excess of 72. ** The abstract seems to contain references ([2], [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 and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (February 12, 2014) is 3725 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'XSD-2' is defined on line 704, but no explicit reference was found in the text == Unused Reference: 'RFC5005' is defined on line 725, but no explicit reference was found in the text == Outdated reference: A later version (-03) exists of draft-nottingham-link-hint-00 ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) -- Obsolete informational reference (is this intentional?): RFC 6982 (Obsoleted by RFC 7942) Summary: 4 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft UC Berkeley 4 Intended status: Informational February 12, 2014 5 Expires: August 16, 2014 7 HTTP Link Descriptions 8 draft-wilde-link-desc-01 10 Abstract 12 Interactions with many resources on the Web are driven by links, and 13 these links often define certain expectations about the interactions 14 (such as HTTP methods being allowed, media types being accepted in 15 the request, or URI templates being supported). While these 16 expectations are essential to define the possible interactions, it 17 may be useful to further narrow them down by providing link 18 descriptions, which can help clients to gain more runtime knowledge 19 about the resource they are about to interact with. This memo 20 defines Link Descriptions, a model and associated media type that can 21 be used to describe links by supporting descriptive markup for 22 representing interaction information with links. Link Descriptions 23 can be used by media types (by inclusion or by reference) that seek 24 to make Link Descriptions runtime-capable, without having to create 25 their own representation for them. 27 Note to Readers 29 Please discuss this draft on the apps-discuss mailing list [1]. 31 Online access to all versions and files is available on github [2]. 33 Status of this Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on August 16, 2014. 50 Copyright Notice 52 Copyright (c) 2014 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.1. Web Links . . . . . . . . . . . . . . . . . . . . . . . . 5 69 1.2. URI Templates . . . . . . . . . . . . . . . . . . . . . . 6 70 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 3. Description Concepts . . . . . . . . . . . . . . . . . . . . . 8 72 3.1. Link Hints . . . . . . . . . . . . . . . . . . . . . . . . 8 73 3.2. Describing Variables . . . . . . . . . . . . . . . . . . . 8 74 4. Link Descriptions . . . . . . . . . . . . . . . . . . . . . . 9 75 4.1. General Concepts . . . . . . . . . . . . . . . . . . . . . 9 76 4.2. Link Description Structure . . . . . . . . . . . . . . . . 10 77 4.3. Variable Description Structure . . . . . . . . . . . . . . 10 78 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 5.1. Editable Entry . . . . . . . . . . . . . . . . . . . . . . 10 80 5.2. Pageable Collection . . . . . . . . . . . . . . . . . . . 11 81 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 82 6.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . . 11 83 6.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 13 84 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 13 85 8. Security Considerations . . . . . . . . . . . . . . . . . . . 14 86 9. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 14 87 10. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 15 88 10.1. From -00 to -01 . . . . . . . . . . . . . . . . . . . . . 15 89 10.2. Prior to -00 . . . . . . . . . . . . . . . . . . . . . . . 15 90 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 91 11.1. Normative References . . . . . . . . . . . . . . . . . . . 15 92 11.2. Informative References . . . . . . . . . . . . . . . . . . 16 93 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17 94 Appendix B. Link Description Schema . . . . . . . . . . . . . . . 17 95 Appendix C. XSLT for Generating Link Description HTML . . . . . . 19 96 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 23 98 1. Introduction 100 Interactions with resources found on the Web often are driven by 101 following links (targeted at URIs [RFC3986]), which can be either 102 fixed links (described in Section 1.1), or can be templated links 103 (using URI Templates [RFC6570]) containing variables (described in 104 Section 1.2). In both cases, the context of the link in most cases 105 provides information that can be essential or helpful when it comes 106 to following a link, which means interacting with the link target: 107 For fixed links, the context may provide (in most cases implicitly, 108 through the use of typed links) allowed interaction methods (such as 109 HTTP verbs) or expectations around the expected media type(s) in 110 requests; for templated links, the context additionally may provide 111 information about how to instantiate the variables provided in the 112 URI Template. This memo defines a schema and a media type that can 113 be used to (partially) represent this information, so that it becomes 114 possible to represent a change in interaction affordances at runtime. 116 Possible use cases for both scenarios (fixed and templated links) are 117 as follows: 119 Fixed Links: AtomPub [RFC5023] defines an "edit" link relation, 120 that informs clients that such a link can be followed to read, 121 update, or delete a resource. This means that a client 122 encountering such a link would conclude that it can try to read, 123 update, or delete the target resource. However, if the resource 124 is not deletable, then an "edit" link could be annotated to 125 indicate that the linked resource cannot be deleted. A client 126 could ignore the annotation and still attempt to delete the 127 resource, but the request would be likely to fail (unless the 128 state of the resource changed in the meantime). This kind of 129 information can be useful for UIs, where it can be used to drive 130 usability features such as disabling certain UI elements. 132 Templated Links: URI Templates [RFC6570] define a framework for 133 how to represent and instantiate (with concrete variable 134 assignments) templated URIs, but they don't describe how variables 135 themselves are described, or can be constrained. If a collection 136 resource for example supports paged access to the set of 137 collection members, then it might be useful for a client to know 138 the number of available pages. With this additional knowledge, it 139 is possible to build applications and UIs that specifically take 140 this knowledge into account to drive further interactions with the 141 resource. For a paged collection, it may be a UI that provides 142 direct links to all available pages (if that number is reasonably 143 small). Again, if the collection changes in size between the link 144 being generated, and the link interaction taking place, the 145 information in the link description has become outdated. But this 146 just means that either a client may request a page that doesn't 147 exist anymore, or will not expect a page to exist that now exists. 148 Both of these conditions can be handled well at the time when the 149 client starts interacting with the linked resource. 151 As described in both cases, it is possible for the link description 152 to become outdated, leading to cases where the assumptions made by 153 the client (based on the link description) and the link target itself 154 do not match anymore. For this reason, ideally a resource should 155 provide a link description for itself, allowing a client to update 156 its expectations. However, since the service generating the link and 157 the service providing the link target often are loosely coupled, link 158 descriptions can be used in links, in descriptions where services 159 expose more runtime information about resources by providing link 160 descriptions for themselves, or in both places. 162 The following example shows hows both of these mechanisms can be used 163 in one representation, which is based on Atom [RFC4287] and AtomPub 164 [RFC5023]. It also shows the two cases just described, with the 165 first link description being one to "self", while the second link 166 description is describing a different resource. 167 168 169 170 Example Feed 171 172 173 174 175 176 2003-12-13T18:30:02Z 177 178 John Doe 179 180 urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 181 182 Atom-Powered Robots Run Amok 183 184 185 186 187 188 189 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 190 2003-12-13T18:30:02Z 191 Some text. 192 193 194 The link to the feed itself is augmented with a URI Template 195 described in Section 1.2, which allows a client to understand that 196 individual feed pages can be requested (assuming the consumer 197 understands the "concept" identifiers for the described variables). 198 The link to the entry is an augmented typed Web Link described in 199 Section 1.1, which allows a consumer to understand that even though 200 "edit" links typically can be followed via GET, PUT, and DELETE, this 201 particular link should only be followed using a PUT request. 203 It is worth noting that link descriptions of course can become 204 outdated between the time such a link description has been received 205 by a client, and the time a client actually sends a request when 206 following such a link (this is the case both for "self" links and 207 links to other resources). This means that clients should never 208 depend on a link description being correct, because for example the 209 "edit" link description shown above might start allowing DELETE 210 requests again at any point in time. 212 1.1. Web Links 214 One of the defining principles of many services provided on the Web 215 is that they expose linked resources, so that clients can follow the 216 links in order to accomplish application goals. "Web Linking" 217 [RFC5988] establishes a framework of typed links, allowing resources 218 to expose typed links, which then can be followed by clients. While 219 this framework allows clients to select links based on their "types", 220 it does not provide any support for additional runtime information 221 about possible interactions with such a link. As outlined in the 222 AtomPub example above, a link typed as "edit" (as defined and 223 registered by AtomPub) can be followed by using HTTP GET, PUT, or 224 DELETE, and the typed link by itself cannot provide the additional 225 information that some resource may allow updates, but disallows 226 deletion. 228 "Link Hints" [I-D.nottingham-link-hint] (a draft currently under 229 development) provide a framework for runtime hints that can be used 230 to indicate information that might be made available by the link 231 target resource itself, but ahead of time. For example, a link hint 232 would be able to indicate on an "edit" link that the resource only 233 allows PUT requests, which is something that could also be discovered 234 by sending an HTTP request and getting an HTTP Allow header in the 235 response. However, link hints can save overhead by avoiding round 236 trips, and they also allow to minimize the chances of sending 237 requests that will not succeed. 239 While link hints can help to avoid overhead and drive client 240 behavior, they are strictly optional. There should be no functional 241 difference of what a client can achieve by using or ignoring link 242 hints; they simply expose information that otherwise would be more 243 costly to acquire. 245 Since it is potentially expensive to provide link hints in 246 representations (because they may involve interpreting access control 247 data), it is perfectly possible that services provide link hints only 248 on some requests. For example, it would be possible for a service to 249 serve http://example.com/collection as a collection of items with 250 embedded "edit" links, whereas 251 http://example.com/collection?hints=true would result in a 252 representation that would contain additional link hints for each 253 individual "edit" link. This kind of design is outside of the scope 254 of this memo, but it is helpful to illustrate the fact that link 255 hints are nothing but optimizations. 257 Currently, there is an overlap in what "Link Hints" 258 [I-D.nottingham-link-hint] define, and what is proposed in this memo. 259 While both drafts propose a way how to represent link hints/ 260 descriptions, the "Link Hints" draft does not address URI Templates. 261 Removing this overlap is captured in the "Open Issues" Section 9 and 262 should be addressed during the further development and/or alignment 263 of both drafts. 265 1.2. URI Templates 267 Following links is the basic principle of interacting with resources 268 on the web, but in many cases, interactions with resources require 269 clients to provide information in addition to just using a fixed URI 270 in a request. In these cases, information can be provided in any way 271 supported by the interaction protocol, and in case of HTTP, this 272 often means that information is either embedded in the URI, in HTTP 273 headers, and/or in the body of the request. For the first case, "URI 274 Template" [RFC6570] provides a standard that allows servers and 275 clients to exchange information about the URIs that a service 276 accepts. The standard specifies "a compact sequence of characters 277 for describing a range of Uniform Resource Identifiers through 278 variable expansion." It allows servers to publish their expectation 279 how a URI should be created by substituting variables with values. 280 Consider the following URI Template: 281 http://www.example.com/collection{?pagesize,page} 283 This URI Template allows clients to expand it with two variables 284 assignments, to end up with a concrete URI such as the following: 285 http://www.example.com/collection?pagesize=10&page=42 287 URI Templates cover the aspect of starting with a template with 288 variables in it, assigning values to these variables, and then 289 expanding the template into a URI that can be used for sending a 290 request. URI Templates make no assumptions or statements about the 291 meaning or value range of the variables, except for those aspects 292 which are required to cover the process of expanding the template. 293 In particular, for the example given above, there is no indication 294 that the values are supposed to be positive integers (the data type), 295 nor is there any indication that the service may apply certain limits 296 such as a maximum page size (which may change depending on which 297 paged resource is being accessed). As a side note, even if this 298 basic type information was known, URI template expansion could still 299 result in URIs that would not yield successful requests, such as when 300 asking for a page that is beyond the number of pages that a 301 collection has (in a given page size). 303 The goal of Link Descriptions as defined in this memo is to allow 304 servers to expose a description that provides support both at 305 development time (when a developer uses a media type that uses URI 306 Templates) and at runtime (when a client wants to use a URI template 307 as part of its application flow). Link Descriptions are intended to 308 provide additional information that is not communicated by publishing 309 URI Templates alone. The additional information is both targeted at 310 machines, and at humans. On the human-oriented Web, a Template 311 Description can be seen as the equivalent of a help or documentation 312 page that is linked to from a form, where users can learn more about 313 the values they are supposed to submit within the form. 315 As a concrete example, a link to a collection like the one above may 316 be exposed in a link description as follows: 317 318 319 320 322 This link description allows a URI Template's variables to be 323 described in terms of URI-identified concepts. By using such a 324 model, it is possible to use global names for URI Template 325 parameters, and bind them to URI Template variable names. The 326 template and the variables int the example above are not specific for 327 any HTTP method, i.e. this link description does not define any 328 constraints in terms of how to use URI Templates differently for 329 different HTTP methods. But this is possible, and is covered in the 330 detailed description below. 332 The concept URIs are pure identifiers for the purpose of link 333 descriptions; i.e. they should not be considered dereferenceable, and 334 the assumption is that consumers of link descriptions will only use 335 them to match discovered concepts against known concepts. This 336 design does not prohibit to make concept URIs dereferenceable, but 337 this is outside of the scope of link descriptions. 339 2. Terminology 341 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 342 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 343 document are to be interpreted as described in RFC 2119 [RFC2119]. 345 3. Description Concepts 347 The general idea of link descriptions is that they allow to annotate 348 links (URIs or URI Templates) with context that clients can use when 349 they choose to follow those links. In the XML syntax, descriptions 350 are deliberately designed to follow the design of Atom's popular 351 element, which serves as a blueprint for links in many media 352 types. The main idea of link descriptions is to provide a framework 353 which provides services that want to serve this kind of description 354 with a starting point. If these services want, they can reuse the 355 representations for this framework, in whole or in part. 357 3.1. Link Hints 359 As mentioned already, "Link Hints" [I-D.nottingham-link-hint] as 360 currently defined overlap with the concepts proposed in this memo. 361 However, this memo goes further than link hints by not just providing 362 hints for URIs, but for URI Templates as well. Based on the current 363 link hint model defined in that draft, a link hint is a name/value 364 pair, where the name is either a registered link hint, or a URI. The 365 allowed value space depends on the link hint, and in the current 366 model, structured values must be encoded in JSON. A link may have 367 any number of link hints, but only one link hint with a given name. 369 3.2. Describing Variables 371 When a link description uses a URI Template, then this template will 372 very likely contain variables. Variables can be described when using 373 Link Descriptions. For each variable contained in the URI Template, 374 it is possible to use the following description methods: 376 Concept: It is possible to associate a variable with a concept, so 377 that media types and applications can make an association between 378 the concepts they are defining/exposing, and how they are exposed 379 in URI Templates. Concepts can be identified by using a URI as an 380 identifier. This specification defines no interactions with this 381 URI identifier and makes no assumption about possible 382 representations, should this URI be dereferenceable and yield some 383 representation. 385 Documentation: Documentation constructs can be associated with 386 variables, which allows Link Descriptions to attach human-readable 387 information to individual variables. The documentation model has 388 the ability to support multi-lingual human-oriented documentation. 390 For the purpose of this specification, the term "description" should 391 be interpreted loosely. Description aspects such as concepts and 392 documentation do not prescribe a description framework; they simply 393 provides a structure how to deliver these descriptions, so that 394 clients can use them when making decisions about which links to 395 follow, and how to follow them. 397 4. Link Descriptions 399 Link Descriptions are based on a URI Template, and add descriptive 400 elements that allow publishers of URI Templates to describe the URI 401 Template as a whole, and to add individual descriptions of all 402 variables in the template. The idea of Link Descriptions is that 403 they are made available at design time and/or at runtime, so that 404 clients encountering URI Templates as part of HTTP services can find 405 more information about the template itself. 407 Ideally, every URI template exposed in an HTTP service should be 408 accompanied by a link to a Link Description. In those XML-based HTTP 409 services where URI Templates are exposed in XML attributes named 410 "hreft", the suggestion is to add a link to the corresponding Link 411 Description in an "hrefd" XML attribute. 413 4.1. General Concepts 415 As mentioned in Section 1.2, most of the descriptions in this spec do 416 not prescribe a specific description framework. While variables 417 (Section 4.3) can be described with a built-in vocabulary of 418 datatypes, most other descriptions are either for human consumption, 419 or do rely on some external description framework. To attach these 420 descriptions to both the template as a whole, and individual 421 variables, this specification reuses the "appinfo" and 422 "documentation" elements from XML Schema Part 1. These elements 423 carry a "source" attribute, which is used "to supplement the local 424 information." For example, when a description of a variable is done 425 formally using a specific description framework, this would best 426 translate to use appinfo elements, and to add an identifier to them 427 which would identify the description framework in question. As a 428 result, any client knowing this particular description framework 429 would be able to interpret the variable description in the Link 430 Description. 432 4.2. Link Description Structure 434 An interaction is described by including the URI Template itself, and 435 optionally adding documentation and/or appinfo elements to add human- 436 or machine-readable descriptions. 438 4.3. Variable Description Structure 440 A variable is described by specifying the variable name. Variables 441 can refer to a "concept" associated with a variable, which can by 442 identified by URI. This specification makes no provision how such a 443 concept is defined and/or described/documented, but it allows 444 consumers of a Link Description to match their understanding of 445 certain concepts to those identifiers, which then establishes a 446 binding between the concept, and the variable it has been bound to. 448 A variable can have a default value, in which case the assumption is 449 that excluding this variable from a request has the same effect as 450 including it with the default value. Since Link Descriptions are 451 runtime concepts, however, there is no guarantee that a service might 452 not use a different value between the time when the Link Description 453 was retrieved, and the time when a request based on it is being sent. 455 Variable descriptions can optionally add documentation and/or appinfo 456 elements to add human- or machine-readable descriptions. 458 5. Examples 460 ... 462 5.1. Editable Entry 464 ... 466 All the example use "documentation" elements which are entirely 467 optional, but can help to improve the usefulness of link descriptions 468 for developers. 470 471 472 473 Link Description for accessing the AtomPub media resource http://www.example.com/feed/item42, with the "edit-media" link allowing PUT/DELETE as per RFC 5023, but the specific resource not currently allowing DELETE (constraining AtomPub semantics), but allowing PATCH. 474 475 For this particular resource, PUT is supported. 476 477 Updates are accepted as PNG or JPEG representations. 478 479 480 481 Extending AtomPub's capabilities, images can also be PATCHed, with two patch media types being supported. 482 483 Patches are accepted as (hypothetical) PNG or JPEG patch document representations. 484 485 486 488 5.2. Pageable Collection 490 ... 491 492 493 494 Template for accessing a paged feed of entries at http://www.example.com/feed, with client controls for the page size, and the returned page. 495 496 Number of returned items per page. 497 498 499 Page number of the returned page (based on the requested pagesize or a service-defined default). 500 501 503 6. IANA Considerations 505 6.1. Media Type 507 The Internet media type [RFC6838] for a Link Description document is 508 application/ldesc+xml (using the "+xml" suffix as defined and 509 registered by RFC 6839 [RFC6839]). 511 Type name: application 513 Subtype name: ldesc+xml 514 Required parameters: none 516 Optional parameters: profile 518 The "profile" link relation [RFC6906] allows "resource 519 representations to indicate that they are following one or more 520 profiles. A profile is defined not to alter the semantics of 521 the resource representation itself, but to allow clients to 522 learn about additional semantics (constraints, conventions, 523 extensions) that are associated with the resource 524 representation, in addition to those defined by the media type 525 and possibly other mechanisms." If the application/ldesc+xml 526 media type is use with a profile parameter, this refers to a 527 profile as defined by [RFC6906], making it easier for 528 extensions of the link description media type to identify 529 themselves. 531 Encoding considerations: Same as encoding considerations of 532 application/xml as specified in [RFC3023]. 534 Security considerations: This media type has all of the security 535 considerations described in [RFC3023], plus those listed in 536 Section 8. 538 Interoperability considerations: N/A 540 Published specification: RFC XXXX 542 Applications that use this media type: Applications that publish 543 descriptions of URI Interactions. 545 Additional information: 547 Magic number(s): none 549 File extension(s): No specific file extension proposed, but as a 550 general rule, XML data often uses ".xml" as the file extension. 552 Macintosh file type code(s): TEXT 554 Person & email address to contact for further information: Erik 555 Wilde 557 Intended usage: COMMON 558 Restrictions on usage: none 560 Author: Erik Wilde 562 Change controller: IESG 564 6.2. Link Relation 566 The link relation type below will be registered by IANA per Section 567 6.2.1 of RFC 5988 [RFC5988]: 569 Relation Name: ldesc 571 Description: Linking to a resource that can be used as a link 572 description for requesting runtime information about a particular 573 context's interaction affordances. 575 Reference: RFC XXXX 577 Notes: Link Descriptions can be used in all scenarios where 578 clients want to create requests that represent a query into the 579 context resource. The media type of the context resource and the 580 media type of the link description resource are not constrained by 581 this specification. 583 7. Implementation Status 585 Note to RFC Editor: Please remove this section before publication. 587 This section records the status of known implementations of the 588 protocol defined by this specification at the time of posting of this 589 Internet-Draft, and is based on a proposal described in RFC 6982 590 [RFC6982]. The description of implementations in this section is 591 intended to assist the IETF in its decision processes in progressing 592 drafts to RFCs. Please note that the listing of any individual 593 implementation here does not imply endorsement by the IETF. 594 Furthermore, no effort has been spent to verify the information 595 presented here that was supplied by IETF contributors. This is not 596 intended as, and must not be construed to be, a catalog of available 597 implementations or their features. Readers are advised to note that 598 other implementations may exist. 600 According to RFC 6982, "this will allow reviewers and working groups 601 to assign due consideration to documents that have the benefit of 602 running code, which may serve as evidence of valuable experimentation 603 and feedback that have made the implemented protocols more mature. 604 It is up to the individual working groups to use this information as 605 they see fit". 607 8. Security Considerations 609 ... 611 9. Open Issues 613 If and how to use profiles (example in Section 5); if profile use 614 is recommended, define a suggested profile URI for other specs to 615 use? 617 How to handle variables in Level 4 templates that are supposed to 618 have composite values? 620 If a template is refined in an incremental process (such as for 621 example faceted search services), does it make sense to be able to 622 add a "back" link and/or "home" link, so that clients can find the 623 "most general" version easily? 625 How does this interact with "faceted search" scenarios? Does 626 incremental refinement of URI Template Descriptions somehow nicely 627 and naturally map into faceted search scenarios? 629 Is there a concept of how Template Descriptions (and thus URI 630 Templates) can be reused? Should there be an inclusion facility 631 or something along those lines? If so, what's the model for that? 632 Initial thoughts on possibilities can be found on this page [3] 634 Should there be some recommended link relation to use when linking 635 to a Template Description from within the context of a URI 636 Template? 638 While currently everything is defined in XML, providing 639 alternative serializations (JSON and RDF) might be an interesting 640 thing to consider. 642 Should there be a "Template" HTTP header field, listing a 643 resource's URI Template and, optionally, containing a link to a 644 description resource for it (basically, a rel="ldesc" link)? 646 What about using CURIE for the variable names, thus eliminating 647 the need for separate concept URIs? This would need prefix 648 bindings, which in XML would just up as regular namespace 649 declarations. It might quite be a bit more problematic in non-XML 650 contexts, such as serving a URI Template in an HTTP header. 652 Support for "HTTP Prefer" [I-D.snell-http-prefer] might need 653 another link hint, so that clients know which preferences they 654 might use. 656 10. Change Log 658 Note to RFC Editor: Please remove this section before publication. 660 10.1. From -00 to -01 662 o Adding "Template" HTTP header field as an open issue. 664 o Adding CURIEs as one possible convention to use for variable 665 names, so that "Concept URIs" are embedded in the template itself, 666 and not external. 668 o Adding "HTTP Prefer" [I-D.snell-http-prefer] as an open issue. 670 o Updated author address. 672 10.2. Prior to -00 674 An earlier variation of a similar idea was published as "Template 675 Descriptions" [I-D.wilde-template-desc]. However, since this earlier 676 draft was exclusively focusing on interactions with links driven by 677 URI Templates [RFC6570], instead of looking at links in general, it 678 was sufficiently distinct to start a new draft, instead of evolving 679 the existing one. 681 11. References 683 11.1. Normative References 685 [I-D.nottingham-link-hint] 686 Nottingham, M., "HTTP Link Hints", 687 draft-nottingham-link-hint-00 (work in progress), 688 June 2013. 690 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 691 Requirement Levels", RFC 2119, March 1997. 693 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 694 Types", RFC 3023, January 2001. 696 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 697 Syndication Format", RFC 4287, December 2005. 699 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 701 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 702 and D. Orchard, "URI Template", RFC 6570, March 2012. 704 [XSD-2] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 705 Second Edition", World Wide Web Consortium 706 Recommendation REC-xmlschema-2-20041028, October 2004, 707 . 709 11.2. Informative References 711 [I-D.snell-http-prefer] 712 Snell, J., "Prefer Header for HTTP", 713 draft-snell-http-prefer-18 (work in progress), 714 January 2013. 716 [I-D.wilde-template-desc] 717 Wilde, E., Davis, C., and Y. Liu, "URI Template 718 Descriptions", draft-wilde-template-desc-00 (work in 719 progress), December 2012. 721 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 722 Resource Identifier (URI): Generic Syntax", STD 66, 723 RFC 3986, January 2005. 725 [RFC5005] Nottingham, M., "Feed Paging and Archiving", RFC 5005, 726 September 2007. 728 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 729 Protocol", RFC 5023, October 2007. 731 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 732 Specifications and Registration Procedures", BCP 13, 733 RFC 6838, January 2013. 735 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 736 Structured Syntax Suffixes", RFC 6839, January 2013. 738 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 739 March 2013. 741 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 742 Code: The Implementation Status Section", RFC 6982, 743 July 2013. 745 URIs 747 [1] 749 [2] 751 [3] 754 Appendix A. Acknowledgements 756 Thanks for comments and suggestions provided by Dmitry Limonov. 758 Appendix B. Link Description Schema 759 760 761 762 763 Get access to the xml: attribute groups for xml:lang as declared on 'documentation' below. 764 765 766 767 768 769 Representing the type for URI template values according to RFC 6570. This is probably too complicated to cover with a regular expression in any reasonable way, so type enforcement is not done by the schema. 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 As defined by http://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-24#section-3.2.6, and only allowing one method token to be specified. 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 If variables are restricted in ways other than the simple type restrictions that are built into link descriptions, then these restrictions can be embedded in a variable description as well, as long as they are represented using a different namespace. 827 828 829 830 831 832 833 Identifies the variable by referring to a concept URI. 834 835 836 837 838 839 840 841 842 843 844 845 A hint is either a registered hint with a simple name (defined by a regular expression), or an unregistered hint which is identified by URI. 846 847 848 849 850 851 852 The list of "registered link hints" is taken from http://tools.ietf.org/html/draft-nottingham-link-hint-00#section-3 and will probably change. 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 874 Appendix C. XSLT for Generating Link Description HTML 875 876 877 878 879 880 881 Link Descriptions 882 886 887 888

Link Descriptions

889 890
891 892

893 894 895 =" 896 897 898 899 " 900 901

902 903 904

905 906 rel=" 907 908 " 909 910

911 912 913 914 915 918 919
Documentation: 916 917
920 921

Variables:

922 923 924 925 926 927 928 929 930 931 932 933 934 935 938 950 964 1005 1008 1009 1010
VariableConceptDefaultValue RangeDocumentation
936 937 939 940 941 942 943 944 945 946 n/a 947 948 949 951 952 953 954 955 956 957 958 959 960 n/a 961 962 963 965 966 967
968 Base: 969 970 971 972 973 974 975 976 977 978 979 980 981
982 983
    984 985 986
  • 987 988 989 990 991 =" 992 993 " 994 995
    • 996     997
998 999 1000 1001 n/a 1002 1003 1004 		1006 1007
1011 1012 1013

Hints:

1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1028 1034 1037 1038 1039
NameValueDocumentation
1026 1027 1029 1030 1031 1033 1035 1036
1040 1041 1042 1043 1044 1045 1046 1047 1048
    1049 1050
  • 1051 1052 1053 1054 1055 ( 1056 1057 xml:lang=" 1058 1059 " 1060 1061 ) 1062 1063 1064
    • 1065     1066
1067 1068 1069 n/a 1070 1071 1072 1073 1074 Author's Address 1076 Erik Wilde 1077 UC Berkeley 1079 Email: dret@berkeley.edu 1080 URI: http://dret.net/netdret/