Indicating, Discovering, Negotiating, and Writing Profiled Representations

Any given web resource can typically be represented in a variety of ways. For example, the same information could be rendered according to different media types, say, as XML or JSON. But in many cases, variations in representation other than those inherent to a given media type are also possible. For example, the same structured data could be rendered in XML according to different XML Schema. Or the same RDF graph could be expressed on the basis of different vocabularies. This dimension of variability regarding representations that goes beyond media types has been acknowledged for quite some time. For example, in 2000, the Dublin Core Metadata Initiative (DCMI) introduced "Application Profiles" to explicitly acknowledge that the same metadata can be represented in various ways and defined them as "schemas which consist of data elements drawn from one or more namespaces, combined together by implementers, and optimised for a particular local application" .

Inspired by the term used in to refer to this extra dimension of variability, this document uses the term "profile" to mean a description of structural and/or semantic constraints on representations of resources that apply in addition to the constraints inherently indicated by their MIME type: Profiles can be dependent on a media type. For example, this is the case for XML, with constraints being expressed using an XML Schema. This is also the case for JSON that offers a wide range of options regarding the use of tree structure, keys, and value types. In these cases, the meaning of the term "profile" intended by this document coincides with the use of the same term in . Profiles can be independent of media type. For example, this is the case for RDF graphs that can be rendered according to various media types, while constraints can be expressed in a manner that is independent of media type, among others, using SHACL. In these cases, the meaning of the term "profile" intended by this document is a slight extension of the one intended by .

When it comes to HTTP interactions, profiles have received little attention despite their de facto existence and the added-value they can bring for building rich applications. Such applications benefit from knowledge regarding the nature of a representation that a client obtains from a server, that a client sends to a server, and that a server is willing to accept from a client, beyond what is conveyed by the representation's MIME type. These applications are also be helped by an ability to discover representations rendered according to a profile they can handle, or, optimally, an ability to explicitly request a rendering according to a preferred profile. A common approach to handle profiles is to register them as a media type, dedicated to the combination of an actual media type and a profile of it. Media types that illustrate this approach include "application/activity+json", "application/calendar+json", and "application/calendar+xml. This approach allows conveying all necessary profile information in HTTP interactions, e.g. using the "Accept" and "Content-Encoding" HTTP headers and the "type" attribute for web links. As such it supports indicating, discovering, and content negotiating (in the media type dimension) for profiled representations. This registration-based approach may be feasible for profiles that are expected to be very widely used but is not practical in case support for many different profiles is required. Also, the "calendar" examples illustrate that the registration-based approach is not ideal when a profile applies to multiple media types. And, the "activity" example illustrates that the approach supports indicating what the major ingredient of a profiled representation is (i.e. the ActivityStreams Vocabulary) but becomes problematic when indications are also needed regarding additional vocabularies used in representations. Another approach to handle profiles leverages the ability provided by to register parameters when registering a media type. Some media types have used this capability to register an attribute dedicated to conveying profiles of the media type. For example, for "application/ld+json" the "profile" parameter has been registered for this purpose. The approach provides flexibility for handling many profiles, including ones that are not yet known when registering the media type. It also supports indicating, discovering, and content negotiating (in the media type dimension) for profiled representations using common approaches. But the approach remains problematic because it ties profile information to a media type, depends on registering a parameter to convey profile information when registering a new media type, and, realistically, on the registration of the same parameter name (i.e. "profile" as suggested in ) for all media types for which registrants deem that conveying profile information is important. Additionaly, discourages registering parameters for previously registered media types, making it highly questionable that a uniform attribute to convey profile information across all media types could retroactively be defined. Recognizing the importance of profiles and the problems with the aforementioned approaches to handle them, specifications have started to introduce alternative approaches to express information about resource representation profiles in HTTP interactions: introduces the "profile" link relation type that is generally applicable for indicating the profile of a resource representation that is sent by a client to a server or by a server to a client. introduces a capability to make profiled representations discoverable via web links by using the "formats" attribute to express the profile of a linked resource. and provide a concise overview of the approaches introduced by and , to respectively indicate and discover the profile of resource representations. specifies a generally applicable approach to negotiate for representations that conform to a profile preferred by a user agent. shows how servers can convey which profiled representations they are able to accept from user agents.

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. This specification uses the terms "link context" and "link target" as defined in . These terms respectively correspond with "Context IRI" and "Target IRI" as used in . Although defined as IRIs, in common scenarios they are also URIs. In the examples provided in this document, links in the HTTP "Link" header are shown on separate lines in order to improve readability. Note, however, that as per Section 3.2 of , line breaks are not allowed in values for HTTP headers; only whitespaces and tabs are supported as seperators.

