]> UC Berkeley

dret@berkeley.edu http://dret.net/netdret/

Interactions with many resources on the Web are driven by links, and these links often define certain expectations about the interactions (such as HTTP methods being allowed, media types being accepted in the request, or URI templates being supported). While these expectations are essential to define the possible interactions, it may be useful to further narrow them down by providing link descriptions, which can help clients to gain more runtime knowledge about the resource they are about to interact with. This memo defines Link Descriptions, a model and associated media type that can be used to describe links by supporting descriptive markup for representing interaction information with links. Link Descriptions can be used by media types (by inclusion or by reference) that seek to make Link Descriptions runtime-capable, without having to create their own representation for them. Please discuss this draft on the apps-discuss mailing list. Online access to all versions and files is available on github.

Interactions with resources found on the Web often are driven by following links (targeted at URIs ), which can be either fixed links (described in ), or can be templated links (using URI Templates ) containing variables (described in ). In both cases, the context of the link in most cases provides information that can be essential or helpful when it comes to following a link, which means interacting with the link target: For fixed links, the context may provide (in most cases implicitly, through the use of typed links) allowed interaction methods (such as HTTP verbs) or expectations around the expected media type(s) in requests; for templated links, the context additionally may provide information about how to instantiate the variables provided in the URI Template. This memo defines a schema and a media type that can be used to (partially) represent this information, so that it becomes possible to represent a change in interaction affordances at runtime. Possible use cases for both scenarios (fixed and templated links) are as follows: Fixed Links: AtomPub defines an "edit" link relation, that informs clients that such a link can be followed to read, update, or delete a resource. This means that a client encountering such a link would conclude that it can try to read, update, or delete the target resource. However, if the resource is not deletable, then an "edit" link could be annotated to indicate that the linked resource cannot be deleted. A client could ignore the annotation and still attempt to delete the resource, but the request would be likely to fail (unless the state of the resource changed in the meantime). This kind of information can be useful for UIs, where it can be used to drive usability features such as disabling certain UI elements. Templated Links: URI Templates define a framework for how to represent and instantiate (with concrete variable assignments) templated URIs, but they don't describe how variables themselves are described, or can be constrained. If a collection resource for example supports paged access to the set of collection members, then it might be useful for a client to know the number of available pages. With this additional knowledge, it is possible to build applications and UIs that specifically take this knowledge into account to drive further interactions with the resource. For a paged collection, it may be a UI that provides direct links to all available pages (if that number is reasonably small). Again, if the collection changes in size between the link being generated, and the link interaction taking place, the information in the link description has become outdated. But this just means that either a client may request a page that doesn't exist anymore, or will not expect a page to exist that now exists. Both of these conditions can be handled well at the time when the client starts interacting with the linked resource. As described in both cases, it is possible for the link description to become outdated, leading to cases where the assumptions made by the client (based on the link description) and the link target itself do not match anymore. For this reason, ideally a resource should provide a link description for itself, allowing a client to update its expectations. However, since the service generating the link and the service providing the link target often are loosely coupled, link descriptions can be used in links, in descriptions where services expose more runtime information about resources by providing link descriptions for themselves, or in both places. The following example shows hows both of these mechanisms can be used in one representation, which is based on Atom and AtomPub . It also shows the two cases just described, with the first link description being one to "self", while the second link description is describing a different resource.

The link to the feed itself is augmented with a URI Template described in , which allows a client to understand that individual feed pages can be requested (assuming the consumer understands the "concept" identifiers for the described variables). The link to the entry is an augmented typed Web Link described in , which allows a consumer to understand that even though "edit" links typically can be followed via GET, PUT, and DELETE, this particular link should only be followed using a PUT request. It is worth noting that link descriptions of course can become outdated between the time such a link description has been received by a client, and the time a client actually sends a request when following such a link (this is the case both for "self" links and links to other resources). This means that clients should never depend on a link description being correct, because for example the "edit" link description shown above might start allowing DELETE requests again at any point in time.

