]>

Las Vegas NV United States of America dev@liksu.com

Web and Internet Transport HTTP link preview unfurl HEAD Open Graph structured fields Many applications display a "preview card" for a link: a title, a short description and an image. Today this information is obtained by retrieving the full HTML representation of the linked resource and extracting metadata from it. This forces origin servers to generate complete pages for clients that need only a few short strings. This document defines the Preview HTTP response header field, a Structured Field that carries link preview metadata, and describes how it can be delivered in responses to HEAD requests so that preview generators can obtain it without the origin server generating the representation. About This Document Discussion of this document is expected to take place on the HTTP Working Group mailing list (ietf-http-wg@w3.org). Open issues are listed in .

Introduction When a URI is shared in a messaging application, a social network, a chat tool or a collaboration product, the application commonly shows a preview card for it. The card is built from metadata published by the resource owner, most often using the Open Graph protocol , which places meta elements in the head of an HTML document. To read those elements, a preview generator retrieves the resource with GET, although it needs only a few hundred bytes of the result. This has costs at every step:

• The origin server generates the representation. For a dynamically generated page, this usually includes database queries and template rendering.
• The representation is transferred over the network and can be stored by intermediaries along the way.
• The preview generator waits for the representation and parses HTML to find the metadata.

Many generators stop reading once the head has been parsed or a size limit is reached, or request only the beginning of the representation with a Range header field (). This reduces the amount of data transferred, but often not the work of the origin server: unless the server streams its responses, the whole page has typically been generated before the first byte is sent. Publishing the metadata in a separate document, as oEmbed and similar mechanisms do, avoids parsing HTML but requires a second request and a second resource to maintain. The cost is multiplied when the same link is previewed by many independent generators. Decentralized social networks are a documented example: each server that receives a post fetches the linked page itself, so a single popular post can cause hundreds or thousands of near-simultaneous requests to the origin . Origin servers that want to reduce this load today have to recognize preview generators by their User-Agent strings and serve them special content. This is fragile, undocumented and different for every generator. This document defines the Preview response header field (), which carries preview metadata as a Structured Field . Because the information is carried in a header field, it can be delivered in a response to a HEAD request (). An origin server can then answer preview generators from a lightweight handler, and generators can build a card from a single HEAD exchange.

Goals and Non-Goals The goals of this specification are:

• to let an origin server provide preview metadata without generating the full representation of a resource;
• to let a preview generator obtain that metadata with a single HEAD request, reducing server work, network transfer and latency at the same time;
• to remain fully backward compatible: a server or generator that does not implement this specification continues to work as it does today;
• to cover resources that have no HTML representation at all, such as PDF documents, media files or API responses.

It is not a goal of this specification to replace the Open Graph protocol, to define how a preview card is rendered, or to define a complete vocabulary of resource metadata. Only the small set of properties that are needed for a typical preview card is defined.

Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. This document uses the following terminology from to specify syntax and parsing: Dictionary, String, Display String, Integer, Boolean and Parameters. The terms "origin server", "target URI", "representation", "selected representation" and "intermediary" are used as defined in . A "preview generator" is any client that retrieves information about a resource in order to display a preview of a link to that resource. A preview generator can be a server (for example, the backend of a messaging service) or a user agent (for example, a messaging application running on the device of the user who shares the link).

The Preview Response Header Field The Preview response header field describes the resource identified by the target URI for the purpose of displaying a preview of a link to it. It is a Structured Header Field () whose value is a Dictionary. The following example shows a Preview field with a title, a description, an image and a site name. It is sent as four field lines, which recipients combine into one Dictionary as described in : The same value can be sent in a single field line, with the members separated by commas. Text values that contain characters outside the printable ASCII range are sent as Display Strings (). For example, the Ukrainian word "Pryvit" ("Hello") written in Cyrillic script is sent as follows:

Dictionary Members This section defines the members of the Preview Dictionary. All members are optional. A sender SHOULD include at least the "title" member, unless it sends the "nopreview" member.

title The "title" member carries the title of the resource as it is intended to be displayed in a preview. Its value MUST be a String or a Display String. It is equivalent to the og:title property of .

description The "description" member carries a short description of the resource. Its value MUST be a String or a Display String. It is equivalent to the og:description property.