As per , a web link with a "profile" link relation type can be used to indicate the profile of a representation that is exchanged in HTTP interactions. shows a client requesting a representation from a server and shows the server responding. The response includes a "Link" header () that contains a link with the "profile" relation type. The link target <http://purl.org/dc/terms/> indicates the profile of the response body (not shown). shows a client submitting a representation to a server, using the same approach to express the profile to which that representation complies. describes how a server can convey the profiles it supports for representations that are submitted by a user agent.

; rel="profile" Content-Length: 23364 Connection: close ... ]]>

; rel="profile" Content-Length: 23364 Connection: close ... ]]> In some cases organisations use separate servers to perform content negotiation and to deliver resources, e. g. when static content is served through content delivery networks. The servers that perform the content negotiation interact with the client requesting the resource and then typically refer to the correct representation using a 303 redirect. In those cases the servers that deliver the representations are not profile aware and thus cannot add the appropriate "Link" headers to the response. Instead the server performing the negotiation will have to supply that information. This is done by adding an "anchor" attribute pointing to the representation the link header refers to. shows the response to a where the server performing the negotiation redirects the client to the resource specified in the "Location" header and by using the same URI in the "anchor" attribute of the "Link" header indicates that the information in the "Link" header does not apply to this response but to the resource redirected to.

; rel="profile" ; anchor="https://static.example.org/other/resource" ... ]]>

The link hints capability introduced in , can be leveraged by a server to make profiled representations discoverable by including a "formats" attribute on web links. shows a response to the client request of in which the server uses this technique. The "Link" header indicates the profile of the returned representation but also points at two alternative representations, each of which conforms to another profile.

; rel="profile" , ; rel="alternate" ; type="application/xml" ; formats="http://example.org/our_internal_xml_profile" , ; rel="alternate" ; formats="http://example.org/our_community_profile" Content-Length: 23364 Connection: close ... ]]>

describes two approaches for conveying profile information in HTTP interactions that make it possible to negotiate for profiled representations by applying content negotiation in the media type dimension. It also indicates the restricted applicability of these approaches, in both cases a result of their direct dependence on the media type registration process. This section describes an approach that applies content negotiation in a dimension that it was previously not applied to. The profile negotiation approach introduced here is generally applicable for resource representations, irrespective of media type. These are its core aspects: In order to allow a user agent to inform a server about its preferences regarding profiles for resource representations, the "Accept-Profile" HTTP header introduced here is used. A user agent can specify several profiles and use quality indicators (q-values) to indicate preferences. In order to allow a server to express its support for profile negotiation the "Vary" HTTP header is used, in this case, with the "Accept-Profile" value. In order to allow a server to convey the profile of a representation delivered to a user agent, rather than introducing a server-side counterpart to the client-side "Accept-Profile" header, the existing "profile" link approach introduced by is used. If a representation conforms to multiple profiles, a distinct "profile" link is used per profile; the order in which these links are provided has no relevance. In order to allow a server to convey the profiles it supports, web links with the "formats" link hint introduced in are used to convey the profiles of the link target resources. This approach uniformely applies to reponses to HTTP HEAD/GET/PUT/POST/PATCH. Throughout the profile negotiation approach, a profile MUST be referred to by a URI. This is the case for the content of the "Accept-Profile" HTTP header, for the target of web links with the "profile" link relation, and for the content of the "formats" link hint for web links.

