Internet-Draft HTTP Preview Field October 2026
Borshchahivskyi Expires 22 April 2027 [Page]
Workgroup:
HTTP
Internet-Draft:
draft-borshchahivskyi-httpbis-preview-00
Published:
Intended Status:
Standards Track
Expires:
Author:
P. Borshchahivskyi

The Preview HTTP Response Header Field

Abstract

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

This note is to be removed before publishing as an RFC.

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 Appendix B.

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 22 April 2027.

▲

Table of Contents

1. 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 [OGP], 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:

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 (Section 14.2 of [HTTP]). 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 [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 [MASTODON-4486].

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 (Section 2), which carries preview metadata as a Structured Field [STRUCTURED-FIELDS]. Because the information is carried in a header field, it can be delivered in a response to a HEAD request (Section 9.3.2 of [HTTP]). An origin server can then answer preview generators from a lightweight handler, and generators can build a card from a single HEAD exchange.

1.1. 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.

1.2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

This document uses the following terminology from Section 3 of [STRUCTURED-FIELDS] 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 [HTTP].

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).

2. 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 (Section 2 of [STRUCTURED-FIELDS]) 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 Section 5.3 of [HTTP]:

Preview: title="How we count cloud costs"
Preview: description="A practical model for small teams"
Preview: image="/og/123.jpg";width=1200;height=630
Preview: site="Example Blog"

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 (Section 3.3.8 of [STRUCTURED-FIELDS]). For example, the Ukrainian word "Pryvit" ("Hello") written in Cyrillic script is sent as follows:

Preview: title=%"%d0%9f%d1%80%d0%b8%d0%b2%d1%96%d1%82"

2.1. 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.

2.1.1. 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 [OGP].

2.1.2. 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.

2.1.3. image

The "image" member identifies an image that represents the resource. Its value MUST be a String containing a URI-reference (Section 4.1 of [URI]). A relative reference is resolved as described in Section 2.3. 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.

2.1.4. 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.

2.1.5. 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:

Preview: nopreview

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. Section 4 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.

2.2. Error Handling

If the field value fails to parse as a Dictionary (Section 4.2 of [STRUCTURED-FIELDS]), the entire field is ignored. When a key appears more than once, the last value is used, as specified for Dictionaries in Section 4.2.2 of [STRUCTURED-FIELDS].

As permitted by Section 2.2 of [STRUCTURED-FIELDS], 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.

2.3. Resolving the Image Reference

A relative reference in the "image" member is resolved (Section 5 of [URI]) 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 (Section 8.7 of [HTTP]) 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 ([RFC6596]) to obtain it.

3. Server Behavior

3.1. 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 Section 9.3.2 of [HTTP], 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 Section 6);
  • caches often answer HEAD requests from stored GET responses (see Section 5);
  • 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.

3.2. Field Content

Senders MUST generate the field value using the serialization algorithms of Section 4.1 of [STRUCTURED-FIELDS]. 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 (Section 4.2.10 of [STRUCTURED-FIELDS]).

3.3. Language and Variants

The language of the text in the Preview field is indicated by the Content-Language header field (Section 8.5 of [HTTP]) 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 Section 12.5.5 of [HTTP].

3.4. 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" (Section 5.2.2.7 of [CACHING]).

4. 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.

4.1. 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 Section 4.3.

4.2. HEAD-First Retrieval

A preview generator that expects the origin server to support the Preview field (see Section 4.4) 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 Section 4.3.
  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.

4.3. 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 Section 8. 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.

4.4. 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 (Section 4.1).
  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 Section 3.1. 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.

5. Caching Considerations

The Preview field does not change the cacheability of a response. The usual rules of [CACHING] apply.

Caches often answer HEAD requests from stored GET responses. When the origin server includes Preview in GET responses, as recommended in Section 3.1, 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 (Section 4.3.5 of [CACHING]), 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:

6. 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 [STRUCTURED-FIELDS] 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. Section 3.1 recommends sending the field in GET responses because caches, some intermediaries and support discovery (Section 4.4) 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.

8. 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. Section 3.2 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.

9. 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. Section 3.4 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.

10. IANA Considerations

IANA is requested to register the following entry in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" defined in Section 16.3.1 of [HTTP]:

Field Name:
Preview
Status:
permanent
Structured Type:
Dictionary
Reference:
This document
Comments:
(none)

11. Normative References

[CACHING]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, , <https://www.rfc-editor.org/info/rfc9111>.
[HTTP]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, , <https://www.rfc-editor.org/info/rfc9110>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[STRUCTURED-FIELDS]
Nottingham, M. and P-H. Kamp, "Structured Field Values for HTTP", RFC 9651, DOI 10.17487/RFC9651, , <https://www.rfc-editor.org/info/rfc9651>.
[URI]
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/info/rfc3986>.

12. Informative References

[FEP-8967]
Fediverse Enhancement Proposals, "FEP-8967: Generating link previews for attached links", <https://w3id.org/fep/8967>.
Youssuff, "Link Preview Manifest: A Proposal for the Fediverse", , <https://www.quippd.com/writing/2026/03/09/link-preview-manifest-a-proposal-for-the-fediverse.html>.
[MASTODON-4486]
Mastodon project issue tracker, "Mastodon can be used as a DDOS tool", Issue #4486, , <https://github.com/mastodon/mastodon/issues/4486>.
[OEMBED]
oEmbed, "oEmbed", <https://oembed.com/>.
[OGP]
Meta Platforms, Inc., "The Open Graph protocol", <https://ogp.me/>.
[RFC6596]
Ohye, M. and J. Kupke, "The Canonical Link Relation", RFC 6596, DOI 10.17487/RFC6596, , <https://www.rfc-editor.org/info/rfc6596>.
[RFC6903]
Snell, J., "Additional Link Relation Types", RFC 6903, DOI 10.17487/RFC6903, , <https://www.rfc-editor.org/info/rfc6903>.
[RFC7942]
Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, , <https://www.rfc-editor.org/info/rfc7942>.
[SIGNPOSTING]
Van de Sompel, H. and M. L. Nelson, "Signposting the Scholarly Web", <https://signposting.org/>.
[SOCIALHUB-CONNEG]
SocialHub, "Using content negotiation for OpenGraph metadata - mitigating the fedi DDoS problem", , <https://socialhub.activitypub.rocks/t/using-content-negotiation-for-opengraph-metadata-mitigating-the-fedi-ddos-problem/4317>.
[WEB-LINKING]
Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, , <https://www.rfc-editor.org/info/rfc8288>.

Appendix A. Complete Example

A preview generator sends:

HEAD /blog/cloud-costs HTTP/1.1
Host: www.example.com
User-Agent: ExamplePreviewBot/1.0

The origin server answers from a handler that reads the title and the image location from a small metadata store, without rendering the page:

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Language: en
Last-Modified: Mon, 12 Oct 2026 08:30:00 GMT
Cache-Control: public, max-age=3600
Link: <https://www.example.com/blog/cloud-costs>; 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 Section 5).

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:

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Preview: nopreview

Appendix B. Open Issues

This section is to be removed before publishing as an RFC.

Appendix C. Implementation Status

This section is to be removed before publishing as an RFC.

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 [RFC7942].

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.

Author's Address

Petro Borshchahivskyi
Las Vegas, NV
United States of America