HTTP header field

An HTTP header field is named information carried in an HTTP message's header section. Its definition determines how its value is interpreted. Field names are case-insensitive, while values follow the rules of their particular field rather than one universal casing rule.^[ref]

For example, ETag: "AbC" and etag: "abc" use the same field name but different entity tags. The quoted opaque strings are compared character by character under the relevant tag-comparison rules. Lowercasing both names is harmless for identifying the field; lowercasing all values would erase a real distinction.^[ref]

Other fields express different kinds of information. Content-Type: text/plain; charset=utf-8 describes a media type and character encoding for content. It does not contain the content itself, and its meaning cannot be inferred by applying the entity-tag grammar to it.

In HTTP/1.1, a textual field line places a colon between the name and value; an empty line terminates the header section. This is a wire-format example, not a requirement that every HTTP version transmit identical text lines.^[ref]

Repeated field occurrences also need their own semantics. Some can be combined as ordered lists, but treating every header section as a dictionary with exactly one value per name can lose information. Read the field definition before combining lines or rearranging values.^[ref]

An entity tag is an opaque validator associated with a selected HTTP representation and commonly supplied in an ETag HTTP header field. It allows requests to refer to a previously observed version or equivalence class without interpreting the representation's contents. The tag's spelling need not reveal how the server generated it.^[ref]

A strong entity tag has no weak marker; a weak entity tag has the prefix W/. Strong comparison succeeds only when both tags are non-weak and their opaque values match character by character. Weak comparison checks the opaque values while ignoring whether either tag is marked weak.^[ref]

For example, "v1" and W/"v1" match weakly but not strongly. Two occurrences of "v1" match under either comparison. Tags "AbC" and "abc" match under neither: field-name case insensitivity does not make the opaque value case-insensitive.

A useful HTTP conditional request illustrates the purpose. Suppose a client retains representation data tagged "v1", then sends GET with If-None-Match: "v1". If the selected current tag matches, this precondition fails and the server returns 304 without transferring that response content. The retained data can then be used according to the applicable caching rules. If-None-Match uses weak comparison, while If-Match uses strong comparison.^[ref]

An entity tag is therefore a protocol validator, not an instruction to lowercase or decode its opaque string. Different representations of one resource can require different validators. Compare the tag for the selected representation under the comparison rule required by the field, rather than assuming that equal resource URLs alone establish equal data.

A weak entity tag is an entity tag explicitly marked W/ whose validation guarantee does not require distinguishing every change to the HTTP representation data. A server may group representations it regards as suitable substitutes, rather than identify each distinct sequence of bytes. The weak marker is case-sensitive.^[ref]

For an invented example, an HTML resource sometimes ends its source with an extra newline. Stipulate that this does not change its relevant rendered meaning and that the server considers both forms interchangeable for reuse. It can retain W/"page-4" across those two forms. It should change the tag when it no longer regards an older representation as an acceptable substitute. This policy is a server decision, not a license for clients to ignore arbitrary differences.^[ref]

Weak comparison ignores whether a tag is marked weak but still compares the opaque value character for character. Consequently W/"page-4" weakly matches both W/"page-4" and "page-4"; it does not match W/"Page-4". Strong comparison fails whenever either operand is a weak entity tag, even when their opaque values agree.^[ref]

This distinction supports HTTP cache validation. An HTTP conditional request with If-None-Match: W/"page-4" uses weak comparison, so a matching selected representation can produce 304 for GET. An update protected by If-Match instead requires a strong entity tag comparison and cannot obtain that guarantee from this weak tag.^[ref]

Weakness concerns the strength of the equivalence assertion. It does not mean that the tag is malformed, that an exchange failed, or that its opaque text measures how similar two representations are.

A strong entity tag is an entity tag that satisfies HTTP's strong-validator requirements. Its value must change whenever the HTTP representation data change in a way observable in a successful GET response. Its syntax has no weak W/ prefix, for example "revision-7".^[ref]

Suppose a resource serves the four bytes blue with tag "revision-7". Changing the first byte to produce Blue requires a different strong entity tag, even if the application regards the capitalization difference as unimportant. A revision counter can implement this example, but the client must treat the quoted tag as opaque: the syntax does not promise that a number can be parsed or incremented to predict the next tag.^[ref]

Strong comparison succeeds only when both entity tags are strong and their quoted opaque values match character for character. Thus "revision-7" matches "revision-7", but not W/"revision-7" and not "Revision-7". Removing the weak marker in a client would change the meaning of the validator rather than upgrade the server's guarantee.^[ref]

An HTTP conditional request using If-Match requires strong comparison. This is useful when an update should proceed only against the representation the client previously observed. The guarantee is scoped to the resource: identical tag text on two unrelated resources does not establish that their data are equal. Conversely, a strong validator may change for a relevant metadata change as well as a data change, so a changed tag alone is not a byte-by-byte difference report.^[ref]