One of the defining principles of many services provided on the Web is that they expose linked resources, so that clients can follow the links in order to accomplish application goals. "Web Linking" establishes a framework of typed links, allowing resources to expose typed links, which then can be followed by clients. While this framework allows clients to select links based on their "types", it does not provide any support for additional runtime information about possible interactions with such a link. As outlined in the AtomPub example above, a link typed as "edit" (as defined and registered by AtomPub) can be followed by using HTTP GET, PUT, or DELETE, and the typed link by itself cannot provide the additional information that some resource may allow updates, but disallows deletion. "Link Hints" (a draft currently under development) provide a framework for runtime hints that can be used to indicate information that might be made available by the link target resource itself, but ahead of time. For example, a link hint would be able to indicate on an "edit" link that the resource only allows PUT requests, which is something that could also be discovered by sending an HTTP request and getting an HTTP Allow header in the response. However, link hints can save overhead by avoiding round trips, and they also allow to minimize the chances of sending requests that will not succeed. While link hints can help to avoid overhead and drive client behavior, they are strictly optional. There should be no functional difference of what a client can achieve by using or ignoring link hints; they simply expose information that otherwise would be more costly to acquire. Since it is potentially expensive to provide link hints in representations (because they may involve interpreting access control data), it is perfectly possible that services provide link hints only on some requests. For example, it would be possible for a service to serve http://example.com/collection as a collection of items with embedded "edit" links, whereas http://example.com/collection?hints=true would result in a representation that would contain additional link hints for each individual "edit" link. This kind of design is outside of the scope of this memo, but it is helpful to illustrate the fact that link hints are nothing but optimizations. Currently, there is an overlap in what "Link Hints" define, and what is proposed in this memo. While both drafts propose a way how to represent link hints/descriptions, the "Link Hints" draft does not address URI Templates. Removing this overlap is captured in the "Open Issues" and should be addressed during the further development and/or alignment of both drafts.

Following links is the basic principle of interacting with resources on the web, but in many cases, interactions with resources require clients to provide information in addition to just using a fixed URI in a request. In these cases, information can be provided in any way supported by the interaction protocol, and in case of HTTP, this often means that information is either embedded in the URI, in HTTP headers, and/or in the body of the request. For the first case, "URI Template" provides a standard that allows servers and clients to exchange information about the URIs that a service accepts. The standard specifies "a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion." It allows servers to publish their expectation how a URI should be created by substituting variables with values. Consider the following URI Template:

http://www.example.com/collection{?pagesize,page}

This URI Template allows clients to expand it with two variables assignments, to end up with a concrete URI such as the following:

http://www.example.com/collection?pagesize=10&page=42

URI Templates cover the aspect of starting with a template with variables in it, assigning values to these variables, and then expanding the template into a URI that can be used for sending a request. URI Templates make no assumptions or statements about the meaning or value range of the variables, except for those aspects which are required to cover the process of expanding the template. In particular, for the example given above, there is no indication that the values are supposed to be positive integers (the data type), nor is there any indication that the service may apply certain limits such as a maximum page size (which may change depending on which paged resource is being accessed). As a side note, even if this basic type information was known, URI template expansion could still result in URIs that would not yield successful requests, such as when asking for a page that is beyond the number of pages that a collection has (in a given page size). The goal of Link Descriptions as defined in this memo is to allow servers to expose a description that provides support both at development time (when a developer uses a media type that uses URI Templates) and at runtime (when a client wants to use a URI template as part of its application flow). Link Descriptions are intended to provide additional information that is not communicated by publishing URI Templates alone. The additional information is both targeted at machines, and at humans. On the human-oriented Web, a Template Description can be seen as the equivalent of a help or documentation page that is linked to from a form, where users can learn more about the values they are supposed to submit within the form. As a concrete example, a link to a collection like the one above may be exposed in a link description as follows:

]]>

This link description allows a URI Template's variables to be described in terms of URI-identified concepts. By using such a model, it is possible to use global names for URI Template parameters, and bind them to URI Template variable names. The template and the variables int the example above are not specific for any HTTP method, i.e. this link description does not define any constraints in terms of how to use URI Templates differently for different HTTP methods. But this is possible, and is covered in the detailed description below. The concept URIs are pure identifiers for the purpose of link descriptions; i.e. they should not be considered dereferenceable, and the assumption is that consumers of link descriptions will only use them to match discovered concepts against known concepts. This design does not prohibit to make concept URIs dereferenceable, but this is outside of the scope of link descriptions.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 .

The general idea of link descriptions is that they allow to annotate links (URIs or URI Templates) with context that clients can use when they choose to follow those links. In the XML syntax, descriptions are deliberately designed to follow the design of Atom's popular <link> element, which serves as a blueprint for links in many media types. The main idea of link descriptions is to provide a framework which provides services that want to serve this kind of description with a starting point. If these services want, they can reuse the representations for this framework, in whole or in part.

As mentioned already, "Link Hints" as currently defined overlap with the concepts proposed in this memo. However, this memo goes further than link hints by not just providing hints for URIs, but for URI Templates as well. Based on the current link hint model defined in that draft, a link hint is a name/value pair, where the name is either a registered link hint, or a URI. The allowed value space depends on the link hint, and in the current model, structured values must be encoded in JSON. A link may have any number of link hints, but only one link hint with a given name.