image The "image" member identifies an image that represents the resource. Its value MUST be a String containing a URI-reference (). A relative reference is resolved as described in . It is equivalent to the og:image property. The following Parameters are defined for the "image" member:

width:

A positive Integer giving the width of the image in pixels. Equivalent to og:image:width.

height:

A positive Integer giving the height of the image in pixels. Equivalent to og:image:height.

type:

A String or a Token containing the media type of the image (for example, "image/jpeg"). Equivalent to og:image:type.

alt:

A String or Display String containing a textual alternative for the image. Equivalent to og:image:alt.

Providing "width" and "height" allows a preview generator to lay out a card before the image has been retrieved.

site The "site" member carries the name of the site or service that the resource belongs to. Its value MUST be a String or a Display String. It is equivalent to the og:site_name property.

nopreview The "nopreview" member, when its value is the Boolean true, indicates that the resource owner prefers that no rich preview be displayed for links to this resource. In serialized form, this is the bare key: When "nopreview" is true, the other members of the field carry no meaning and recipients ignore them. A value of false has the same effect as the absence of the member. describes how preview generators react to it. This member allows an origin server to decline preview generation cheaply, without serving the representation to every preview generator. It expresses a preference about previews shown to people who share or receive a link. It is independent of directives for search engines, such as "nosnippet" in robots meta tags or the X-Robots-Tag field, and is not a substitute for mechanisms that control crawling or indexing.

Error Handling If the field value fails to parse as a Dictionary (), the entire field is ignored. When a key appears more than once, the last value is used, as specified for Dictionaries in . As permitted by , this specification defines its own handling of values that parse correctly but violate the constraints above: a member whose value does not have the required type (for example, a "title" whose value is an Integer) MUST be ignored on its own, and the remaining members MUST still be processed. The same applies to a Parameter of "image" whose value does not have the required type or is not positive where this is required. Recipients MUST ignore Dictionary members and Parameters that they do not recognize. This allows the field to be extended in the future.

Resolving the Image Reference A relative reference in the "image" member is resolved () using the target URI of the request whose response carried the Preview field as the base URI. When redirects were followed, this is the target URI of the final request, not of the original one. The Content-Location header field () does not affect the base URI or the resource that the field describes. Likewise, a preview generator uses the Preview field of the response it received, and does not need to follow a "canonical" link () to obtain it.

Server Behavior

Responses to HEAD and GET An origin server MAY send the Preview field in 2xx (Successful) responses to HEAD and GET requests. Recipients ignore the field in responses with other status codes. The main benefit of the field comes from HEAD: a server can produce the field from a handler that does not generate the representation data, and a preview generator can use it without retrieving that data. Consistent with , an origin server that sends Preview in responses to HEAD SHOULD send the same field value in responses to GET for the same resource. This matters in practice for three reasons:

• some intermediaries forward HEAD requests to the origin server as GET requests (see );
• caches often answer HEAD requests from stored GET responses (see );
• some preview generators only send GET requests.

Sending the field in GET responses does not require generating anything new: the server already has this information when it generates the representation. When a preview generator receives different Preview values for the same resource in responses to HEAD and GET, the value from the more recent response takes precedence.

Field Content Senders MUST generate the field value using the serialization algorithms of . This is especially important because titles and descriptions are often derived from user-provided content; correct serialization prevents the injection of additional members or field lines. Senders SHOULD use a String rather than a Display String for text that contains only printable ASCII characters, since it is shorter and easier to read. Percent-encoding makes non-ASCII text considerably longer: a Cyrillic character, for instance, occupies two octets in UTF-8 and six characters after encoding. Many servers and intermediaries limit the total size of response header fields, sometimes to a few kilobytes, and fail the whole response when the limit is exceeded. Therefore:

• the serialized field value SHOULD NOT exceed 2048 octets;
• a "title" SHOULD NOT exceed 100 Unicode code points, and a "description" SHOULD NOT exceed 300 Unicode code points, both counted before encoding.

For text in scripts that need several octets per code point, the 2048-octet limit is reached before the code point limits. In that case, senders SHOULD shorten the "description" first. Senders that truncate text MUST do so on code point boundaries, because a Display String that contains invalid UTF-8 causes the entire field to fail parsing ().

Language and Variants The language of the text in the Preview field is indicated by the Content-Language header field () of the same response, when present. This document does not define a separate language member. If the content of the Preview field depends on request header fields, such as Accept-Language, the server SHOULD send a Vary header field as described in .

