idnits 2.17.1 draft-wilde-link-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 : ---------------------------------------------------------------------------- ** There are 96 instances of too long lines in the document, the longest one being 247 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 (September 16, 2013) is 3868 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: 'RFC5005' is defined on line 731, 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 (~~), 4 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 EMC Corporation 4 Intended status: Informational September 16, 2013 5 Expires: March 20, 2014 7 HTTP Link Descriptions 8 draft-wilde-link-desc-00 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 used, media types being sent in the 15 request, or URI parameters being used in a certain way). While these 16 expectations are essential to define the possible framework for 17 interactions, it may be useful to further narrow them down by 18 providing link descriptions, which can help clients to gain more 19 runtime knowledge about the resource they are about to interact with. 20 This memo defines Link Descriptions, a model and associated media 21 type that can be used to describe links by supporting descriptive 22 markup for representing interaction information with links. Link 23 Descriptions can be used by media types (by inclusion or by 24 reference) that seek to make Link Descriptions runtime-capable, 25 without having to create their own representation. 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 March 20, 2014. 50 Copyright Notice 52 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . . . . . . 6 69 1.2. URI Templates . . . . . . . . . . . . . . . . . . . . . . 7 70 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 3. Description Concepts . . . . . . . . . . . . . . . . . . . . . 8 72 3.1. Link Hints . . . . . . . . . . . . . . . . . . . . . . . . 8 73 3.2. Describing Variables . . . . . . . . . . . . . . . . . . . 9 74 4. Link Descriptions . . . . . . . . . . . . . . . . . . . . . . 10 75 4.1. General Concepts . . . . . . . . . . . . . . . . . . . . . 10 76 4.2. Link Description Structure . . . . . . . . . . . . . . . . 11 77 4.3. Variable Description Structure . . . . . . . . . . . . . . 11 78 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 79 5.1. Editable Entry . . . . . . . . . . . . . . . . . . . . . . 11 80 5.2. Pageable Collection . . . . . . . . . . . . . . . . . . . 12 81 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 82 6.1. Media Type . . . . . . . . . . . . . . . . . . . . . . . . 12 83 6.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 14 84 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 14 85 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 86 9. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 15 87 10. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 15 88 10.1. Prior to -00 . . . . . . . . . . . . . . . . . . . . . . . 15 89 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 90 11.1. Normative References . . . . . . . . . . . . . . . . . . . 16 91 11.2. Non-Normative References . . . . . . . . . . . . . . . . . 16 92 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17 93 Appendix B. Link Description Schema . . . . . . . . . . . . . . . 17 94 Appendix C. XSLT for Generating Link Description HTML . . . . . . 21 95 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 26 97 1. Introduction 99 Interactions with resources found on the Web often are driven by 100 following links (targeted at URIs [RFC3986]), which can be either 101 fixed links (described in Section 1.1), or can be templated links 102 (using URI Templates [RFC6570]) containing variables (described in 103 Section 1.2). In both cases, the context of the link in most cases 104 provides information that can be essential or helpful when it comes 105 to following a link, which essentially means interacting with the 106 link target: For fixed links, the context may provide (in most cases 107 implicitly, through the use of typed links) allowed interaction 108 methods (such as HTTP verbs) or expectations around the expected 109 media type(s) in requests; for templated links, the context 110 additionally may provide information about how to instantiate the 111 variables provided in the URI Template. This memo defines a schema 112 and a media type that can be used to (partially) represent this 113 information, so that it becomes possible to represent a change in 114 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 a link can be followed to read, update, 121 or delete a resource. This means that a client encountering such 122 a link would conclude that it can try to read, update, or delete 123 the target resource. However, if the resource is not deletable, 124 then an "edit" link could be annotated to indicate that the linked 125 resource cannot be deleted. A client could ignore the annotation 126 and still attempt to delete the resource, but the request would be 127 likely to fail (unless the state of the resource changed in the 128 meantime). This kind of information can be very useful for UIs, 129 where it can be used to drive usability features such as disabling 130 certain UI elements. 132 Templated Links: URI Templates [RFC6570] define a framework for 133 how to represent and instantiate (with concrete variable values) 134 templated URIs, but they don't describe how variables themselves 135 are described, or can be constrained. If a collection resource 136 for example supports paged access to the set of collection 137 members, then it might be useful for a client to know the number 138 of available pages. With this additional knowledge, it is 139 possible to build applications and UIs that specifically take this 140 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 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 about a different resource. 168 169 170 Example Feed 171 172 173 174 175 176 177 178 179 180 181 2003-12-13T18:30:02Z 182 183 John Doe 184 185 urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6 186 187 Atom-Powered Robots Run Amok 188 189 190 191 192 193 urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a 194 2003-12-13T18:30:02Z 195 Some text. 196 197 199 The link to the feed itself is augmented with a URI Template 200 described in Section 1.2, which allows a client to understand that 201 individual feed pages can be requested (assuming the consumer 202 understands the "concept" identifiers for the described variables). 203 The link to the entry is an augmented typed Web Link described in 204 Section 1.1, which allows a consumer to understand that even though 205 "edit" links typically can be followed via GET, PUT, and DELETE, this 206 particular link should only be followed using a PUT request. 208 It is worth noting that link descriptions of course can become 209 outdated between the time such a link decription has been received by 210 a client, and the time a client actually sends a request when 211 following such a link (this is the case both for "self" links and 212 links to other resources). This means that clients should never 213 depend on link description being correct, because for example the 214 "edit" link description shown above might start allowing DELETE 215 requests again at any point in time. 217 1.1. Web Links 219 One of the defining principles of many services provided on the Web 220 is that they expose linked resources, so that clients can follow the 221 links in order to accomplish application goals. "Web Linking" 222 [RFC5988] establishes a framework of typed links, allowing resources 223 to expose typed links, which then can be followed by clients. While 224 this framework allows clients to select links based on their types, 225 it does not provide any support for additional runtime information 226 about possible interactions with such a link. As outlined in the 227 AtomPub example above, a link typed as "edit" (as defined and 228 registered by AtomPub) by definition can be followed by using HTTP 229 GET, PUT, or DELETE, and the typed link by itself cannot provide the 230 additional information that some resource may allow updates, but 231 disallows deletion. 233 "Link Hints" [I-D.nottingham-link-hint] provide a framework of 234 runtime hints that can be used to indicate information that might be 235 made available by the link target resource itself, but ahead of time. 236 For example, a link hint would be able to indicate on an "edit" link 237 that the resource only allows PUT requests, which is something that 238 could also be discovered by sending an HTTP request and getting an 239 HTTP Allow header in the response. However, link hints can save 240 overhead by avoiding round trips, and they also allow to minimize the 241 chances of sending requests that will not succeed. 243 While link hints can help to avoid overhead and drive client 244 behavior, they are strictly optional. There should be no functional 245 difference of what a client can achieve by using or ignoring link 246 hints; they simply expose information that otherwise would be more 247 costly to acquire. 249 Since it is potentially expensive to provide link hints in 250 representations (because they may involve interpreting access control 251 data), it is perfectly possible that services provide link hints only 252 on some requests. For example, it would be possible to design a 253 service that served http://example.com/collection as a collection of 254 items with embedded "edit" links, whereas 255 http://example.com/collection?hints=true would result in a 256 representation that would contain additional link hints for each 257 individual "edit" link. This kind of design is outside of the scope 258 of this memo, but it's helpful to illustrate the fact that link hints 259 are nothing but optimizations of at which point during interactions 260 certain information is provided. 262 Currently, there is an overlap in what "Link Hints" 263 [I-D.nottingham-link-hint] define, and what is proposed in this memo. 264 Removing this overlap is captured in the "Open Issues" Section 9 and 265 should be addressed during the development of both drafts. 267 1.2. URI Templates 269 While following links is the basic principle of interacting with 270 resources on the web, in many cases, interactions with resources 271 require clients to provide information in addition to just using a 272 fixed URI in a request. In these cases, information can be provided 273 in any way supported by the interaction protocol, and in case of 274 HTTP, this often means that information is either embedded in the 275 URI, and/or in the body of the request. For the first case, "URI 276 Template" [RFC6570] provides a standard that allows servers and 277 clients to exchange information about the URIs that a service 278 accepts. The standard specifies "a compact sequence of characters 279 for describing a range of Uniform Resource Identifiers through 280 variable expansion." It allows servers to publish their expectation 281 how a URI should be created by substituting variables with values. 282 Consider the following URI Template: 283 http://www.example.com/collection{?pagesize,page} 285 This URI Template allows clients to expand it with two variables 286 values, to end up with a concrete URI such as the following: 287 http://www.example.com/collection?pagesize=10&page=42 289 URI Templates cover the aspect of starting with a template with 290 variables in it, assigning values to these variables, and then 291 expanding the template into a URI that can be used for sending a 292 request. URI Templates make no assumptions or statements about the 293 value range of the variables, except for those aspects which are 294 required to cover the process of expanding the template. In 295 particular, for the example given above, there is no indication that 296 the values are supposed to be positive integers (the simple data 297 type), nor is there any indication that the service may apply certain 298 limits such as a maximum page size (which may change depending on 299 which paged resource is being accessed). As a side note, even if 300 this basic type information was known, URI template expansion could 301 still result in URIs that would not yield successful requests, such 302 as when asking for a page that is beyond the number of pages that a 303 collection has (in a given page size). 305 The goal of Link Descriptions as defined in this memo is to allow 306 servers to expose a description that provides support both at 307 development time (when a developer looks at a media type that uses 308 URI Templates) and at runtime (when a client wants to use a URI 309 template as part of its application flow). Link Descriptions are 310 intended to provide additional information that is not communicated 311 by publishing URI Templates alone. The additional information is 312 both targeted at machines and at humans. On the human-oriented Web, 313 a Template Description can be seen as the equivalent of a help or 314 documentation page that is linked to from a form, where users can 315 learn more about the values they are supposed to submit within the 316 form. 318 As a concrete example, a link to a collection like the one above may 319 be exposed in a link description as follows: 320 321 322 323 325 This link description allows a URI Template's variables to be 326 described in terms of URI-identified concepts. By using such a 327 model, it is possible to use global names for URI Template 328 parameters, by binding them to the local variable names. The concept 329 URIs are pure identifiers for the purpose of link descriptions; i.e. 330 they should not be considered dereferenceable, and the assumption is 331 that consumers of link descriptions will only use them to match 332 discovered concepts against known concepts. This design does not 333 prohibit to make concept URIs dereferenceable, but this is outside of 334 the scope of link descriptions. 336 2. Terminology 338 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 339 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 340 document are to be interpreted as described in RFC 2119 [RFC2119]. 342 3. Description Concepts 344 The general idea of link descriptions is that they allow to annotate 345 links (URIs or URI Templates) with context that clients can use when 346 they choose to follow those links. In the XML syntax, descriptions 347 are deliberately designed to echo the design of Atom's popular 348 element, which serves as a blueprint for links in many media types. 349 The main idea of link descriptions is to provide a framework which 350 provides services that want to serve this kind of description with a 351 starting point. If these services want, they can reuse the 352 representations for this framework, in whole or in part. 354 3.1. Link Hints 356 As mentioned already, "Link Hints" [I-D.nottingham-link-hint] as 357 currently defined overlap with the concepts proposed in this memo. 358 However, this memo goes further that link hints by not just providing 359 hints for URIs, but for URI Templates as well. Based on the current 360 link hint model, a link hint is a name/value pair, where the name is 361 either a registered link hint, or a URI. The allowed value space 362 depends on the link hint, and in the current model, structured values 363 must be encoded in JSON. A hint may also contain application 364 specific information or documentation, in an model of application 365 information and documentation that has been inspired by XML Schema 366 Part 1 [XSD-1]. 368 A link may have any number of link hints, but only one link with a 369 given name. 371 3.2. Describing Variables 373 When a link uses a URI Template, then this template will very likely 374 contain variables. Variables can be described in a variety of ways 375 when using Link Descriptions. For each variable contained in the URI 376 Template, it is possible to use the following description methods: 378 Concept: It is possible to associate a variable with a concept, so 379 that media types and applications can make an association between 380 the concepts they are defining/exposing, and how they are exposed 381 in URI Templates. Concepts can be identified by using a URI as an 382 identifier. This specification defines no interactions with this 383 URI identifier and makes no assumption about possible 384 representations, should this URI be dereferenceable and yield some 385 representation. 387 Datatype: Variables can be described in terms of using certain 388 datatypes. The datatype vocabulary is that of XML Schema Part 2 389 [XSD-2], plus all of the applicable facets of those datatypes. 390 This allows Link Descriptions to constrain the set of allowed 391 values. (This model does not cover any "co-constraints", i.e. 392 dependencies across variables, or between variables and an 393 external context.) 395 Documentation: Documentation constructs can be associated with 396 variables, which allows Link Descriptions to attach human-readable 397 information to individual variables. The documentation constructs 398 use the documentation design of XML Schema Part 1 [XSD-1]. XML 399 Schema's documentation model has the ability to support multi- 400 lingual human-oriented documentation. 402 Application Information: Application information constructs can be 403 associated with variables, which allows Link Descriptions to 404 attach machine-readable information to individual variables. The 405 application information constructs use the application information 406 design of XML Schema Part 1 [XSD-1]. 408 For the purpose of this specification, the term "description" should 409 be interpreted loosely. Some aspects of descriptions can be formal, 410 such as the datatypes of variables. Thus, such a description can be 411 used to drive general-purpose logic that knows no additional 412 framework other than this specification. However, for most other 413 description aspects (concepts, documentation, and application 414 information), this specification does not prescribe a description 415 framework; it simply provides a structure how to deliver these 416 descriptions. 418 The descriptions of "concepts" and "datatypes" are not mutually 419 exclusive. On the contrary, a concept often will have associated 420 constraints that essentially define a datatype. The difference is 421 that while concepts are only described by identifier (allowing a 422 consumer to identify a concept that they know about), datatypes are 423 described with a built-in vocabulary (XSD datatypes and their 424 facets), allowing clients to interpret the datatype description. As 425 a consequence, when a consumer encounters an unknown concept, it adds 426 little to the knowledge of the consumer, whereas a datatype 427 description can always be interpreted and thus allows the consumer to 428 learn about constraints of the associated variable in a declarative 429 way. It may therefore make sense to combine concepts and datatypes, 430 if the goal is to be as self-describing as possible. 432 4. Link Descriptions 434 Link Descriptions are based on a URI Template, and add descriptive 435 elements that allow publishers of URI Templates to describe the URI 436 Template as a whole, and to add individual descriptions of all 437 variables in the template. The idea of Link Descriptions is that 438 they are made available at design time and/or at runtime, so that 439 clients encountering URI Templates as part of HTTP services can find 440 more information about the template itself. 442 Ideally, every URI template exposed in an HTTP service should be 443 accompanied by a link to a Link Description. In those XML-based HTTP 444 services where URI Templates are exposed in XML attributes named 445 "hreft", the suggestion is to add a link to the corresponding Link 446 Description in an "hrefd" XML attribute. 448 4.1. General Concepts 450 As mentioned in Section 1.2, most of the descriptions in this spec do 451 not prescribe a specific description framework. While variables 452 (Section 4.3) can be described with a built-in vocabulary of 453 datatypes, most other descriptions are either for human consumption, 454 or do rely on some external description framework. To attach these 455 descriptions to both the template as a whole, and individual 456 variables, this specification reuses the "appinfo" and 457 "documentation" elements from XML Schema Part 1 [XSD-1]. These 458 elements carry a "source" attribute, which is used (quoting from 459 [XSD-1]) "to supplement the local information." For example, when a 460 description of a variable is done formally using a specific 461 description framework, this would best translate to use appinfo 462 elements, and to add an identifier to them which would identify the 463 description framework in question. As a result, any client knowing 464 this particular description framework would be able to interpret the 465 variable description in the Link Description. 467 4.2. Link Description Structure 469 An interaction is described by including the URI Template itself, and 470 optionally adding documentation and/or appinfo elements to add human- 471 or machine-readable descriptions. 473 4.3. Variable Description Structure 475 A variable is described by specifying the variable name. Variables 476 can refer to a "concept" associated with a variable, which can by 477 identified by URI. This specification makes no provision how such a 478 concept is defined and/or described/documented, but it allows 479 consumers of a Link Description to match their understanding of 480 certain concepts to those identifiers, which then establishes a 481 binding between the concept, and the variable it has been bound to. 483 A variable can have a default value, in which case the assumption is 484 that excluding this variable from a request has the same effect as 485 including it with the default value. Since Link Descriptions are 486 runtime concepts, however, there is no guarantee that a service might 487 not use a different value between the time when the Link Description 488 was retrieved, and the time when a request based on it is being sent. 490 Variable descriptions can optionally add documentation and/or appinfo 491 elements to add human- or machine-readable descriptions. 493 5. Examples 495 ... 497 5.1. Editable Entry 499 ... 501 All the example use "documentation" elements which are entirely 502 optional, but can help to improve the usefulness of link descriptions 503 for developers. 504 505 506 For this particular resource, only PUT is supported. Specifically, this resource does not accept DELETE requests. 507 508 509 Updates are accepted as PNG or JPEG representations. 510 511 Template for accessing an AtomPub media resource http://www.example.com/feed/item42, with the "edit-media" link by default allowing PUT/DELETE as per RFC 5023. 512 514 5.2. Pageable Collection 516 ... 517 518 519 520 521 522 523 Number of returned items per page. 524 525 526 527 Page number of the returned page (based on the requested pagesize or a service-defined default). 528 529 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. 530 532 6. IANA Considerations 534 6.1. Media Type 536 The Internet media type [RFC6838] for a Link Description document is 537 application/ldesc+xml (using the "+xml" suffix as defined and 538 registered by RFC 6839 [RFC6839]). 540 Type name: application 542 Subtype name: ldesc+xml 544 Required parameters: none 546 Optional parameters: profile 547 The "profile" link relation [RFC6906] allows "resource 548 representations to indicate that they are following one or more 549 profiles. A profile is defined not to alter the semantics of 550 the resource representation itself, but to allow clients to 551 learn about additional semantics (constraints, conventions, 552 extensions) that are associated with the resource 553 representation, in addition to those defined by the media type 554 and possibly other mechanisms." If the application/ldesc+xml 555 media type is use with a profile parameter, this refers to a 556 profile as defined by [RFC6906], making it easier for 557 extensions of the link description media type to identify 558 themselves. 560 Encoding considerations: Same as encoding considerations of 561 application/xml as specified in [RFC3023]. 563 Security considerations: This media type has all of the security 564 considerations described in [RFC3023], plus those listed in 565 Section 8. 567 Interoperability considerations: N/A 569 Published specification: RFC XXXX 571 Applications that use this media type: Applications that publish 572 descriptions of URI Interactions. 574 Additional information: 576 Magic number(s): none 578 File extension(s): No specific file extension proposed, but as 579 a general rule, XML data often uses ".xml" as the file 580 extension. 582 Macintosh file type code(s): TEXT 584 Person & email address to contact for further information: Erik 585 Wilde 587 Intended usage: COMMON 589 Restrictions on usage: none 591 Author: Erik Wilde 593 Change controller: IETF 595 6.2. Link Relation 597 The link relation type below will be registered by IANA per Section 598 6.2.1 of RFC 5988 [RFC5988]: 600 Relation Name: ldesc 602 Description: Linking to a resource that can be used as a link 603 description for requesting runtime information about a particular 604 context's interaction affordances. 606 Reference: RFC XXXX 608 Notes: Link Descriptions can be used in all scenarios where 609 clients want to create requests that represent a query into the 610 context resource. The media type of the context resource and the 611 media type of the link description resource are not constrained by 612 this specification. 614 7. Implementation Status 616 Note to RFC Editor: Please remove this section before publication. 618 This section records the status of known implementations of the 619 protocol defined by this specification at the time of posting of this 620 Internet-Draft, and is based on a proposal described in RFC 6982 621 [RFC6982]. The description of implementations in this section is 622 intended to assist the IETF in its decision processes in progressing 623 drafts to RFCs. Please note that the listing of any individual 624 implementation here does not imply endorsement by the IETF. 625 Furthermore, no effort has been spent to verify the information 626 presented here that was supplied by IETF contributors. This is not 627 intended as, and must not be construed to be, a catalog of available 628 implementations or their features. Readers are advised to note that 629 other implementations may exist. 631 According to RFC 6982, "this will allow reviewers and working groups 632 to assign due consideration to documents that have the benefit of 633 running code, which may serve as evidence of valuable experimentation 634 and feedback that have made the implemented protocols more mature. 635 It is up to the individual working groups to use this information as 636 they see fit". 638 8. Security Considerations 640 ... 642 9. Open Issues 644 If and how to use profiles (example in Section 5); if profile use 645 is recommended, define a suggested profile URI for other specs to 646 use? 648 How to handle variables in Level 4 templates that are supposed to 649 have composite values? 651 If a template is refined in an incremental process (such as for 652 example faceted search services), does it make sense to be able to 653 add a "back" link and/or "home" link, so that clients can find the 654 "most general" version easily? 656 How does this interact with "faceted search" scenarios? Does 657 incremental refinement of URI Template Descriptions somehow nicely 658 and naturally map into faceted search scenarios? 660 Is there a concept of how Template Descriptions (and thus URI 661 Templates) can be reused? Should there be an inclusion facility 662 or something along those lines? If so, what's the model for that? 663 Initial thoughts on possibilities can be found on this page [3] 665 Should there be some recommended link relation to use when linking 666 to a Template Description from within the context of a URI 667 Template? 669 While currently everything is defined in XML, providing 670 alternative serializations (JSON and RDF) might be an interesting 671 thing to consider. 673 10. Change Log 675 Note to RFC Editor: Please remove this section before publication. 677 10.1. Prior to -00 679 An earlier variation of a similar idea was published as "Template 680 Descriptions" [I-D.wilde-template-desc]. However, since this earlier 681 draft was exclusively focusing on interactions with links driven by 682 URI Templates [RFC6570], instead of looking at links in general, it 683 was sufficiently distinct to start a new draft, instead of evolving 684 the existing one. 686 11. References 688 11.1. Normative References 690 [I-D.nottingham-link-hint] 691 Nottingham, M., "HTTP Link Hints", 692 draft-nottingham-link-hint-00 (work in progress), 693 June 2013. 695 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 696 Requirement Levels", RFC 2119, March 1997. 698 [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media 699 Types", RFC 3023, January 2001. 701 [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom 702 Syndication Format", RFC 4287, December 2005. 704 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 706 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 707 and D. Orchard, "URI Template", RFC 6570, March 2012. 709 [XSD-1] Thompson, H., Beech, D., Mendelsohn, N., and M. Maloney, 710 "XML Schema Part 1: Structures Second Edition", World Wide 711 Web Consortium Recommendation REC-xmlschema-1-20041028, 712 October 2004, 713 . 715 [XSD-2] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes 716 Second Edition", World Wide Web Consortium 717 Recommendation REC-xmlschema-2-20041028, October 2004, 718 . 720 11.2. Non-Normative References 722 [I-D.wilde-template-desc] 723 Wilde, E., Davis, C., and Y. Liu, "URI Template 724 Descriptions", draft-wilde-template-desc-00 (work in 725 progress), December 2012. 727 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 728 Resource Identifier (URI): Generic Syntax", STD 66, 729 RFC 3986, January 2005. 731 [RFC5005] Nottingham, M., "Feed Paging and Archiving", RFC 5005, 732 September 2007. 734 [RFC5023] Gregorio, J. and B. de hOra, "The Atom Publishing 735 Protocol", RFC 5023, October 2007. 737 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 738 Specifications and Registration Procedures", BCP 13, 739 RFC 6838, January 2013. 741 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 742 Structured Syntax Suffixes", RFC 6839, January 2013. 744 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, 745 March 2013. 747 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 748 Code: The Implementation Status Section", RFC 6982, 749 July 2013. 751 URIs 753 [1] 755 [2] 757 [3] 760 Appendix A. Acknowledgements 762 Thanks for comments and suggestions provided by Dmitry Limonov. 764 Appendix B. Link Description Schema 765 766 767 768 Get access to the xml: attribute groups for xml:lang as declared on 'documentation' below. 769 770 771 772 773 774 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. 775 776 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 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 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. 869 870 871 872 873 874 875 Identifies the variable by referring to a concept URI. 876 877 878 879 880 Defines the default value for the variable (used by the service if no value is provided). The value must match the type defined for the variable. 881 882 883 884 885 886 887 888 889 890 891 892 893 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. 894 895 896 897 898 899 900 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. 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 It is not allowed to have more than one hint with the same @name on the same link. 921 923 924 925 926 927 928 929 930 931 A link must either specify a URI (@href) or a URI Template (@hreft), but it cannot specify both at the same time. 932 933 934 935 937 Appendix C. XSLT for Generating Link Description HTML 938 939 940 941 942 943 Link Descriptions 944 948 949 950

