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 Abstract 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. Status of This Memo 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 Notice Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. Svensson & Verborgh Expires September 10, 2019 [Page 1] Internet-Draft Negotiating Profiles in HTTP March 2017 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 2. Terminology and Implementation Options . . . . . . . . . . . 3 2.1. A Note on Terminology . . . . . . . . . . . . . . . . . . 3 2.2. Other Implementation Options Considered . . . . . . . . . 3 3. Client and Server Behaviour . . . . . . . . . . . . . . . . . 6 3.1. Accept-Profile Header Syntax . . . . . . . . . . . . . . 7 3.2. Profile Header Syntax . . . . . . . . . . . . . . . . . . 7 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 6.1. Accept-Profile HTTP Header Registration . . . . . . . . . 11 6.2. Profile HTTP Header Registration . . . . . . . . . . . . 11 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 8.1. Normative References . . . . . . . . . . . . . . . . . . 12 8.2. Informative References . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 1. Introduction 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 Svensson & Verborgh Expires September 10, 2019 [Page 2] Internet-Draft Negotiating Profiles in HTTP March 2017 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. 1.1. Requirements Language 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 [RFC2119]. 2. Terminology and Implementation Options 2.1. A Note on Terminology 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) [DSP] -, XML Schema documents [XSD] and RDF Shapes expressed in SHACL [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 [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] [rachelandheery]. 2.2. Other Implementation Options Considered 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: 1. The HTTP "Link" header [RFC 5988] [RFC5988] offers various possibilities to relate a resource to other resources, e. g. to alternate representations having different media types or content in another language. One of the specified relationtypes is "profile" [RFC 6906] [RFC6906], that offers the possibility to associate a resource with a document describing "additional semantics that can be used to process a resource representation, Svensson & Verborgh Expires September 10, 2019 [Page 3] Internet-Draft Negotiating Profiles in HTTP March 2017 such as constraints, conventions, extensions, or any other aspects that do not alter the basic media type semantics." This header can be used for a client to specify what profile it would the requested resource to conform to. This option offers no possibility to use q-values and thus does not allow the UA and the server to properly negotiate which profile to use. Example: HEAD /some/other/resource HTTP/1.1 Accept: text/turtle;q=0.9,application/rdf+xml;q=0.5 Link: ; rel="profile" HTTP/1.1 200 OK Content-type: text/turtle Link: ; rel="profile" Figure 1 2. Another way to use the Link" header directly, without using the "profile" relation. It is unclear if this usage can be applied in an http request, where the value of the link's context IRI is undefined unless the client uses the "anchor" parameter to specify that, and even when the client explicitly sets an anchor it is not specified if the relation between the anchor IRI and the related resource remains the same when a server redirects a client to another resource using e. g. the HTTP 301 or 303 status codes. This could be solved by letting the UA request a preferred profile by using the "Link" header together with the "profile" relation as described above and having the server specify which profile the returned resource conforms to and also link to alternate representations of the same resource. Currently, there is no target attribute linking to a resource's profile. In order to enable this, this document registers the "profile" attribute to be used with the "Link" header. Svensson & Verborgh Expires September 10, 2019 [Page 4] Internet-Draft Negotiating Profiles in HTTP March 2017 Example: GET some/resource HTTP/1.1 Accept: application/xml Link: ; rel="profile" HTTP/1.1 200 OK Content-Type: application/xml Link: rel="self"; type="application/xml" profile="", rel="alternate"; type="application/xml"; profile=" Figure 2 3. A further way to convey profile information is through the http Accept and Content-Type header field as specified in RFC 7231 [RFC7231]. 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= Figure 3 If this is possible depends on the media type. Of the media types commonly used for linked data, only two registrations in the IANA Media Type Registry [IANAMEDIAREG] foresee the use of profiles: application/xhtml+xml [RFC3236] and application/ld+json [JSONLD]. E. g. neither application/rdf+xml [RFC3870] nor text/ turtle [TURTLE] do not mention the use of profiles. 4. A fourth option would be to use the http "Prefer" and "Preference-Applied" headers as specified in RFC 7240 [RFC7240]. This approach has two disadvantages. The first is - as with the "Link" header, that there is no possibility to work with q-values. The second one is that the only way for a server to state that it ignored the preference stated by the client is to omit sending a "Preference-Applied" header. For the client - however - it is not clear if the "Preference-Applied" header is absent because the server did not honour the preference, or if it Svensson & Verborgh Expires September 10, 2019 [Page 5] Internet-Draft Negotiating Profiles in HTTP March 2017 is because the server did not understand the "Prefer" header in the first place. This could be solved by making it mandatory to send a "Link: rel=profile" header when answering to a request with a "Prefer: profile=''" header in it. This solution requires that a client evaluates two different headers in order to find a response to its request for a specific profile, which would make client implementation more complicated. Example: GET /some/resource HTTP/1.1 Accept: text/turtle Prefer: profile= HTTP/1.1 200 OK Content-Type: text/turtle Preference-Applied: profile= Figure 4 3. Client and Server Behaviour 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. Svensson & Verborgh Expires September 10, 2019 [Page 6] Internet-Draft Negotiating Profiles in HTTP March 2017 3.1. Accept-Profile Header Syntax 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 [XMLSCHEMA]) -- 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 [RFC7230] 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 [RFC5234] and the rules defined in Section 3.2 of RFC 7230 [RFC7230]. The definitions of "URI-reference" and "weight" are imported from RFC 7230 [RFC7230] and RFC 7231 [RFC7231], 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 3.2. Profile Header Syntax 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 [XMLSCHEMA]) -- a list of pairs of URI references separated by whitespace similar to the syntax used in the Svensson & Verborgh Expires September 10, 2019 [Page 7] Internet-Draft Negotiating Profiles in HTTP March 2017 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 [RFC5234] and the rules defined in Section 3.2 of RFC 7230 [RFC7230]. The definition of "URI-reference" is imported from RFC 7230 [RFC7230]. Profile header syntax Profile = "Profile" ":" "<" URI-reference ">" | "<" URI-reference "0x20" URI-reference *( "0x20" URI-reference "0x20" URI-reference) ">" Figure 6 4. Examples 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. Svensson & Verborgh Expires September 10, 2019 [Page 8] Internet-Draft Negotiating Profiles in HTTP March 2017 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: Response: HTTP/1.1 200 OK Content-Type: application/xml Profile: Link: rel="self"; type="application/xml"; profile="", rel="alternate"; type="application/xml"; profile="" 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: ; q=0.8, ; q=0.5 Response: HTTP/1.1 200 OK Content-Type: application/rdf+xml Profile: Link: rel="self"; type="application/rdf+xml"; profile="", rel="alternate"; type="application/rdf+xml"; profile="" Figure 8 Svensson & Verborgh Expires September 10, 2019 [Page 9] Internet-Draft Negotiating Profiles in HTTP March 2017 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: Response: HTTP/1.1 406 Not acceptable Content-Type: application/xhtml+xml Accept-Profile: 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: Response: HTTP/1.1 200 OK Content-Type: application/xml Profile: Figure 10 5. Acknowledgements This is the place to have YOUR NAME prominently displayed! Svensson & Verborgh Expires September 10, 2019 [Page 10] Internet-Draft Negotiating Profiles in HTTP March 2017 6. IANA Considerations 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 [RFC3864]. [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] [RFC5988] so the parameter "profile" will be seen as a link-extension. 6.1. Accept-Profile HTTP Header Registration The Accept-Profile header should be added to the permanent registry of message header fields (see RFC 3864 [RFC3864]), taking into account the guidelines given by HTTP/1.1 RFC 7231 [RFC7231]". Header Field Name: Accept-Profile Applicable Protocol: Hypertext Transfer Protocol (HTTP) Status: Standard Author/Change controller: IETF Specification document(s): RFC XXXX 6.2. Profile HTTP Header Registration The Profile header should be added to the permanent registry of message header fields (see RFC 3864 [RFC3864]), taking into account the guidelines given by HTTP/1.1 RFC 7231 [RFC7231]". Header Field Name: Profile Applicable Protocol: Hypertext Transfer Protocol (HTTP) Status: Standard Author/Change controller: IETF Specification document(s): RFC XXXX Svensson & Verborgh Expires September 10, 2019 [Page 11] Internet-Draft Negotiating Profiles in HTTP March 2017 7. Security Considerations 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. 8. References 8.1. Normative References [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., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, . [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, . 8.2. Informative References [DSP] Nilsson, M., "Description Set Profiles: A constraint language for Dublin Core Application Profiles", 2008, . [IANAMEDIAREG] IANA, "Media Types", 2015, . [JSONLD] Sporny, M., Kellogg, G., and M. Lanthaler, "JSON-LD 1.0: A JSON-based Serialization for Linked Data", 2015, . Svensson & Verborgh Expires September 10, 2019 [Page 12] Internet-Draft Negotiating Profiles in HTTP March 2017 [rachelandheery] Heery, R. and M. Patel, "Application Profiles: Mixing and Matching Metadata Schemas", 2000, . [RFC3236] Baker, M. and P. Stark, "The 'application/xhtml+xml' Media Type", RFC 3236, DOI 10.17487/RFC3236, January 2002, . [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, DOI 10.17487/RFC3864, September 2004, . [RFC3870] Swartz, A., "application/rdf+xml Media Type Registration", RFC 3870, DOI 10.17487/RFC3870, September 2004, . [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010, . [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, DOI 10.17487/RFC6906, March 2013, . [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, DOI 10.17487/RFC7240, June 2014, . [SHACL] Knublauch, H. and A. Ryman, "Shapes Constraint Language (SHACL): W3C First Public Working Draft 08 October 2015", 2014, . [TURTLE] Prud'hommeaux, E. and G. Carothers, "RDF 1.1 Turtle", 2014, . [XMLBEANS] Apache Software Foundation, "XMLBeans", 2014, . [XMLSCHEMA] Gao, S., Sperberg-McQueen, C., and H. Thompson, "W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures", 2012, . Svensson & Verborgh Expires September 10, 2019 [Page 13] Internet-Draft Negotiating Profiles in HTTP March 2017 [XSD] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML Schema Part 1: Structures Second Edition", 2004, . Authors' Addresses Lars G. Svensson Deutsche Nationalbibliothek Adickesallee 1 Frankfurt 60322 Germany Phone: +49 69 1525 1752 Email: l.svensson@dnb.de Ruben Verborgh Ghent University - imec Sint-Pietersnieuwstraat 41 Ghent 9000 Belgium Phone: +32 9 331 49 10 Email: ruben.verborgh@ugent.be Svensson & Verborgh Expires September 10, 2019 [Page 14]