When a link description uses a URI Template, then this template will very likely contain variables. Variables can be described when using Link Descriptions. For each variable contained in the URI Template, it is possible to use the following description methods: Concept: It is possible to associate a variable with a concept, so that media types and applications can make an association between the concepts they are defining/exposing, and how they are exposed in URI Templates. Concepts can be identified by using a URI as an identifier. This specification defines no interactions with this URI identifier and makes no assumption about possible representations, should this URI be dereferenceable and yield some representation. Documentation: Documentation constructs can be associated with variables, which allows Link Descriptions to attach human-readable information to individual variables. The documentation model has the ability to support multi-lingual human-oriented documentation. For the purpose of this specification, the term "description" should be interpreted loosely. Description aspects such as concepts and documentation do not prescribe a description framework; they simply provides a structure how to deliver these descriptions, so that clients can use them when making decisions about which links to follow, and how to follow them.

Link Descriptions are based on a URI Template, and add descriptive elements that allow publishers of URI Templates to describe the URI Template as a whole, and to add individual descriptions of all variables in the template. The idea of Link Descriptions is that they are made available at design time and/or at runtime, so that clients encountering URI Templates as part of HTTP services can find more information about the template itself. Ideally, every URI template exposed in an HTTP service should be accompanied by a link to a Link Description. In those XML-based HTTP services where URI Templates are exposed in XML attributes named "hreft", the suggestion is to add a link to the corresponding Link Description in an "hrefd" XML attribute.

As mentioned in , most of the descriptions in this spec do not prescribe a specific description framework. While variables () can be described with a built-in vocabulary of datatypes, most other descriptions are either for human consumption, or do rely on some external description framework. To attach these descriptions to both the template as a whole, and individual variables, this specification reuses the "appinfo" and "documentation" elements from XML Schema Part 1. These elements carry a "source" attribute, which is used "to supplement the local information." For example, when a description of a variable is done formally using a specific description framework, this would best translate to use appinfo elements, and to add an identifier to them which would identify the description framework in question. As a result, any client knowing this particular description framework would be able to interpret the variable description in the Link Description.

An interaction is described by including the URI Template itself, and optionally adding documentation and/or appinfo elements to add human- or machine-readable descriptions.

A variable is described by specifying the variable name. Variables can refer to a "concept" associated with a variable, which can by identified by URI. This specification makes no provision how such a concept is defined and/or described/documented, but it allows consumers of a Link Description to match their understanding of certain concepts to those identifiers, which then establishes a binding between the concept, and the variable it has been bound to. A variable can have a default value, in which case the assumption is that excluding this variable from a request has the same effect as including it with the default value. Since Link Descriptions are runtime concepts, however, there is no guarantee that a service might not use a different value between the time when the Link Description was retrieved, and the time when a request based on it is being sent. Variable descriptions can optionally add documentation and/or appinfo elements to add human- or machine-readable descriptions.

...

... All the example use "documentation" elements which are entirely optional, but can help to improve the usefulness of link descriptions for developers.

...

The Internet media type for a Link Description document is application/ldesc+xml (using the "+xml" suffix as defined and registered by RFC 6839 ). application ldesc+xml none profile The "profile" link relation allows "resource representations to indicate that they are following one or more profiles. A profile is defined not to alter the semantics of the resource representation itself, but to allow clients to learn about additional semantics (constraints, conventions, extensions) that are associated with the resource representation, in addition to those defined by the media type and possibly other mechanisms." If the application/ldesc+xml media type is use with a profile parameter, this refers to a profile as defined by , making it easier for extensions of the link description media type to identify themselves. Same as encoding considerations of application/xml as specified in . This media type has all of the security considerations described in , plus those listed in . N/A RFC XXXX Applications that publish descriptions of URI Interactions. none No specific file extension proposed, but as a general rule, XML data often uses ".xml" as the file extension. TEXT Erik Wilde <dret@berkeley.edu> COMMON none Erik Wilde <dret@berkeley.edu> IESG

The link relation type below will be registered by IANA per Section 6.2.1 of RFC 5988 : Relation Name: ldesc Description: Linking to a resource that can be used as a link description for requesting runtime information about a particular context's interaction affordances. Reference: RFC XXXX Notes: Link Descriptions can be used in all scenarios where clients want to create requests that represent a query into the context resource. The media type of the context resource and the media type of the link description resource are not constrained by this specification.

Note to RFC Editor: Please remove this section before publication. This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in RFC 6982 . The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist. According to RFC 6982, "this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit".

...