Access Control The Preview field can carry metadata that is not contained in the representation itself, for example a title and description of a PDF document stored in a separate database. This is expected. However, a server MUST NOT include in the Preview field any information that the requester is not authorized to obtain; the field is not a way around the access control that applies to the resource. In particular, a server that requires authentication for a resource MUST NOT reveal the title or description of that resource in a Preview field sent to an unauthenticated client. Responses that carry Preview for access-controlled resources SHOULD be marked with "Cache-Control: private" ().

Preview Generator Behavior A preview generator can obtain the Preview field in two ways: from a response to the GET request it already sends today, or from a response to a HEAD request sent instead of that GET. The first way costs nothing extra; the second one realizes the savings this specification aims for, but only when the origin server supports the field.

Using Preview in GET Responses A preview generator SHOULD use the Preview field when it finds it in a response to a GET request, following the rules in .

HEAD-First Retrieval A preview generator that expects the origin server to support the Preview field (see ) processes a link as follows:

1. It sends a HEAD request for the target URI, following redirects as it would for a GET request.
2. If the final response has a 2xx (Successful) status code and contains a Preview field that parses successfully, it processes the field as described in .
3. In all other cases (the field is absent or invalid, contains neither "nopreview" nor "title", the HEAD request fails, or the server responds with a status code such as 405 (Method Not Allowed) or 501 (Not Implemented)), it falls back to the methods it uses today, such as retrieving the representation with GET and reading Open Graph metadata from it.

Processing the Field

• If the "nopreview" member is true, the generator SHOULD NOT display a rich preview and SHOULD NOT retrieve the resource or the image for the purpose of generating one. It can still display the link itself.
• Otherwise, if the field contains a "title" member, the generator has enough information for a basic preview. After a HEAD request, it SHOULD NOT send a GET request for the target URI for the purpose of generating the preview. If an "image" member is present, the generator can retrieve the image as it would retrieve an og:image, subject to . A generator that needs a property the field does not provide (for example, an image required by its card layout) MAY still retrieve the representation, accepting the cost that this specification aims to avoid.

When a preview generator obtains both a Preview field and other preview metadata for the same resource (for example, Open Graph metadata from a representation), the information in the Preview field SHOULD take precedence, member by member. Metadata from other sources can be used for properties that the Preview field does not provide.

Discovering Support Sending HEAD first to an origin server that does not support the field adds a round trip. Before this specification is widely deployed, that would be the common case. How a generator decides when to use HEAD-first retrieval is an implementation choice; this section describes a strategy that avoids most of the extra cost.

1. By default, the generator retrieves links with GET as it does today, and uses the Preview field if the GET response contains it ().
2. When a response contains a Preview field that parses successfully and contains a "title" member or a "nopreview" member that is true, the generator records that the origin of the final response, after redirects, supports it, and uses HEAD-first retrieval for further links to that origin.
3. When a HEAD response from such an origin does not contain such a field (the field is absent, invalid, or contains neither member), the generator falls back to GET and can remove or narrow the record.

Records of support SHOULD expire after a limited time, because support can change. A generator can keep records at a finer granularity than the origin, for example per path prefix, because different parts of a site are sometimes served by different software. A stateless generator can skip discovery entirely and use the field only when it appears in GET responses. This strategy finds only servers that send the field in GET responses, as recommended in . A generator MAY also try HEAD-first retrieval at other times, for example occasionally for origins with no record, to find servers that send the field only in HEAD responses. With the strategy above, and without occasional HEAD-first attempts, origins that do not support the field receive no additional requests, and origins that support it receive fewer expensive ones. Occasional attempts add a small number of HEAD requests to origins that do not support the field. Origins that support the field only for some of their resources can receive an occasional extra HEAD request.

Caching Considerations The Preview field does not change the cacheability of a response. The usual rules of apply. Caches often answer HEAD requests from stored GET responses. When the origin server includes Preview in GET responses, as recommended in , such caches can provide the field to preview generators without contacting the origin server. A cache that forwards a HEAD request uses the response to update or invalidate its stored GET responses (), depending on whether the validators and the Content-Length match. A lightweight HEAD handler that sends values different from those of GET responses would make caches discard their stored responses and increase the load on the origin server. Therefore:

