5. Field Definitions
This section defines the syntax and semantics of HTTP fields related to caching.
5.1 Age
The "Age" response header field conveys the sender's estimate of the amount of time since the response was generated or successfully validated at the origin server. The Age value is calculated as specified in Section 4.2.3.
Age = delta-seconds
The Age field value is a non-negative integer, representing time in seconds (see Section 1.2.2).
Although it is defined as a singleton header field, a cache that encounters a message with a list-based Age field value SHOULD use the first member of the field value, discarding subsequent members.
If the field value (after discarding other members, as per above) is invalid (e.g., it contains something other than a non-negative integer), a cache SHOULD ignore the field.
The presence of an Age header field implies that the response was not generated or validated by the origin server for this request. However, lack of an Age header field does not imply that the origin server was contacted.
5.2 Cache-Control
The "Cache-Control" header field is used to list directives for caches along the request/response chain. Cache directives are unidirectional in that the presence of a directive in a request does not imply that the same directive is present or copied in the response.
See Section 5.2.3 for information about how Cache-Control directives defined elsewhere are handled.
A proxy, whether or not it implements a cache, MUST pass through cache directives in forwarded messages, regardless of their significance to that application, since the directives might apply to all recipients along the request/response chain. It is not possible to target a directive to a specific cache.
Cache directives are identified by a token (to be compared case-insensitively), and have an optional argument, which can use both token and quoted-string syntax. For the directives defined below where an argument is defined, recipients SHOULD accept both forms, even if a specific form is required for generation.
Cache-Control = #cache-directive
cache-directive = token [ "=" ( token / quoted-string ) ]
For the cache directives defined below, no argument is defined (nor allowed) unless otherwise stated.
5.2.1 Request Directives
This section defines cache request directives. They are advisory; caches MAY implement them, but are not required to.
5.2.1.1 max-age
Argument syntax:
delta-seconds (see Section 1.2.2)
The max-age request directive indicates that the client prefers a response whose age is less than or equal to the specified number of seconds. Unless the max-stale request directive is also present, the client does not wish to receive a stale response.
This directive uses the token form of the argument syntax: e.g., 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the quoted-string form.
5.2.1.2 max-stale
Argument syntax:
delta-seconds (see Section 1.2.2)
The max-stale request directive indicates that the client will accept a response that has exceeded its freshness lifetime. If a value is present, the client is willing to accept a response that has exceeded its freshness lifetime by no more than the specified number of seconds. If no value is assigned to max-stale, the client will accept a stale response of any age.
This directive uses the token form of the argument syntax: e.g., 'max-stale=10' not 'max-stale="10"'. A sender MUST NOT generate the quoted-string form.
5.2.1.3 min-fresh
Argument syntax:
delta-seconds (see Section 1.2.2)
The min-fresh request directive indicates that the client prefers a response whose freshness lifetime is no less than its current age plus the specified number of seconds. That is, the client wants a response that will remain fresh for at least the specified number of seconds.
This directive uses the token form of the argument syntax: e.g., 'min-fresh=20' not 'min-fresh="20"'. A sender MUST NOT generate the quoted-string form.
5.2.1.4 no-cache
The no-cache request directive indicates that the client prefers that stored responses not be used to satisfy the request without successful validation at the origin server.
5.2.1.5 no-store
The no-store request directive indicates that a cache MUST NOT store any part of either this request or any response to it. This directive applies to both private and shared caches. "MUST NOT store" in this context means that the cache MUST NOT intentionally store the information in non-volatile storage, and MUST make a best-effort attempt to remove the information from volatile storage as promptly as possible after forwarding it.
This directive is NOT a reliable or sufficient mechanism for ensuring privacy. In particular, malicious or compromised caches might not recognize or obey this directive, and communications networks might be vulnerable to eavesdropping.
Note that if a request containing this directive is satisfied from a cache, the no-store request directive does not apply to the already stored response.
5.2.1.6 no-transform
The no-transform request directive indicates that the client is asking an intermediary to avoid transforming the content, as defined by Section 7.7 of [HTTP].
5.2.1.7 only-if-cached
The only-if-cached request directive indicates that the client only wishes to obtain a stored response. A cache that honors this request directive SHOULD respond with either a stored response that is consistent with the other constraints of the request, or a 504 (Gateway Timeout) status code upon receiving it.
5.2.2 Response Directives
This section defines cache response directives. Caches MUST obey the Cache-Control directives defined in this section.
5.2.2.1 max-age
Argument syntax:
delta-seconds (see Section 1.2.2)
The max-age response directive indicates that the response is to be considered stale after its age is greater than the specified number of seconds.
This directive uses the token form of the argument syntax: e.g., 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the quoted-string form.
5.2.2.2 must-revalidate
The must-revalidate response directive indicates that once the response has become stale, a cache MUST NOT reuse that response to satisfy another request until it has been successfully validated by the origin server, as defined in Section 4.3.
The must-revalidate directive is necessary to support reliable operation of certain protocol features. In all circumstances a cache MUST NOT ignore the must-revalidate directive; in particular, if a cache is disconnected, the cache MUST generate an error response rather than reuse the stale response. The generated status code SHOULD be 504 (Gateway Timeout) unless another error status code is more applicable.
Servers SHOULD only use the must-revalidate directive when failure to revalidate a request could result in incorrect operation (such as a silently unexecuted financial transaction).
The must-revalidate directive also enables a shared cache to reuse a response to a request containing an Authorization header field (see Section 11.6.2 of [HTTP]), subject to the above requirement on revalidation (Section 3.5).
5.2.2.3 must-understand
The must-understand response directive limits caching of the response to caches that understand and conform to the requirements for that response's status code.
A response that contains a must-understand directive SHOULD also contain a no-store directive. When a cache that implements the must-understand directive receives a response that contains it, the cache SHOULD ignore the no-store directive if it understands and implements the status code's caching requirements.
5.2.2.4 no-cache
Argument syntax:
#field-name
The no-cache response directive, in its unqualified form (without an argument), indicates that the response MUST NOT be used to satisfy any other request without forwarding it for validation and receiving a successful response; see Section 4.3.
This allows an origin server to prevent a cache from using the response to satisfy a request without contacting it, even by caches that have been configured to send stale responses.
The qualified form of the no-cache response directive, with an argument that lists one or more field names, indicates that a cache MAY use the response to satisfy a subsequent request, subject to any other restrictions on caching, if the listed header fields are excluded from the subsequent response or the subsequent response has been successfully revalidated with the origin server (updating or removing those fields). This allows an origin server to prevent the reuse of certain header fields in a response, while still allowing caching of the rest of the response.
The field names given are not limited to the set of header fields defined by this specification. Field names are case-insensitive.
This directive uses the quoted-string form of the argument syntax. A sender SHOULD NOT generate the token form (even if quoting appears not to be needed for single-entry lists).
Note: The qualified form of the directive is often handled by caches as if an unqualified no-cache directive was received; i.e., the special handling of the qualified form is not widely implemented.
5.2.2.5 no-store
The no-store response directive indicates that a cache MUST NOT store any part of either the immediate request or response, and MUST NOT use the response to satisfy any other request.
This directive applies to both private and shared caches. "MUST NOT store" in this context means that the cache MUST NOT intentionally store the information in non-volatile storage, and MUST make a best-effort attempt to remove the information from volatile storage as promptly as possible after forwarding it.
This directive is NOT a reliable or sufficient mechanism for ensuring privacy. In particular, malicious or compromised caches might not recognize or obey this directive, and communications networks might be vulnerable to eavesdropping.
Note that the must-understand cache directive overrides no-store in certain circumstances; see Section 5.2.2.3.
5.2.2.6 no-transform
The no-transform response directive indicates that an intermediary (whether or not it implements a cache) MUST NOT transform the content, as defined by Section 7.7 of [HTTP].
5.2.2.7 private
Argument syntax:
#field-name
The unqualified private response directive indicates that a shared cache MUST NOT store the response (i.e., the response is intended for a single user). It also indicates that a private cache MAY store the response, subject to the constraints defined in Section 3, even if the response would not otherwise be heuristically cacheable by a private cache.
If a qualified private response directive is present (with an argument that lists one or more field names), then only the listed header fields are limited to a single user: a shared cache MUST NOT store the listed header fields if they are present in the original response, but MAY store the rest of the response message without those header fields, subject to the constraints defined in Section 3.
The field names given are not limited to the set of header fields defined by this specification. Field names are case-insensitive.
This directive uses the quoted-string form of the argument syntax. A sender SHOULD NOT generate the token form (even if quoting appears not to be needed for single-entry lists).
Note: This usage of the word "private" only controls where the response can be stored; it cannot ensure the privacy of the message content. Also, the qualified form of the directive is often handled by caches as if an unqualified private directive was received; i.e., the special handling of the qualified form is not widely implemented.
5.2.2.8 proxy-revalidate
The proxy-revalidate response directive indicates that once the response has become stale, a shared cache MUST NOT reuse that response to satisfy another request until it has been successfully validated by the origin server, as defined in Section 4.3. This is analogous to must-revalidate (Section 5.2.2.2), except that proxy-revalidate does not apply to private caches.
Note that proxy-revalidate on its own does not imply that a response is cacheable. For example, it might be combined with the public directive (Section 5.2.2.9) to allow a response to be cached while requiring only shared caches to revalidate when stale.
5.2.2.9 public
The public response directive indicates that a cache MAY store the response even if it would otherwise be prohibited, subject to the constraints defined in Section 3. In other words, public explicitly marks the response as cacheable. For example, public permits a shared cache to reuse a response to a request containing an Authorization header field (Section 3.5).
Note that it is unnecessary to add the public directive to a response that is already cacheable according to Section 3.
If a response with a public directive has no explicit freshness information, it is heuristically cacheable (Section 4.2.2).
5.2.2.10 s-maxage
Argument syntax:
delta-seconds (see Section 1.2.2)
The s-maxage response directive indicates that, for a shared cache, the maximum age specified by this directive overrides the maximum age specified by either the max-age directive or the Expires header field.
The s-maxage directive incorporates the semantics of the proxy-revalidate response directive (Section 5.2.2.8) for shared caches. A shared cache MUST NOT reuse a stale response with s-maxage to satisfy another request until it has been successfully validated by the origin server, as defined in Section 4.3. This directive also permits a shared cache to reuse a response to a request containing an Authorization header field, subject to the above requirements on maximum age and revalidation (Section 3.5).
This directive uses the token form of the argument syntax: e.g., 's-maxage=10' not 's-maxage="10"'. A sender MUST NOT generate the quoted-string form.
5.2.3 Extension Directives
The Cache-Control header field can be extended by the use of one or more extension cache directives. A cache MUST ignore unrecognized cache directives.
Informational extensions (those that do not require a change in cache behavior) can be added without changing the semantics of other directives.
Behavioral extensions are designed to work by acting as modifiers to the existing base of cache directives. Both the new directive and the old directive are supplied, such that applications that do not understand the new directive will default to the behavior specified by the old directive, and those that understand the new directive will recognize it as modifying the requirements associated with the old directive. In this way, extensions to the existing cache directives can be made without breaking deployed caches.
For example, consider a hypothetical new response directive called "community" that acts as a modifier to the private directive: in addition to private caches, any cache that is shared only by members of a named community is allowed to cache the response. An origin server wishing to allow the UCI community to use an otherwise private response in their shared caches could do so by including:
Cache-Control: private, community="UCI"
Caches that recognize such a community cache directive could broaden their behavior in accordance with that extension. Caches that do not recognize the community cache directive would ignore it and adhere to the private directive.
New extension directives ought to consider defining:
-
What it means for the directive to be specified multiple times,
-
When the directive argument is present, what it means when the argument is absent,
-
When the directive argument is required, what it means when the argument is missing, and
-
Whether the directive is specific to requests, specific to responses, or able to be used in both.
5.2.4 Cache Directive Registry
The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry" defines the namespace for cache directives. It has been created and is now maintained at ````https://www.iana.org/assignments/http-cache-directives\````.
A registration MUST include the following fields:
-
Cache Directive Name
-
Pointer to specification text
Values to be added to this namespace require IETF Review (see Section 4.8 of [RFC8126]).
5.3 Expires
The "Expires" response header field gives the date/time after which the response is considered stale. See Section 4.2 for further discussion of the freshness model.
The presence of an Expires header field does not imply that the original resource will change or cease to exist at, before, or after that time.
The Expires field value is an HTTP-date timestamp, as defined in Section 5.6.7 of [HTTP]. For cache-specific parsing requirements, see also Section 4.2.
Expires = HTTP-date
For example:
Expires: Thu, 01 Dec 1994 16:00:00 GMT
A cache recipient MUST interpret invalid date formats, especially the value "0", as representing a time in the past (i.e., "already expired").
If a response includes a Cache-Control header field with the max-age directive (Section 5.2.2.1), a recipient MUST ignore the Expires header field. Likewise, if a response includes the s-maxage directive (Section 5.2.2.10), a shared cache recipient MUST ignore the Expires header field. In either of these cases, the value in Expires is only intended for recipients that have not yet implemented the Cache-Control header field.
An origin server without a clock (see Section 5.6.7 of [HTTP]) MUST NOT generate an Expires header field unless its value represents a fixed time in the past (always expired) or its value has been associated with the resource by a system with a clock.
Historically, HTTP required the Expires field value to be no more than a year in the future. While longer freshness lifetimes are no longer prohibited, extremely large values have been demonstrated to cause problems (e.g., clock overflow due to use of 32-bit integers for time values), and many caches will evict a response far sooner.
5.4 Pragma
The "Pragma" request header field was defined for HTTP/1.0 caches, so that clients could specify a "no-cache" request (since Cache-Control was not defined until HTTP/1.1).
However, support for Cache-Control is now widespread. As a result, this specification deprecates Pragma.
Note: Because the meaning of "Pragma: no-cache" in responses was never specified, it does not provide a reliable replacement for "Cache-Control: no-cache" in responses.
5.5 Warning
The "Warning" header field was used to carry additional information about the status or transformation of a message that might not be reflected in the status code. This specification obsoletes it, as it is not widely generated or surfaced to users. The information it carried can be gleaned from examining other header fields, such as Age.