HTTP Working Group Koen Holtman, TUE Internet-Draft Andrew Mutz, Hewlett-Packard Expires: May 15, 1998 Ted Hardie, NASA NIC The Alternates Header Field draft-ietf-http-alternates-01.txt STATUS OF THIS MEMO This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. 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". To learn the current status of any Internet-Draft, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Distribution of this document is unlimited. Though this work originated in the HTTP working group and comments should continue to be directed to that group, the authors expect that the proposed header will have considerable use outside of HTTP. Discussions about its potential uses outside of HTTP are particularly sought by the authors. Send comments to the HTTP working group at . Discussions of the working group are archived at . General discussions about HTTP and the applications which use HTTP should take place on the mailing list. ABSTRACT This document proposes a header, Alternates, which is intended to provide a common method for Internet-based application protocols to indicate that a particular resource exists in multiple forms. The Alternates header provides a machine-readable indication of the bases on which the different forms vary and how the the recipient of the header can select among them. 1 Introduction Where a particular content provider has created more than one representation of a specific resource, the provider may wish to indicate the existance of the different representations, or "variants", to those who might want to select among them. Rather than consuming bandwidth by sending all available variants, the content provider can employ the Alternates header to indicate what variants are available, the bases on which the variants differ, and how to select a specific variant. The functionality of the Alternates header is similar to that of the Multipart/Alternative MIME type[Ref] where the Multipart/Alternative object has all external message bodies. The Alternates header differs in that it does not rank the alternatives. Instead, it provides information which allows the recipient to decide among them based on the provider's estimation of their quality, local capabilities, and preferences. 2 Terminology The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as described in RFC 2119 [Ref]. 3 Notation The version of BNF used in this document is taken from [Ref], and many of the nonterminals used are defined in [Ref]. 4.1 Definition The Alternates header field describes all available variants for a specific resource. The description for each variant includes an URI from which this variant can be retrieved. Alternates = "Alternates" ":" variant-list variant-list = 1#( variant-description ; see section 5 | fallback-variant | negotiation-directive ) fallback-variant = "{" <"> URI <"> "}" negotiation-directive = token [ "=" ( token | quoted-string ) ] An example is Alternates: {"http://x.org/paper.1" 0.9 {type text/html} {language en}}, {"http://x.org/paper.2" 0.7 {type text/html} {language fr}}, {"ftp://x.org/pub/paper.3" 1.0 {type application/postscript} {language en}}, {"http://x.org/paper.html.en"}, x=y A variant list may contain multiple differing descriptions of the same variant. This can be convenient if the variant uses conditional rendering constructs, or if the variant resource returns multiple representations using a multipart media type. Only one fallback-variant field may be present. If the variant selection algorithm of the user agent finds that all variants described by variant-description fields are unacceptable, then it SHOULD choose the fallback variant, if present, as the best variant. This specification does not define any specific negotiation directives for the Alternates header field. User agents SHOULD ignore all negotiation directives they do not understand. If a proxy receives an Alternates header field with an unknown negotiation directive, it SHOULD, whenever possible, forward the response towards the user agent instead of trying to take part in a negotiation process itself. 4.2 Length of variant lists As a general rule, variant lists in Alternates header fields should be as short as possible. The use of multiple differing descriptions of the same variant is supported, but should be limited to those resources which cannot easily be expressed without the use of condititional constructs or multipart media types. It is expected that a typical negotiable resource will have 2 to 10 variants. In situations where many more variants are available, more sophisticated methods than the Alternates header field should be used. 5 Variant descriptions 5.1 Syntax A variant can be described in a machine-readable way with a variant description. variant-description = "{" <"> URI <"> source-quality *variant-attribute"}" source-quality = qvalue variant-attribute = "{" "type" media-type "}" | "{" "charset" charset "}" | "{" "language" 1#language-tag "}" | "{" "length" 1*DIGIT "}" | extension-attribute extension-attribute = "{" extension-name extension-value "}" extension-name = token extension-value = *( token | quoted-string | LWS | extension-specials ) extension-specials = and "}"> Examples are {"http://x.org/paper.2" 0.7 {type text/html} {language fr}} {"http://x.org/paper.5" 0.9 {type text/html} {length 1002}} {"http://x.org/paper.1" 0.001} The various attributes which can be present in a variant description are covered in the subsections below. Each attribute may appear only once in a variant description. 5.2 URI The URI attribute gives the URI of the resource from which the variant can be retrieved with a GET request. It must be an absolute URI, in order to allow for this header to be passed to other MIME transport protocols without transformation. The variant resource may vary the content it sends (on the Cookie request header field, for example), but SHOULD NOT engage in content negotiation itself. 5.3 Source-quality The source-quality attribute gives the quality of the variant, as a representation of the negotiable resource, when this variant is rendered with a perfect rendering engine on the best possible output medium. If the source-quality is less than 1, it often expresses a quality degradation caused by a lossy conversion to a particular data format. For example, a picture originally in JPEG form would have a lower source quality when translated to the XBM format, and a much lower source quality when translated to an ASCII-art variant. Note however, that degradation is a function of the source; an original piece of ASCII-art may degrade in quality if it is captured in JPEG form. Servers should use the following table a guide when assigning source quality values: 1.000 perfect representation 0.900 threshold of noticeable loss of quality 0.800 noticeable, but acceptable quality reduction 0.500 barely acceptable quality 0.300 severely degraded quality 0.000 completely degraded quality In the source-quality values, servers should not account for the size of the variant and its impact on transmission and rendering delays; the size of the variant should be stated in the length attribute and any size-dependent calculations should be done by a variant selection algorithm in the user agent. 5.4 Type, charset, language, and length The type attribute of a variant description carries the same information as its Content-Type response header field counterpart defined in [1], except for any charset information, which MUST be carried in the charset attribute. For, example, the header field Content-Type: text/html; charset=ISO-8859-4 has the counterpart attributes {type text/html} {charset ISO-8859-4} The language and length attributes carry the same information as their Content-* response header field counterparts in [1]. The length attribute, if present, MUST thus reflect the length of the variant alone, and not the total size of the variant and any objects inlined or embedded by the variant. Though all of these attributes are optional, it is often desirable to include as many attributes as possible, as this will increase the quality of the negotiation process. Note: A server is not required to maintain a one-to-one correspondence between the attributes in the variant description and the Content-* header fields in the variant response. For example, if the variant description contains a language attribute, the response does not necessarily have to contain a Content-Language header field. If a Content-Language header field is present, it does not have to contain an exact copy of the information in the language attribute. 5.5 Extension-attribute The extension-attribute allows future specifications to incrementally define new dimensions of negotiation, and eases content negotiation experiments. User agents conforming to this specification SHOULD treat all variants with extension attributes they do not recognize as unusable. Proxies SHOULD NOT do any negotiation processing for a response if an extension attribute unknown to them is present in the variant list. They SHOULD forward the response unchanged towards the user agent instead. The extension names "features" and "description" are reserved by this specification for use in transparent content negotiation [4]. 6 Use of the Alternates header field This section defines conventions and guidelines for the use of the Alternates header field. 6.1 Use accompanying a variant A resource provider may provide a recipient with a particular variant together with an Alternates header field which notifies the recipient that multiple variants are available. An HTTP example of such an exchange is: HTTP/1.1 200 OK Date: Tue, 11 Jun 1996 20:05:31 GMT Content-Type: text/html Content-Language: en Last-Modified: Mon, 10 Jun 1996 10:01:14 GMT Content-Length: 5327 Alternates: {"http://x.org/paper.1" 0.9 {type text/html} {language en}}, {"http://x.org/paper.2" 0.7 {type text/html} {language fr}}, {"http://x.org/paper.3" 1.0 {type application/postscript} {language en}} Content-Location: http://x.org/paper.1 Vary: * Expires: Thu, 01 Jan 1980 00:00:00 GMT Cache-Control: max-age=604800 A paper about .... In this response, the Content-Location header field tells the user agent which variant was included. The Vary, Expires, and Cache-Control header fields ensure proper handling of the response by HTTP/1.0 and HTTP/1.1 caches. When detecting that an Alternates header field is present, a user agent MAY choose to use a variant selection algorithm to select the best variant of the negotiable resource. If the best variant is not the same one as the one identified by the Content-Location header field, the user agent MAY use the URI indicated for the best version to obtain it. 6.2 Use when a variant is not present A content provider may also inform a potential recipient that multiple variants exist without providing any particular variant. In such exchanges, the content provider should omit the Content-Location header. A message body MAY accompany the headers used to convey this information. An SMTP example of such an exchange is: 220 ESMTP spoken here EHLO mail.x.org 250-mail.y.org Hello mail.x.org, pleased to meet you MAIL FROM: lists@mail.x.org 250 lists@mail.x.org... Sender ok RCPT TO: exploder-lists@mail.y.org 250 exploder-lists@mail.y.org... Recipient ok DATA 354 Enter mail, end with "."on a line by itself To: exploder-lists@mail.y.org From: lists@mail.x.org Date: Tue, 11 Jun 1996 20:02:21 GMT Content-Type: text/htm Content-Length: 227 Alternates: {"http://x.org/paper.1" 0.9 {type text/html} {language en}}, {"http://x.org/paper.2" 0.7 {type text/html} {language fr}}, {"http://x.org/paper.3" 1.0 {type application/postscript} {language en}} Vary: * <h1>Multiple Choices:</h1> <ul> <li><a href=paper.1>HTML, English version</a> <li><a href=paper.2>HTML, French version</a> <li><a href=paper.3>Postscript, English version</a> </ul> . 250 XAA13385 Message accepted for delivery On receipt of such a message, the user agent MAY use a variant selection algorithm to select the best variant of the negotiable resource, and retrieve this variant. For compatibility with user agents which are not capable of handling the Alternates header field, any message body should normally allow the user to select the best variant manually. 6.3 Use of redirection to optimize availability HTTP and related protocols allow an origin server to indicate that a resource is available but is not at the URL by which it was requested. As an optimization, the Alternates header can be used in combination with this redirection to allow an origin server to indicate the availability of variant resources without including a resource or excluding user agents which do not support the Alternates header. By providing the fallback variant's URL in the location header, the origin server can ensure that all user agents will have access to that variant, while the full list of variants is provided in the Alternates header for more capable user agents. An example of this usage in an HTTP response is: HTTP/1.1 302 Moved Temporarily Date: Tue, 11 Jun 1996 20:05:31 GMT Content-Type: text/html Alternates: {"http://x.org/paper.1" 0.9 {type text/html} {language en}}, {"http://x.org/paper.2" 0.7 {type text/html} {language fr}}, {"http://x.org/paper.3" 1.0 {type application/postscript} {language en}} Location: http://x.org/paper.1 Content-Length: 67 This document is available <a href="http://x.org/paper.1">here</a>. Note the use of a Location header field instead of a Content-Location header field. On receipt of such a response, user agents which understand the Alternates header SHOULD use a variant selection algorithm to select the best variant of the negotiable resource, and retrieve this variant. When the Alternates header is used in protocols which do not provide redirection, the method outlined in section 6.1 should be used when the content provider wishes to ensure at least one variant is made available to all recipients. 6.4 User agent guidelines Summarizing the three sections above, if an Alternates header field is present in the response, then * a recipient SHOULD use its variant selection algorithm to choose and retrieve the best variant if a Content-Location header field is absent, * and MAY use its variant selection algorithm to choose and retrieve the best variant if a Content-Location header field is present. 6.4.1 Interactive user agent guidelines For user agents which provide direct interaction with users, the following guidelines apply: 1. The user agent SHOULD make available though its user interface some indication that the resource being displayed is a negotiated resource instead of a plain resource. It SHOULD also allow the user to examine the variant list included in the Alternates header field. Such a notification and review mechanism is needed because of privacy considerations, see section 7.1. 2. If the user agent shows the URI of the displayed information to the user, it SHOULD be the negotiable resource URI, not the variant URI that is shown. This encourages third parties, who want to refer to the displayed information in their own documents, to refer to the negotiable resource as a whole, rather than to the variant resource which happens to be shown. This abstract referencing is vital for the interoperability of content across sites. The user agent SHOULD also, however, provide a means for reviewing the URI of the particular variant which is currently being displayed. 3. Similarly, if the user agent stores a reference to the displayed information for future use, for example in a hotlist, it SHOULD store the negotiable resource URI, not the variant URI. 6.4.2 Non-interactive user agent guidelines Devices like printers, fax machines, or text processors may also be the recipients of the Alternates header. Since such devices typically function without direct interaction with a human operator, the user agent guidelines given above do not directly apply. Many of the same principals, however, can be employed. For example, a device which generates a log report or cover sheet which contains information about the information received could provide the same information described above in that form. 6.5 Negotiation on content encoding Negotiation on the content encoding of a response is orthogonal to content negotiation based on the Alternates header field. 6.6 Role of proxies This specification does not define mechanisms by which proxies can use the Alternates header field, but does allow other specifications to define such mechanisms. To ensure extensibility of the Alternates header field, this specification does however define, in section 4.1 and section 5.5, that a proxy should not engage in a negotiation process when encountering an Alternates header field which has a component unknown to it. 7 Security and privacy considerations 7.1 Variants hiding the source of displayed material. The Variants header may be used to allow a user to select among variants available from more than one location. In such cases, users may make incorrect asssumptions about the origin of particular resources. The guidlines given in 6.4 alleviate this problem to a degree, but some implementors of the Alternates header may wish to provide further warnings or filters. 7.2 User agent choices revealing information of a private nature The automatic selection and retrieval of a variant by a user agent will reveal a preference for this variant to the server. A malicious service author could provide a page with `fake' negotiability as a means of obtaining privacy-sensitive information. Such a plot would, however, be visible to an alert victim if the list of available variants and their properties is reviewed through a mechanism as described in section 6.4.1. 7.3 Security holes revealed by negotiation Malicious servers could use content negotiation as a means of obtaining information about security holes which may be present in user agents. 8 Acknowledgments Work on HTTP content negotiation has been done since at least 1993. This specification builds on an earlier incomplete specification of the Alternates header field recorded in [2]. The authors wish to thank the individuals who have contributed to the work on content negotiation in the HTTP working group, including Brian Behlendorf, Daniel DuBois, Martin J. Duerst, Roy T. Fielding, Jim Gettys, Yaron Goland, Dirk van Gulik, Graham Klyne, Scott Lawrence, Larry Masinter, Jeffrey Mogul, Henrik Frystyk Nielsen, Frederick G.M. Roeber, Paul Sutton, and Klaus Weide. 9 References [1] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, and T. Berners-Lee. Hypertext Transfer Protocol -- HTTP/1.1. RFC 2068, HTTP Working Group, January 1997. [2] Roy T. Fielding, Henrik Frystyk Nielsen, and Tim Berners-Lee. Hypertext Transfer Protocol -- HTTP/1.1. Internet-Draft draft-ietf-http-v11-spec-01.txt, HTTP Working Group, January 1996. [3] T. Berners-Lee, R. Fielding, and H. Frystyk. Hypertext Transfer Protocol -- HTTP/1.0. RFC 1945. MIT/LCS, UC Irvine, May 1996. [4] K. Holtman, A. Mutz. Transparent Content Negotiation in HTTP. Internet-Draft draft-ietf-http-negotiation-04.txt, HTTP Working Group, September 1997. [5] S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. RFC 2119. Harvard University, March 1997. 10 Authors' addresses Koen Holtman Technische Universiteit Eindhoven Postbus 513 Kamer HG 6.57 5600 MB Eindhoven (The Netherlands) Email: koen@win.tue.nl Andrew H. Mutz Hewlett-Packard Company 1501 Page Mill Road 3U-3 Palo Alto CA 94304, USA Fax +1 415 857 4691 Email: mutz@hpl.hp.com Ted Hardie NASA NIC Mail Stop 204-14 NASA Ames Research Center Moffett Field, CA 94035 Email: hardie@nic.nasa.gov 11 Appendix: Example of a variant selection algorithm A negotiating user agent will choose the best variant from a variant list with a variant selection algorithm. This appendix contains an example of such an algorithm. The inputs of the algorithm are a variant list from an Alternates header field, and an agent-side configuration database, which contains - a collection of quality values assigned to media types, languages, and charsets for the current request, following the model of the corresponding HTTP/1.1 [1] Accept- header fields, - a table which lists `forbidden' combinations of media types and charsets, i.e. combinations which cannot be displayed because of some internal user agent limitation. The output of the algorithm is either the best variant, or the conclusion that none of the variants are acceptable. 11.1 Computing overall quality values As a first step in the variant selection algorithm, the overall qualities associated with all variant descriptions in the list are computed. The overall quality Q of a variant description is the value Q = round5( qs * qt * qc * ql * qa ) where rounds5 is a function which rounds a floating point value to 5 decimal places after the point. It is assumed that the user agent can run on multiple platforms: the rounding function makes the algorithm independent of the exact characteristics of the underlying floating point hardware. The factors qs, qt, qc, ql, and qa are determined as follows. qs Is the source quality factor in the variant description. qt The media type quality factor is 1 if there is no type attribute in the variant description. Otherwise, it is the quality value assigned to this type by the configuration database. If the database does not assign a value, then the factor is 0. qc The charset quality factor is 1 if there is no charset attribute in the variant description. Otherwise, it is the quality value assigned to this charset by the configuration database. If the database does not assign a value, then the factor is 0. ql The language quality factor is 1 if there is no language attribute in the variant description. Otherwise, it is the highest quality value the configuration database assigns to any of the languages listed in the language attribute. If the database does not assign a value to any of the languages listed, then the factor is 0. qa The quality adjustment factor is 0 if the variant description lists a media type - charset combination which is `forbidden' by the table, and 1 otherwise. As an example, if a variant list contains the variant description {"paper.2" 0.7 {type text/html} {language fr}} and if the configuration database contains the quality value assignments types: text/html;q=1.0, type application/postscript;q=0.8 languages: en;q=1.0, fr;q=0.5 then the variant selection algorithm will compute the overall quality for the variant description as follows: {"paper.2" 0.7 {type text/html} {language fr}} | | | | | | V V V round5 ( 0.7 * 1.0 * 0.5 ) = 0.35000 With same configuration database, the variant list {"paper.1" 0.9 {type text/html} {language en}}, {"paper.2" 0.7 {type text/html} {language fr}}, {"paper.3" 1.0 {type application/postscript} {language en}} would yield the following computations: round5 ( qs * qt * qc * ql * qa ) = Q --- --- --- --- --- paper.1: 0.9 * 1.0 * 1.0 * 1.0 * 1.0 = 0.90000 paper.1: 0.7 * 1.0 * 1.0 * 0.5 * 1.0 = 0.35000 paper.3: 1.0 * 0.8 * 1.0 * 1.0 * 1.0 = 0.80000 11.2 Determining the result Using all computed overall quality values, the end result of the variant selection algorithm is determined as follows. If all overall quality values are 0, then the best variant is the fallback variant, if there is one in the Alternates header field, else the result is the conclusion that none of the variants are acceptable. If at least one overall quality value is greater than 0, then the best variant is the variant which has the description with the highest overall quality value, or, if there are multiple variant descriptions which share the highest overall quality value, the variant of the first variant description in the list which has this highest overall quality value. 11.3 Ranking dimensions Consider the following variant list: {"paper.greek" 1.0 {language el} {charset ISO-8859-7}}, {"paper.english" 1.0 {language en} {charset ISO-8859-1}} It could be the case that the user prefers the language "el" over "en", while the user agent can render "ISO-8859-1" better than "ISO-8859-7". The result is that in the language dimension, the first variant is best, while the second variant is best in the charset dimension. In this situation, it would be preferable to choose the first variant as the best variant: the user settings in the language dimension should take precedence over the hard-coded values in the charset dimension. To express this ranking between dimensions, the user agent configuration database should have a higher spread in the quality values for the language dimension than for the charset dimension. For example, with languages: el;q=1.0, en-gb;q=0.7, en;q=0.6, da;q=0, ... charsets: ISO-8859-1;q=1.0, ISO-8859-7;q=0.95, ISO-8859-5;q=0.97, unicode-1-1;q=0, ... the first variant will have an overall quality of 0.95000, while the second variant will have an overall quality 0.70000. This makes the first variant the best variant. Expires: May 15, 1998