• a HEAD response that carries Preview SHOULD carry the same validator fields () that a GET response for the same resource would carry, when the server can determine them without generating the representation (for example, from the modification time of the underlying data);
• a server that cannot determine a validator or the Content-Length without generating the representation SHOULD omit that field from the HEAD response rather than send a value that differs from the GET response, as allowed by .

Operational Considerations Many HTTP server frameworks implement HEAD by running the handler for GET and discarding the content. Such servers send the Preview field correctly but do not save any work. To benefit from this specification, a server needs a separate HEAD handler, or a GET handler that stops before generating content when the request method is HEAD. Some intermediaries, including some content delivery networks, forward HEAD requests to the origin server as GET requests. Behind such an intermediary, the origin server generates the representation, and the preview generator receives the Preview field only if the server sends it in GET responses. The intermediary can still serve later requests from its cache. Implementations of Structured Fields that predate do not support Display Strings, and fail to parse the entire field when one is present. Senders MAY use Strings for "site" and for the "alt" Parameter when the text can reasonably be expressed in ASCII, to reduce the impact of such implementations. Header compression in HTTP/2 and HTTP/3 is effective for field values that repeat across responses. The Preview field is usually different for each resource and therefore compresses poorly. Servers that send it in every GET response add its full size to each of those responses, most of which go to clients that do not need it. recommends sending the field in GET responses because caches, some intermediaries and support discovery () depend on it. A server for which the added size matters more can send the field only in HEAD responses; it remains interoperable, but preview generators are less likely to discover and use it.

Relationship to Other Mechanisms

Open Graph Protocol The Preview field is designed as a transport for the subset of Open Graph properties that preview cards use. shows the correspondence. Other Open Graph properties already have HTTP equivalents, also shown in the table. Open Graph Properties and Their HTTP Equivalents

Open Graph	HTTP
og:title	Preview: title
og:description	Preview: description
og:image	Preview: image
og:image:width, og:image:height, og:image:type, og:image:alt	Parameters of Preview: image
og:site_name	Preview: site
og:url	Link with rel="canonical"
og:locale	Content-Language

A resource can publish both Open Graph metadata and the Preview field. Publishers are encouraged to keep them consistent.

The "preview" Link Relation The "preview" link relation type refers to a resource that provides a preview of the link's context, and can be sent in a Link header field . It can identify an image. Target attributes such as "title" () describe the link target, not the resource that the response describes, and there are no attributes for a description, image dimensions or alternative text. A preview generator MAY use an image identified by a "preview" link when the Preview field has no "image" member.

Content Negotiation An alternative design would let a preview generator request a special media type that contains only preview metadata, using the Accept header field . This specification does not take that approach because it requires a new media type; it requires origin servers to send "Vary: Accept", which reduces the efficiency of shared caches for all clients of the resource; and it changes the representation that is returned, whereas HEAD already has the semantics of "metadata without content".

Other Mechanisms oEmbed lets a provider return embeddable content from a separate endpoint, which can be discovered through a link with the "alternate" relation type and an oEmbed media type. Discovery through a Link header field is possible with HEAD, but retrieving the metadata then takes a second request, and an endpoint has to be deployed for it. oEmbed serves rich embeds from selected providers rather than generic preview cards, and is complementary to this specification. More generally, a Link header field with a relation type such as "describedby" could point to a separate metadata document for the resource. The Link Preview Manifest proposal follows this approach for the same problem: a HEAD response carries a link to a JSON document with the preview metadata. Such a design can describe richer metadata, but it has the same cost as oEmbed discovery: a second request, and a second resource to deploy and keep consistent. Carrying a few short values directly in the response avoids both. The two approaches can coexist: a server can send the Preview field and also link to a richer document. Signposting uses typed links in HTTP header fields, retrievable with HEAD, to expose metadata about scholarly resources. It shows that clients can successfully rely on HEAD responses to discover information about a resource without retrieving it. Fediverse Enhancement Proposal 8967 lets the author of a social media post attach preview information to the post itself. It reduces repeated fetching between servers but not the initial fetch from the origin; the two approaches can be combined.

