| Internet Engineering Task Force | L. Svensson |
| Internet-Draft | Deutsche Nationalbibliothek |
| Intended status: Standards Track | R. Verborgh |
| Expires: September 10, 2019 | Ghent University – imec |
| March 9, 2017 |
Negotiating Profiles in HTTP
draft-svensson-accept-profile-00
This document defines two new HTTP headers "Content-Profile" and "Accept-Profile" that enable User Agents and hosts to indicate and negotiate the profile used for representing a specific resource. In this context, a profile is a description of the structural and/or semantic constraints of a group of documents in addition to the syntactical interpretation provided by more generic MIME types. Examples of profiles include Dublin Core Application Profiles, XML Schemata, and RDF Shape Expressions. This document further defines and registers the "profile" parameter for the HTTP "Link" header and suggests a best practice for the use of the new headers together with the "Link" header for the purposes of performing content negotiation and pointing clients to alternate representations.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 10, 2019.
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
This document defines two new HTTP headers that enable User Agents (UAs) and hosts to indicate and negotiate the profile used to represent a specific resource. On the Web, resources are identified with HTTP(S) URIs. In many cases, it can be desired to have multiple representations of a resource to accomodate different UAs or use cases. When a UA issues a GET request for a specific URI, the UA and the server negotiate which of the available representations best suit the UA's needs and capabilities. Typically a UA specifies preferences by setting appropriate HTTP headers, e. g. Accept for media type, Accept-Language for content language or Accept-Charset for character encoding.
In many cases, there are several ways to describe a resource within the scope of the media type. In the case of XML documents, for instance, the same content can be encoded using one of several DTDs or XML Schemas, whereas in RDF there is a wide choice of RDF vocabularies (classes and properties) available to describe resources of the same type. When a UA initiates a request, e.g., a GET request to retrieve or a PUT request to create or replace a resource, neither the UA nor the server have any possibility to exchange information on how the transmitted resource will be structured precisely. This document proposes a solution by defining the HTTP headers Accept-Profile and Profile.
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.
In the context of this proposal, a "profile" is a document that expresses the structural and/or semantic constraints of other documents. Examples of "profile" in this context include, but are not limited to, Dublin Core application profiles - formally expressed in Description Set Profiles (DSP) -, XML Schema documents and RDF Shapes expressed in SHACL. How those profiles are used by consuming applications is beyond the scope of this proposal, but typical use cases are validation of data received from another system and the automated creation of objects from received data as in Java XMLBeans. The choice of the term "profile"was derived from the term "Application Profile" which the Dublin Core community defines as "schemas which consist of data elements drawn from one or more namespaces, combined together by implementors, and optimised for a particular local application" [Rachel & Heery].
A number of options were considered when specifying how schema negotiation could be implemented. Below is a record of those options listing the consequences of using them:
Example:
HEAD /some/other/resource HTTP/1.1 Accept: text/turtle;q=0.9,application/rdf+xml;q=0.5 Link: <http://example.com/profile-1>; rel="profile" HTTP/1.1 200 OK Content-type: text/turtle Link: <http://example.com/profile-1>; rel="profile"
Figure 1
Example:
GET some/resource HTTP/1.1 Accept: application/xml Link: <urn:example:schema-1>; rel="profile" HTTP/1.1 200 OK Content-Type: application/xml Link: rel="self"; type="application/xml" profile="<urn:example:schema-1>", rel="alternate"; type="application/xml"; profile="<urn:example:schema-2>
Figure 2
Example:
GET /some/resource HTTP/1.1 Accept: text/turtle;q=0.9;profile="urn:example:profile-1", text/turtle;q=0.7;profile="urn:example:profile-2"; HTTP/1.1 200 OK Content-Type: text/turtle;profile=<urn:example:profile-2>
Figure 3
Example:
GET /some/resource HTTP/1.1 Accept: text/turtle Prefer: profile=<urn:example:schema> HTTP/1.1 200 OK Content-Type: text/turtle Preference-Applied: profile=<urn:example:schema>
Figure 4
The "Accept-Profile" and "Profile" header fields can be sent by both the UA and the server. The "Accept-Profile" header is used to specify one or more profiles the Agent can accept, whereas the "Profile" header tells the other Agent according to which profile the payload of the message is structured. So can a UA issuing a request for a resource specify that it prefers persons to be described using foaf, but that the BBC Core ontology is also acceptable, and that it can only accept text/turtle, by setting the "Accept" and "Accept-Profile" header fields appropriately. When the server answers, it would set the "Content-Type" and "Profile" header fields. Likewise, a UA sending an XML document to a server would set the the "Content-Type" and the "Profile" header fields. If the server cannot process the specified profile, it would answer with an http 406 status code and possibly a list of acceptable profiles.
An "Accept-Profile" and "Profile" header field do not contain the actual profile but instead points to it using a URI. As long as the URI is only used to denote the profile, the URI does not need to point to an actual document but can be considered opaque. If the parties involved agree on a profile definition, the profile can be identified with e. g. a URN or an info-URI. When a protocol-based URI, such as an FTP- or an HTTP-URI is used, however, it is RECOMMENDED that it dereference to a document containing the profile definition.
The "Accept-Profile" header field is used to specify one or more content profiles the issuing agent can accept for processing. Each profile is identified by a URI reference or -- e. g. in the case of namespace-specific XML schemas (cf. 4.3.2 of XML Schema 1.1-1) -- a list of pairs of URI references separated by whitespace similar to the syntax used in the xsi:schemaLocation attribute. If several profiles are specified, quality values as defined in Section 5.3.1 of RFC 7230 can be used to assign a relative "weight" to the preference. Exactly how that weight is used to determine the best representation is beyond the scope of this specification.
A request without any "Accept-Profile" header field implies that the user agent will accept content conforming to any profile. If the header field is present in a request and the origin server cannot provide a representation that conforms to the specified profile, it can either honour the header field by sending a 406 (Not Acceptable) response or disregard the header field by treating the response as if it is not subject to content negotiation. If the the origin server chooses to disregard the header field and the profile the content conforms to is known, the origin server SHOULD send a "Profile" header indicating that profile together with the payload.
Figure 5 describes the syntax (Augmented Backus-Naur Form) of the header fields, 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.
Accept-Profile header syntax
Accept-Profile = "Accept-Profile" ":" (profile-value) *("," profile-value)
profile-value = "<" URI-reference ">" [weight] |
"<" URI-reference "0x20" URI-reference
*("0x20" URI-reference "0x20" URI-reference) ">"
[weight]
Figure 5
The "Profile" header field is used to specify a profile the payload in the message conforms to. The profile is identified by a URI reference or -- e. g. in the case of namespace-specific XML schemas (cf. 4.3.2 of XML Schema 1.1-1) -- a list of pairs of URI references separated by whitespace similar to the syntax used in the xsi:schemaLocation attribute. If a client uses the "Accept-Profile" header to specify one or more profiles it is willing to accept and a server does not use the "Profile" header to specify which profile the returned content conforms to, the client MAY process the returned content as it deems fit.
If a client uses the "Profile" header field to indicate the profile the payload conforms to (e. g. in an HTTP POST or PUT request) and the server cannot process content conforming to that profile, the server SHOULD send a 406 (Not acceptable) response together with an "Accept-Profile" header field (including q-values) to indicate the profiles it can process. Reasons for not sending a 406 response in such a case might be that the the processing of the message payload leads to an internal server error. If in such a case the server does not implement profile negotiation, the server is more likely to return a 500 (Internal server error) response instead of 406.
Figure 6 describes the syntax (Augmented Backus-Naur Form) of the header fields, using the grammar defined in RFC 5234 and the rules defined in Section 3.2 of RFC 7230. The definition of "URI-reference" is imported from RFC 7230.
Profile header syntax
Profile = "Profile" ":" "<" URI-reference ">" |
"<" URI-reference "0x20" URI-reference
*( "0x20" URI-reference "0x20" URI-reference) ">"
Figure 6
The following examples highlight the exchange of profile information between a client and a server. For clarity, the examples only contain minimal information, i. e. only the relevant headers are included and message bodies are ignored.
A client requests an XML document conforming to a specific XML schema. The XML schema is identified by "urn:example:schema:e-commerce-payment".
Request: GET /some-resource HTTP/1.1 Accept: application/xml Accept-Profile: <urn:example:schema:e-commerce-payment> Response: HTTP/1.1 200 OK Content-Type: application/xml Profile: <urn:example:schema:e-commerce-payment> Link: rel="self"; type="application/xml"; profile="<urn:example:schema:e-commerce-payment>", rel="alternate"; type="application/xml"; profile="<urn:example:schema:e-commerce-accounting>"
Figure 7
A client requests an RDF/XML document conforming to one of two RDF Shapes (http://example.com/shapes/shape-1 and http://example.com/shapes/shape-2). It uses q-values to express a preference for shape-1, the server, however, prefers to deliver in shape-2.
Request:
GET /some-resource HTTP/1.1
Accept: application/rdf+xml
Accept-Profile: <http://example.com/shapes/shape-1>; q=0.8,
<http://example.com/shapes/shape-2>; q=0.5
Response:
HTTP/1.1 200 OK
Content-Type: application/rdf+xml
Profile: <http://example.com/shapes/shape-2>
Link: rel="self";
type="application/rdf+xml";
profile="<http://example.com/shapes/shape-2>",
rel="alternate";
type="application/rdf+xml";
profile="<http://example.com/shapes/shape-3>"
Figure 8
A client PUTs a turtle document conforming to the RDF Shape http://example.com/shapes/shape-1. The server answers that it can only process documents conforming to http://example.com/shapes/shape-2.
Request: PUT /some-resource HTTP/1.1 Profile: <http://example.com/shapes/shape-1> Response: HTTP/1.1 406 Not acceptable Content-Type: application/xhtml+xml Accept-Profile: <http://example.com/shapes/shape-2>
Figure 9
A client requests an XML document where the elements in namespace urn:example:namespaces:ns1 must conform to XML schema http://example.com/schema/schema-1 and the elements in namespace urn:example:namespaces:ns2 must conform to XML schema http://example.com/schema/schema-2. The server answers that it can supply the document as requested.
Request: GET /some-resource HTTP/1.1 Accept-Profile: <urn:example:namespaces:ns1 http://example.com/schema/schema-1 urn:example:namespaces:ns2 http://example.com/schema/schema-2> Response: HTTP/1.1 200 OK Content-Type: application/xml Profile: <urn:example:namespaces:ns1 http://example.com/schema/schema-1 urn:example:namespaces:ns2 http://example.com/schema/schema-2>
Figure 10
This is the place to have YOUR NAME prominently displayed!
This specification defines two header field for the Hypertext Transfer Protocol (HTTP) that have been registered with the Internet Assigned Numbers Authority (IANA) following the "Registration Procedures for Message Header Fields" RFC 3864. [TO BE REMOVED: This registration should take place at the following location: http://www.iana.org/assignments/message-headers/message-headers.xhtml] Further, it defines a parameter for the "Link" header. There is no registry for link-param except for the values listed in [RFC5988] so the parameter "profile" will be seen as a link-extension.
The Accept-Profile header should be added to the permanent registry of message header fields (see RFC 3864), taking into account the guidelines given by HTTP/1.1 RFC 7231".
Header Field Name: Accept-Profile
Applicable Protocol: Hypertext Transfer Protocol (HTTP)
Status: Standard
Author/Change controller: IETF
Specification document(s): RFC XXXX
The Profile header should be added to the permanent registry of message header fields (see RFC 3864), taking into account the guidelines given by HTTP/1.1 RFC 7231".
Header Field Name: Profile
Applicable Protocol: Hypertext Transfer Protocol (HTTP)
Status: Standard
Author/Change controller: IETF
Specification document(s): RFC XXXX
The Accept-Profile and Profile headers may expose information that a User Agent or an origin server would prefer to not publish. In such a case, a server can simply stop exposing the header, in which case HTTP interactions would be back to the level of standard HTTP (i.e., with no indication what profiles the UA or the server prefer and/or can handle.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC5234] | Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008. |
| [RFC7230] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014. |
| [RFC7231] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014. |