Profile negotiation uses the content negotiation processes described in Section 3.4 of RFC 7231 but applies them to the profile dimension. Both proactive negotiation and reactive negotiation for profiles can be supported by servers. Both are described in more detail in the remainder of this section. In profile negotiation, a profile MUST be referred to by a URI that, from here onwards, is named a profile URI. If the profile URI is dereferencable it SHOULD lead to a document that details the profile. If the profile URI is not dereferencable (e.g. a URN or an info-URI) facilities SHOULD be available to allow user agents and servers to understand their meaning, e.g. community registries of profiles.

In proactive profile negotiation, the user agent uses the "Accept-Profile" HTTP header to inform the server about the agent's preference regarding profiles to be used for representing a resource in the server's response. In case a user agent wants to express a preference for a single profile, the value of the header is that profile's URI. In case a user agent wants to express a preference for multiple profiles, the value of the header is a list containing each profile's URI, seperated by commas. Alternatively, multiple "Accept-Profile" HTTP headers can be used, each conveying a single profile URI. Quality indicators (q-values) MAY be used to rank profile preferences. The order in which profile URIs are conveyed or the duplicate mentioning of a same profile URI MUST NOT be interpreted as significant. A server that supports proactive profile negotiation for the resource that a user agent interacts with: MUST include a "Vary" HTTP header containing the value "accept-profile" in its response to the user agent. MUST include a "Link" HTTP header containing a link with the "profile" relation type that has as link target the profile URI of the resource representation returned to the user agent. In case the representation conforms to additional profiles known to the server, such a "profile" link SHOULD be included for each. SHOULD convey the availability of alternate profiled representations of the resource by using the link hint approach described in . These requirements for servers that support proactive profile negotiation also apply when: The user agent expressed a profile preference in its request by using an "Accept-Profile" header but the server cannot return a representation that conforms to a preferred profile. The user agent did not express a profile preference using an "Accept-Profile" header in its request. A user agent SHOULD interpret the abscence of a "Vary" HTTP header with an "accept-profile" value in a response from a server as the lack of support for profile negotiation for the resource the user agent interacts with. A server SHOULD consider representations that do not conform to any of the profiles listed by a user agent in an "Accept-Profile" header as non-interpretable by the agent. As such, honoring the user agent preferences in the profile dimension SHOULD take precedence over honoring content negotiation in other dimensions. In a user agent requests an RDF serialization from a server and expresses preference for two media types using the "Accept" header and two profiles using the "Accept-Profile" header. It uses q-values to express a preference for the profile with profile URI <http://example.org/shapes/shape-1> over the one with profile URI <http://example.org/shapes/shape-2>.

shows the server's response to the request of . By means of the "Vary" header, the server expresses support for negotiation in both the media type and profile dimensions. The "profile" link with link target <http://example.org/shapes/shape-2> indicates that the server was able to honor the user agent's second profile preference. Another "profile" link shows that the delivered representation also conforms to a profile with profile URI <http://example.org/shapes/shape-3>. Furthermore, using an "alternate" link, the server indicates support for another profile with <http://example.org/shapes/shape-4> as profile URI. Note that, even if the user agent does not express profile preferences using the "Accept-Profile" header and the server's "Vary" header would be the same, the "Link" header would still include a "profile" link to indicate the profile of the representation returned by the server.

; rel="profile" , ; rel="profile" , ; rel="alternate" ; type="text/turtle" ; formats="http://example.org/shapes/shape-4" Content-Length: 8724 Connection: close ... ]]> shows the response to the request of in case the server supports profile negotiation for the resource at hand but can not return a representation that conforms to a profile preferred by the user agent. The server has chosen to nevertheless return a representation that conforms to profile <http://example.org/shapes/shape-4>, which is not among the ones preferred by the user agent. The server also reveals the existence of a representation that conforms to profile <http://example.org/shapes/shape-5>. The server could also choose not to return a default representation in which case it would return a "406 Not Acceptable" HTTP response code and no response body. It would not provide any "profile" links but might use "alternate" links with a "formats" attribute to indicate the existence of supported profiles.

; rel="profile" , ; rel="alternate" ; type="text/turtle" ; formats="http://example.org/shapes/shape-5" Content-Length: 6333 Connection: close ... ]]> shows the response to the request of in case the server does not support profile negotiation for the resource <http://example.org/document>. It does support negotiation in the media type dimension and has honoured one of the user agent's preferences with that regard, as can be seen by the "Vary" and "Content-Type" headers.

