| Internet-Draft | HTTP Semantic Validators | July 2026 |
| Jurkovikj | Expires 28 January 2027 | [Page] |
This document defines the Semantic-ETag HTTP response field and the
If-Semantic-Match HTTP request field. Unlike the standard ETag field,
which identifies a selected representation, Semantic-ETag identifies a
server-defined semantic state within an explicitly scoped semantic equivalence
domain. If-Semantic-Match enables origin servers to perform
representation-independent optimistic concurrency control when different HTTP
resources or representations expose the same logical state.¶
This document does not update or replace the semantics of ETag, If-Match,
or HTTP cache validation defined by RFC 9110.¶
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 28 January 2027.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
HTTP entity tags identify selected representations and support cache revalidation and conditional requests [RFC9110]. Applications often expose a single logical object through several representations or resources, such as an HTML page, a JSON API resource, and a Markdown editing resource. The ordinary ETags of those representations can differ even when they were generated from the same application state.¶
A client can therefore read one representation and later modify another
without a standard way to state, "perform this action only if the shared
logical state is still the state I observed." Reusing an ETag obtained from a
different target resource as If-Match does not solve this problem because
If-Match is evaluated against the selected representation of the request
target.¶
This document defines a separate semantic validator and a corresponding positive precondition. The extension preserves the existing meanings of ordinary representation validators:¶
ETag and If-Match remain scoped to the selected representation of the
target resource.¶
Semantic-ETag and If-Semantic-Match operate within a server-defined
semantic equivalence domain.¶
Semantic-ETag is not an HTTP cache validator and does not cause a 304 Not
Modified response.¶
This document specifies field syntax, comparison, precondition evaluation, atomicity, cache interaction, and security requirements. It does not define:¶
a universal model of application state;¶
automatic equivalence between arbitrary URIs or origins;¶
a discovery mechanism for semantic-precondition support;¶
an editing format, merge algorithm, or conflict-resolution policy; or¶
an integrity or authorization mechanism.¶
An application profile can define the relevant semantic equivalence domain, discovery mechanism, and methods for which semantic preconditions are required. The Agentic State Transfer profile [I-D.jurkovikj-httpapi-agentic-state] is one such profile.¶
The Collaboration Content Transfer protocol
[I-D.jurkovikj-collab-tunnel] defines machine-oriented representations and
discovery. A TCT representation can carry Semantic-ETag, but its ordinary
ETag continues to identify the exact TCT representation.¶
Agentic State Transfer (AST) defines safe mutation workflows. AST Core uses
ordinary ETag and If-Match when the mutation targets the State-Bearing
Resource itself. AST Semantic uses the fields defined here when a mutation
targets a different resource or representation in the same semantic
equivalence domain.¶
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 Augmented Backus-Naur Form (ABNF) notation of [RFC5234]
and the list extension defined in Section 5.6.1 of [RFC9110]. It imports the
opaque-tag rule from Section 8.8.3 of [RFC9110].¶
The application-defined logical state relevant to semantic equivalence and mutation safety. It excludes representation-only artifacts but includes all state whose change could make an action constructed against an earlier state unsafe.¶
The scope within which a server assigns meaning to a semantic validator. A domain can be limited by resource identity, tenant, authorization context, language, workflow, or another application-defined boundary.¶
The opaque value carried by Semantic-ETag that identifies a current
semantic state within one semantic equivalence domain.¶
A request whose successful processing can alter semantic state. Whether a method is state-changing can depend on application semantics in addition to the method name.¶
The Semantic-ETag response field communicates the current semantic validator
associated with the target resource in the applicable semantic equivalence
domain.¶
Semantic-ETag = opaque-tag¶
The weak prefix (W/) is not part of opaque-tag and MUST NOT be used. A
sender MUST generate no more than one Semantic-ETag field value in a
response. A recipient that receives multiple or syntactically invalid values
MUST NOT choose one arbitrarily and MUST treat the field as unusable.¶
Semantic-ETag is response metadata about semantic state. It is independent
of the selected representation's ETag. A response can contain both fields:¶
HTTP/1.1 200 OK Content-Type: text/html ETag: "html-v17" Semantic-ETag: "article-state-v42"¶
The ordinary ETag identifies the selected HTML representation. The semantic validator identifies the application state within the origin-defined equivalence domain.¶
An origin server MAY include Semantic-ETag in a successful response without
supporting If-Semantic-Match. Consequently, the presence of
Semantic-ETag alone is not a capability advertisement for semantic
precondition enforcement.¶
Intermediaries MUST NOT generate, rewrite, or remove Semantic-ETag unless
they act with explicit origin authority as part of the semantic validation
system. An intermediary that forwards the field SHOULD forward it unchanged.¶
Within one semantic equivalence domain, an origin server MUST satisfy all of the following invariants:¶
Equal current Semantic-ETag values imply semantically equivalent state.¶
Every change to state relevant to mutation safety changes the semantic validator before or atomically with publication of the changed state.¶
A validator is not reused across authorization contexts, tenants, or other boundaries that do not expose the same mutation-relevant state.¶
Validators are opaque to clients and are compared only as specified in this document.¶
This specification does not require the converse of the first invariant. Semantically equivalent states MAY receive different validators at different times. This permits monotonic revision identifiers, version vectors, changes to a validator-construction regime, and protection against an ABA transition.¶
A server MAY derive a validator from a collision-resistant hash, an HMAC, a revision identifier, a version vector, or another server-controlled mechanism. If historical transitions matter to mutation safety, the semantic state or validator construction SHOULD include a revision component rather than reissuing an earlier validator after the state returns to an equal value.¶
When JSON is used internally to derive a validator, JSON Canonicalization Scheme (JCS) [RFC8785] can provide a deterministic input. JCS is not required when the validator is derived from a revision identifier or another mechanism that already satisfies the invariants above.¶
Two semantic validators match only when their opaque-tag values are
identical, using a case-sensitive, character-for-character comparison. No
Unicode normalization, case folding, weak comparison, or interpretation of an
embedded hash or version is performed.¶
Validators obtained from different semantic equivalence domains are not comparable unless an applicable protocol profile explicitly binds those domains together. Equality of opaque strings observed on unrelated resources or origins does not establish semantic equivalence.¶
The If-Semantic-Match request field makes a request conditional on the
origin server's current semantic validator.¶
If-Semantic-Match = "*" / 1#opaque-tag¶
For a list of validators, the condition is true when the current
Semantic-ETag matches at least one supplied validator. The condition is
false when no supplied validator matches or when the target has no current
semantic state in the applicable domain.¶
For the wildcard value (*), the condition is true when the target has a
current semantic state in the applicable domain and false otherwise. An
application profile MAY prohibit wildcard-only conditions when proof of an
observed version is required.¶
When the condition is false, an origin server that supports this field for the
target resource MUST NOT perform the requested method and MUST respond with
412 Precondition Failed.¶
PATCH /article/123 HTTP/1.1
Host: example.com
Content-Type: application/merge-patch+json
If-Semantic-Match: "article-state-v42"
{"title":"Updated title"}
¶
An unknown request field can be ignored by an HTTP implementation. A client
therefore MUST NOT rely on If-Semantic-Match for mutation safety unless it
has positive knowledge, specific to the target resource and request method,
that the target enforces the field. Such knowledge can be provided by an
application profile, resource-and-method-specific documentation, or another
explicit discovery mechanism.¶
The presence of Semantic-ETag alone is insufficient because a deployment can
provide the response field for observation without implementing the request
field.¶
A server that advertises enforcement for a target resource and request method
MUST NOT silently ignore a syntactically valid If-Semantic-Match field on
that method. If the field is malformed, the server MUST reject the request
with 400 Bad Request. If it is valid but cannot be satisfied or evaluated
for the applicable domain, the server MUST fail closed with 412 Precondition
Failed.¶
Standard HTTP preconditions retain their meanings and ordering under [RFC9110]. After authentication, authorization, request validation, and other normal checks that precede precondition evaluation, an origin server MUST:¶
evaluate applicable standard HTTP preconditions according to [RFC9110];¶
if no standard precondition has already determined the response, evaluate
If-Semantic-Match; and¶
perform the requested action only if every applicable precondition is true.¶
A request can contain both If-Match and If-Semantic-Match. In that case,
If-Match constrains the selected representation of the target resource and
If-Semantic-Match constrains the semantic equivalence domain. Both
conditions must be true.¶
For a state-changing request, evaluation of If-Semantic-Match, application
of the state transition, and publication of the resulting semantic validator
MUST occur atomically with respect to every operation capable of changing the
same semantic equivalence domain.¶
This requirement applies to all writers, including HTTP handlers, background jobs, administrative interfaces, migrations, event consumers, and other services. Merely storing the new state and validator in one transaction is not sufficient if two requests can both compare against the same old validator before either transition commits.¶
When a server accepts a request for deferred execution, it MUST preserve the precondition through commit. It MUST do at least one of the following:¶
commit the semantic state transition before returning 202 Accepted, while
deferring only external side effects;¶
reserve or fence the matched semantic version until commit; or¶
re-evaluate the expected semantic validator atomically when the deferred transition commits.¶
If a commit-time comparison fails, the semantic state MUST NOT be modified by that operation. Because the original HTTP exchange has completed, the status resource or equivalent completion channel MUST report a failed-precondition outcome.¶
After a successful state-changing request that leaves a current semantic
state, the origin server SHOULD include the resulting Semantic-ETag when the
requesting principal is authorized to observe it:¶
HTTP/1.1 204 No Content Semantic-ETag: "article-state-v43"¶
A 412 Precondition Failed response SHOULD include the current
Semantic-ETag only after authentication and authorization checks and only
when disclosure is appropriate. A returned validator is advisory and can
become stale immediately.¶
A client receiving 412 MUST NOT retry solely by replacing its supplied
validator with the value returned in the error response. It MUST first obtain
or otherwise validate the current state and reconcile its intended action,
unless an application specification explicitly guarantees that such a retry
is safe.¶
Semantic-ETag is not an HTTP cache validator, does not define a cache key,
and does not replace ETag. A cache MUST NOT use it to validate a stored
response unless another specification explicitly defines complete cache
semantics for that use.¶
This specification deliberately does not define If-Semantic-None-Match and
does not permit an origin to return 304 Not Modified solely because semantic
state is unchanged. A 304 response authorizes reuse of a stored selected
representation; semantic equivalence does not imply byte-for-byte equality of
that representation.¶
Ordinary representation selection and caching continue to use Vary,
ETag, If-None-Match, and the rules of [RFC9110] and [RFC9111]. For example,
HTML and JSON representations can share a semantic validator while retaining
different ordinary ETags:¶
HTTP/1.1 200 OK Content-Type: text/html ETag: "html-en-v17" Semantic-ETag: "article-state-v42" Vary: Accept, Accept-Language¶
HTTP/1.1 200 OK Content-Type: application/json ETag: "json-en-v9" Semantic-ETag: "article-state-v42" Vary: Accept, Accept-Language¶
Content codings and other representation transformations affect ordinary
strong ETags according to HTTP semantics. They do not require a different
Semantic-ETag when the coded variants remain in the same semantic
equivalence domain.¶
Semantic-ETag MUST NOT be used to evaluate If-Range; semantic equivalence
does not establish byte-range compatibility.¶
The principal protocol risk is relying on a request field that an unaware
server ignores. Clients MUST obtain positive knowledge of enforcement before
using If-Semantic-Match as a safety condition. Servers and profiles SHOULD
make that knowledge specific to the resource and method rather than to an
entire origin.¶
Overbroad domains can authorize an action against state different from the state the client observed. Servers MUST include every mutation-relevant, authorization-relevant, and integrity-relevant value in the domain or split the domain. A semantic validator from one origin, tenant, language, or principal MUST NOT be applied to another unless a profile explicitly establishes the shared domain and trust relationship.¶
A non-atomic comparison permits multiple requests to pass against the same old state and reintroduces lost updates. All write paths to the domain must participate in the same serialization or compare-and-swap mechanism.¶
Semantic validators can reveal update frequency, correlate representations or authorization views, and expose internal revision information. Servers SHOULD use separate domains and privacy-preserving validator construction when such correlation is sensitive. Validators MUST NOT be treated as authentication, authorization, confidentiality, or content-integrity mechanisms.¶
Content-derived validators for low-entropy state can enable offline guessing. Servers can mitigate this with an HMAC, secret salt, opaque revision identifier, or another construction appropriate to their threat model. A construction that permits two mutation-relevant states to share a validator can cause an unsafe match; servers therefore need collision resistance appropriate to the domain and deployment lifetime.¶
A current validator or state returned with 412 can disclose information to
an unauthorized requester. Authentication and authorization checks MUST
precede such disclosure. Clients must treat returned conflict information as
untrusted and potentially stale.¶
IANA is requested to register the following field names in the "Hypertext Transfer Protocol (HTTP) Field Name Registry".¶
-00
This revision:¶
removes If-Semantic-None-Match and semantic 304 behavior;¶
defines exact comparison and one-way equivalence invariants;¶
requires positive resource-and-method-specific capability knowledge before a client relies on enforcement;¶
requires atomic compare, transition, and validator publication;¶
defines deferred-processing requirements;¶
prohibits blind retry based only on a validator returned with 412;¶
clarifies that Semantic-ETag is response metadata rather than an HTTP cache
validator; and¶
aligns the extension with AST Core, AST Semantic, and TCT layering.¶
A representation-oriented read can expose both validators:¶
GET /article/123 HTTP/1.1 Host: example.com Accept: text/html HTTP/1.1 200 OK Content-Type: text/html ETag: "html-v17" Semantic-ETag: "article-state-v42"¶
After obtaining positive knowledge that the target enforces semantic preconditions, the client can submit:¶
PATCH /article/123 HTTP/1.1
Host: example.com
Content-Type: application/merge-patch+json
If-Semantic-Match: "article-state-v42"
{"status":"draft"}
¶
A successful transition can return:¶
HTTP/1.1 204 No Content Semantic-ETag: "article-state-v43"¶
A conflict can return:¶
HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json
Semantic-ETag: "article-state-v44"
{
"type": "https://example.com/problems/semantic-precondition-failed",
"title": "Semantic precondition failed",
"status": 412,
"detail": "The resource state changed after the client constructed its update."
}
¶
The client retrieves or otherwise validates the current state, reconciles the intended change, and only then sends a new request.¶