Link Descriptions

951 952
953 954

955 956 957 =" 958 959 960 961 " 962 963

964 965 966

967 968 rel=" 969 970 " 971 972

973 974 975 976 977 980 981 982 983 986 987
Documentation: 978 979
Appinfo: 984 985
988 989

Variables:

990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1007 1020 1034 1076 1079 1082 1083 1084
VariableConceptDefaultValue RangeDocumentationAppinfo
1005 1006 1008 1009 1010 1011 1012 1013 1014 1015 n/a 1016 1017 1019 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 n/a 1031 1032 1033 1035 1036 1037
1038 Base: 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051
1052 1053
    1054 1055 1056
  • 1057 1058 1059 1060 1061 =" 1062 1063 " 1064 1065
    • 1066     1068
1069 1070 1071 1072 n/a 1073 1074 1075 		1077 1078 1080 1081
1085 1086 1087

Hints:

1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1103 1108 1111 1114 1115 1117
NameValueDocumentationAppinfo
1101 1102 1104 1105 1106 1107 1109 1110 1112 1113
1118 1119 1120 1121 1122 1123 1124 1125 1126
    1127 1128
  • 1129 1130 1131 1132 1133 ( 1134 1135 xml:lang=" 1136 1137 " 1138 1139 ) 1140 1141 1142
    • 1143     1144
1145 1146 1147 n/a 1148 1149 1150 1151 1152 1153 1154
    1155 1156
  • 1157 Source: 1158 1159
    • 1160     1161
1162 1163 1164 n/a 1166 1167 1168 1169 1171 Author's Address 1173 Erik Wilde 1174 EMC Corporation 1175 6801 Koll Center Parkway 1176 Pleasanton, CA 94566 1177 U.S.A. 1179 Phone: +1-925-6006244 1180 Email: erik.wilde@emc.com 1181 URI: http://dret.net/netdret/