In reactive profile negotiation, the user agent selects the profiled representation that best meets its preferences on the basis of a list of possible representations it obtains from the server. A server that supports reactive profile negotiation MUST provide such a list of supported profiled representation as a set of links in the "Link" header. Each of these links: SHOULD have the "alternate" relation type. MUST use the "formats" link hint to convey the profile URI of the profile to which the resource that is the link target conforms. SHOULD use the "allow" link hint to convey the HTTP methods that are supported by the resource that is the link target. shows a user agent issuing a HTTP HEAD on a resource in order to determine whether profiled representations are available for it. shows the response of a server that supports reactive profile negotiation. By means of "alternate" links in the "Link" header, the server indicates support for two profiled representations for the resource at hand, and, for each, indicates the URI at which they can be accessed, as well as their respective profile URIs, media types, and supported HTTP methods. On the basis of this response, the client can decide whether any of the linked resources conform to a preferred profile, and, if so, access the respective link target. shows the response to an HTTP HEAD issued on the link target <http://example.org/bibrecord/1/DC> of the first "alternate" link.

; rel="alternate" ; type="application/xml" ; formats="http://purl.org/dc/terms/" ; allow="HEAD,GET,PATCH" , ; rel="alternate" ; formats="http://id.loc.gov/ontologies/bibframe/" ; allow="HEAD,GET" Content-Length: 200 Connection: close ]]>

; rel="profile" , ; rel="alternate" ; formats="http://id.loc.gov/ontologies/bibframe/" ; allow="HEAD,GET" Allow: HEAD, GET, PATCH Accept-Patch: application/xml-patch+xml Content-Length: 458 Connection: close ]]>

describes the syntax of the "Accept-Profile" HTTP header, using the grammar defined in RFC 5234 and the rules defined in Section 3.2 of RFC 7230. The definitions of "URI-reference" and "weight" are imported from RFC 7230 and RFC 7231, respectively.

" [weight] | accept-value-ext ]]>

A user agent that wants to submit a profiled representation to a server can use the reactive negotiation approach to determine the nature of a server's support with this regard. A server that allows user agents to submit profiled representations SHOULD follow the directions for reactive negotiation described in . A client that submits a representation that complies to a profile that was not advertised by the server by means of the reactive negotiation approach, SHOULD assume that the server is not able to process it. A server that fails a submission request due to receiving a payload with a profile that it does not support MUST respond with a "422 Unprocessable Entity" HTTP status code and SHOULD use the approach described in to convey profiles that are supported. Continuing from , shows a user agent issuing a HTTP PATCH against resource <http://example.org/bibrecord/1/DC> in order to update it. It uses the "Content-Encoding" header to convey the XML Patch media type of its message body and a link with a "profile" relation type in the "Link" header to indicate the profile to which it conforms. shows the server's response, indicating that the patch was applied successfully; the server returns the updated representation as message body.

; rel="profile" Accept: application/xml Content-Length: 321 Connection: close ... ]]>

; rel=profile" , ; rel="alternate" ; formats="http://id.loc.gov/ontologies/bibframe/" ; allow="HEAD,GET" Allow: HEAD, GET, PATCH Accept-Patch: application/xml-patch+xml Content-Length: 592 Connection: close ... ]]> If, in , the user agent would have issued an HTTP PATCH on resource <http://example.org/bibrecord/1/DC> indicating that the profile URI of the patch was <http://id.loc.gov/ontologies/bibframe/>, the response would have a 422 HTTP status code to express that the profile is not supported by the resource at hand. Such a response is shown in .

; rel="alternate" ; type="application/xml" ; formats="http://purl.org/dc/terms/" ; allow="HEAD,GET,PATCH" Content-Length: 110 Connection: close ... ]]>

This memo requires IANA to register the Accept-Profile HTTP header defined in in the appropriate IANA registry: Header Field Name: Accept-Profile Applicable Protocol: Hypertext Transfer Protocol (HTTP) Status: Informational Author/Change controller: IETF Specification document(s): this document

Many thanks to our colleagues for feedback: Enno Meijers, Michael L. Nelson