Security Considerations The Preview field contains information provided by the origin server, in the same way as Open Graph metadata in an HTML document. It therefore has similar security properties. In particular, a server can describe a resource in a misleading way. This was already possible by serving different HTML to preview generators; the Preview field does not add this capability, but makes it cheaper. Preview generators SHOULD apply the same trust policies to the Preview field that they apply to other publisher-provided metadata. A generator that suspects misleading metadata, for example because of reports from its users, can retrieve the representation and compare. Preview generators retrieve URIs chosen by other parties: the target URI chosen by the user who shares a link, every redirect target, and the image chosen by the origin server. Server-based generators are therefore exposed to server-side request forgery, both for the HEAD request defined here and for image retrieval, in the same way as they are today with GET requests and og:image. They SHOULD apply to every request, including each redirect and each image retrieval, the same restrictions that they apply today, such as refusing private, loopback and link-local addresses and checking the address after DNS resolution to prevent DNS rebinding. In addition, they SHOULD only retrieve images with "https" URIs. Intermediaries can add, remove or modify the Preview field. Using HTTPS protects it in transit between the origin server and the preview generator. Text in the field is frequently derived from user-provided content. requires correct Structured Field serialization to prevent header injection. Preview generators MUST treat the text as untrusted and escape it appropriately before displaying it, for example before inserting it into HTML. Display Strings can contain any Unicode text, including control characters and bidirectional formatting characters that can make displayed text misleading. Senders SHOULD NOT include control characters (Unicode general category Cc) or bidirectional formatting characters in Preview text. Preview generators SHOULD remove such characters, or isolate the text so that they cannot affect the surrounding content, before display. A large Preview field can consume resources of the recipient. Preview generators SHOULD impose a limit on the size of the field value they process, and MAY truncate text values for display.

Privacy Considerations The Preview field carries the kind of information that publishers already expose for link previews through Open Graph metadata. For resources without an HTML representation, it can expose metadata that is not contained in the representation itself; the publisher decides what to include. prevents servers from using the field to reveal information to requesters that are not authorized to obtain it. Some preview generators run on the device of the user who shares a link, so that the service they use does not learn which links they share. For those generators, retrieving a short HEAD response instead of a full page reduces data usage and delay, but the origin server still learns the network address of the device, as it does today. The URI in the "image" member can contain identifiers that let the origin server, or the server hosting the image, observe which preview generators displayed a link. This is also true of og:image today. This specification reduces the cost of each request made by preview generators, not the number of those requests. In particular, it does not change how often decentralized services retrieve the same link.

IANA Considerations IANA is requested to register the following entry in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" defined in :

Field Name:

Preview

Status:

permanent

Structured Type:

Dictionary

Reference:

This document

Comments:

(none)

Normative References Informative References Meta Platforms, Inc. oEmbed Fediverse Enhancement Proposals SocialHub Mastodon project issue tracker Issue #4486

Complete Example A preview generator sends: The origin server answers from a handler that reads the title and the image location from a small metadata store, without rendering the page: ; rel="canonical" Preview: title="How we count cloud costs" Preview: description="A practical model for small teams" Preview: image="/og/123.jpg";width=1200;height=630;type="image/jpeg" Preview: site="Example Blog" ]]> The handler takes the Last-Modified value from the same metadata store, so it matches the value of a GET response. It omits Content-Length, which it cannot know without rendering the page (see ). The preview generator builds the card from these fields, resolves the image reference to "https://www.example.com/og/123.jpg" and retrieves the image. It does not send a GET request for the page. For a resource whose owner does not want previews:

Open Issues

• Should sending Preview in GET responses () be a requirement rather than a recommendation?
• Should a registry of Preview members be created, and with which registration policy?
• Should a member for the kind of resource (similar to og:type) be defined, so that generators can choose a card layout for articles, videos and other content?
• Should video and audio previews (similar to og:video and og:audio) be in scope?
• Is the precedence rule in (Preview before HTML metadata) the right default?
• Are the recommended size limits in appropriate?
• Is "Preview" the best field name? It is short and descriptive, but it could be confused with other uses of the word, such as link preview features of browsers or prerendering. "Preview-Card" is a possible alternative; "Link-Preview" is already used informally by .

Implementation Status This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, following the approach described in . At the time of writing, there are no known implementations.

Acknowledgements This proposal was informed by public discussions in the fediverse community about the load that link previews create on origin servers, by the earlier work on the "preview" link relation and on Signposting, and by the Link Preview Manifest proposal.