If and how to use profiles (example in ); if profile use is recommended, define a suggested profile URI for other specs to use? How to handle variables in Level 4 templates that are supposed to have composite values? If a template is refined in an incremental process (such as for example faceted search services), does it make sense to be able to add a "back" link and/or "home" link, so that clients can find the "most general" version easily? How does this interact with "faceted search" scenarios? Does incremental refinement of URI Template Descriptions somehow nicely and naturally map into faceted search scenarios? Is there a concept of how Template Descriptions (and thus URI Templates) can be reused? Should there be an inclusion facility or something along those lines? If so, what's the model for that? Initial thoughts on possibilities can be found on this page Should there be some recommended link relation to use when linking to a Template Description from within the context of a URI Template? While currently everything is defined in XML, providing alternative serializations (JSON and RDF) might be an interesting thing to consider. Should there be a "Template" HTTP header field, listing a resource's URI Template and, optionally, containing a link to a description resource for it (basically, a rel="ldesc" link)? What about using CURIE for the variable names, thus eliminating the need for separate concept URIs? This would need prefix bindings, which in XML would just up as regular namespace declarations. It might quite be a bit more problematic in non-XML contexts, such as serving a URI Template in an HTTP header. Support for "HTTP Prefer" might need another link hint, so that clients know which preferences they might use.

Note to RFC Editor: Please remove this section before publication.

Adding "Template" HTTP header field as an open issue. Adding CURIEs as one possible convention to use for variable names, so that "Concept URIs" are embedded in the template itself, and not external. Adding "HTTP Prefer" as an open issue. Updated author address.

An earlier variation of a similar idea was published as "Template Descriptions" . However, since this earlier draft was exclusively focusing on interactions with links driven by URI Templates , instead of looking at links in general, it was sufficiently distinct to start a new draft, instead of evolving the existing one.

This document standardizes five new media types -- text/xml, application/xml, text/xml-external-parsed-entity, application/xml- external-parsed-entity, and application/xml-dtd -- for use in exchanging network entities that are related to the Extensible Markup Language (XML). This document also standardizes a convention (using the suffix '+xml') for naming media types outside of these five types when those media types represent XML MIME (Multipurpose Internet Mail Extensions) entities. [STANDARDS-TRACK]

mnot@pobox.com http://www.mnot.net/

rfsayre@boswijck.com http://boswijck.com

This document specifies Atom, an XML-based Web content and metadata syndication format.

A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet. [STANDARDS-TRACK] This memo specifies "HTTP Link Hints", a mechanism for annotating Web links to HTTP(S) resources with information that otherwise might be discovered by interacting with them. Note to Readers: This draft should be discussed on the apps-discuss mailing list; see [apps-discuss]. World Wide Web Consortium

Massachusetts Institute of Technology 77 Massachusetts Avenue Cambridge MA 02139 USA +1-617-253-5702 +1-617-258-5999 timbl@w3.org http://www.w3.org/People/Berners-Lee/

Day Software

5251 California Ave., Suite 110 Irvine CA 92617 USA +1-949-679-2960 +1-949-679-2972 fielding@gbiv.com http://roy.gbiv.com/

Adobe Systems Incorporated

345 Park Ave San Jose CA 95110 USA +1-408-536-3024 LMM@acm.org http://larry.masinter.net/

Applications uniform resource identifier URI URL URN WWW resource A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. This specification defines three types of syndicated Web feeds that enable publication of entries across one or more feed documents. This includes "paged" feeds for piecemeal access, "archived" feeds that allow reconstruction of the feed's contents, and feeds that are explicitly "complete". [STANDARDS-TRACK] The Atom Publishing Protocol (AtomPub) is an application-level protocol for publishing and editing Web resources. The protocol is based on HTTP transfer of Atom-formatted representations. The Atom format is documented in the Atom Syndication Format. [STANDARDS TRACK] This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. A content media type name sometimes includes partitioned meta- information distinguished by a structured syntax to permit noting an attribute of the media as a suffix to the name. This document defines several structured syntax suffixes for use with media type registrations. In particular, it defines and registers the "+json", "+ber", "+der", "+fastinfoset", "+wbxml" and "+zip" structured syntax suffixes, and provides a media type structured syntax suffix registration form for the "+xml" structured syntax suffix. This document is not an Internet Standards Track specification; it is published for informational purposes. This specification defines the 'profile' link relation type that allows resource representations to indicate that they are following one or more profiles. A profile is defined not to alter the semantics of the resource representation itself, but to allow clients to learn about additional semantics (constraints, conventions, extensions) that are associated with the resource representation, in addition to those defined by the media type and possibly other mechanisms. Interactions with many resources on the Web are driven by and/or can be described by URI Templates. RFC 6570 says that "a URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion." This specification defines Template Descriptions, a schema and a media type that can be used to document and describe a URI Template by supporting descriptive markup that allows variables to be associated with documentation (human-oriented) and/or descriptions (machine- oriented). Template Descriptions can be used by media types (by inclusion or by reference) that seek to make URI Templates self-describing, without having to create their own representation. This document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature.</t><t> The process in this document is offered as an experiment. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. The authors of this document intend to collate experiences with this experiment and to report them to the community. This specification defines an HTTP header field that can be used by a client to request that certain behaviors be employed by a server while processing a request.

Thanks for comments and suggestions provided by Dmitry Limonov.