Semantic Validators for HTTP
draft-jurkovikj-http-semantic-validator-01
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Antun Jurkovikj | ||
| Last updated | 2026-08-05 (Latest revision 2026-07-27) | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Additional resources |
Four-draft guided reconciliation story
Interactive Semantic Validators and AST timeline Source for the browser-only protocol demos |
||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-jurkovikj-http-semantic-validator-01
Network Working Group A. Jurkovikj
Internet-Draft 27 July 2026
Intended status: Standards Track
Expires: 28 January 2027
Semantic Validators for HTTP
draft-jurkovikj-http-semantic-validator-01
Abstract
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.
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 28 January 2027.
Copyright Notice
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.
Jurkovikj Expires 28 January 2027 [Page 1]
Internet-Draft HTTP Semantic Validators July 2026
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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Relationship to TCT and AST . . . . . . . . . . . . . . . 4
2. Conventions and Terminology . . . . . . . . . . . . . . . . . 4
3. The Semantic-ETag Response Field . . . . . . . . . . . . . . 5
3.1. Generation and Equivalence Requirements . . . . . . . . . 5
3.2. Comparison . . . . . . . . . . . . . . . . . . . . . . . 6
4. The If-Semantic-Match Request Field . . . . . . . . . . . . . 6
4.1. Capability Requirement . . . . . . . . . . . . . . . . . 7
4.2. Evaluation with Standard Preconditions . . . . . . . . . 7
4.3. Atomic Compare-and-Commit . . . . . . . . . . . . . . . . 8
4.4. Deferred Processing . . . . . . . . . . . . . . . . . . . 8
4.5. Successful and Failed Responses . . . . . . . . . . . . . 9
5. Interaction with HTTP Caching and Representations . . . . . . 9
6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
6.1. Enforcement Downgrade . . . . . . . . . . . . . . . . . . 10
6.2. Equivalence-Domain Confusion . . . . . . . . . . . . . . 10
6.3. Atomicity and Competing Writers . . . . . . . . . . . . . 10
6.4. Disclosure, Correlation, and Tracking . . . . . . . . . . 11
6.5. Guessing and Collision Resistance . . . . . . . . . . . . 11
6.6. Conflict Information . . . . . . . . . . . . . . . . . . 11
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
7.1. Semantic-ETag . . . . . . . . . . . . . . . . . . . . . . 11
7.2. If-Semantic-Match . . . . . . . . . . . . . . . . . . . . 12
8. Changes Since -00 . . . . . . . . . . . . . . . . . . . . . . 12
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
9.1. Normative References . . . . . . . . . . . . . . . . . . 12
9.2. Informative References . . . . . . . . . . . . . . . . . 13
Appendix A. Appendix A. Complete Example . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction
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.
Jurkovikj Expires 28 January 2027 [Page 2]
Internet-Draft HTTP Semantic Validators July 2026
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.
1.1. Scope
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.
Jurkovikj Expires 28 January 2027 [Page 3]
Internet-Draft HTTP Semantic Validators July 2026
1.2. Relationship to TCT and AST
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.
2. Conventions and Terminology
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].
*Semantic state* 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.
*Semantic equivalence domain* 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.
*Semantic validator* The opaque value carried by Semantic-ETag that
identifies a current semantic state within one semantic
equivalence domain.
*State-changing request* 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.
Jurkovikj Expires 28 January 2027 [Page 4]
Internet-Draft HTTP Semantic Validators July 2026
3. The Semantic-ETag Response Field
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.
3.1. Generation and Equivalence Requirements
Within one semantic equivalence domain, an origin server MUST satisfy
all of the following invariants:
1. Equal current Semantic-ETag values imply semantically equivalent
state.
2. Every change to state relevant to mutation safety changes the
semantic validator before or atomically with publication of the
changed state.
Jurkovikj Expires 28 January 2027 [Page 5]
Internet-Draft HTTP Semantic Validators July 2026
3. A validator is not reused across authorization contexts, tenants,
or other boundaries that do not expose the same mutation-relevant
state.
4. 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.
3.2. Comparison
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.
4. The If-Semantic-Match Request Field
The If-Semantic-Match request field makes a request conditional on
the origin server's current semantic validator.
If-Semantic-Match = "*" / 1#opaque-tag
Jurkovikj Expires 28 January 2027 [Page 6]
Internet-Draft HTTP Semantic Validators July 2026
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"}
4.1. Capability Requirement
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.
4.2. Evaluation with Standard Preconditions
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:
Jurkovikj Expires 28 January 2027 [Page 7]
Internet-Draft HTTP Semantic Validators July 2026
1. evaluate applicable standard HTTP preconditions according to
[RFC9110];
2. if no standard precondition has already determined the response,
evaluate If-Semantic-Match; and
3. 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.
4.3. Atomic Compare-and-Commit
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.
4.4. Deferred Processing
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.
Jurkovikj Expires 28 January 2027 [Page 8]
Internet-Draft HTTP Semantic Validators July 2026
4.5. Successful and Failed Responses
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.
5. Interaction with HTTP Caching and Representations
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
Jurkovikj Expires 28 January 2027 [Page 9]
Internet-Draft HTTP Semantic Validators July 2026
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.
6. Security Considerations
6.1. Enforcement Downgrade
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.
6.2. Equivalence-Domain Confusion
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.
6.3. Atomicity and Competing Writers
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.
Jurkovikj Expires 28 January 2027 [Page 10]
Internet-Draft HTTP Semantic Validators July 2026
6.4. Disclosure, Correlation, and Tracking
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.
6.5. Guessing and Collision Resistance
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.
6.6. Conflict Information
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.
7. IANA Considerations
IANA is requested to register the following field names in the
"Hypertext Transfer Protocol (HTTP) Field Name Registry".
7.1. Semantic-ETag
* Field Name: Semantic-ETag
* Status: permanent
* Structured Type: not applicable
* Reference: this document
* Comments: single opaque-tag response field; weak entity-tag syntax
is not permitted.
Jurkovikj Expires 28 January 2027 [Page 11]
Internet-Draft HTTP Semantic Validators July 2026
7.2. If-Semantic-Match
* Field Name: If-Semantic-Match
* Status: permanent
* Structured Type: not applicable
* Reference: this document
* Comments: conditional request field using "*" / 1#opaque-tag;
clients require positive knowledge of enforcement before relying
on it for safety.
8. Changes Since -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.
9. References
9.1. Normative References
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/rfc/rfc9110>.
Jurkovikj Expires 28 January 2027 [Page 12]
Internet-Draft HTTP Semantic Validators July 2026
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/rfc/rfc5234>.
[RFC9111] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Caching", STD 98, RFC 9111,
DOI 10.17487/RFC9111, June 2022,
<https://www.rfc-editor.org/rfc/rfc9111>.
9.2. Informative References
[I-D.jurkovikj-httpapi-agentic-state]
Jurkovikj, A., "HTTP Profile for Synchronized Resource
State (Agentic State Transfer)", Work in Progress,
Internet-Draft, draft-jurkovikj-httpapi-agentic-state-01,
16 May 2026, <https://datatracker.ietf.org/doc/html/draft-
jurkovikj-httpapi-agentic-state-01>.
[I-D.jurkovikj-collab-tunnel]
Jurkovikj, A., "The Collaboration Content Transfer (TCT)
Protocol", Work in Progress, Internet-Draft, draft-
jurkovikj-collab-tunnel-02, 12 May 2026,
<https://datatracker.ietf.org/doc/html/draft-jurkovikj-
collab-tunnel-02>.
[RFC8785] Rundgren, A., Jordan, B., and S. Erdtman, "JSON
Canonicalization Scheme (JCS)", RFC 8785,
DOI 10.17487/RFC8785, June 2020,
<https://www.rfc-editor.org/rfc/rfc8785>.
Appendix A. Appendix A. Complete Example
A representation-oriented read can expose both validators:
Jurkovikj Expires 28 January 2027 [Page 13]
Internet-Draft HTTP Semantic Validators July 2026
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.
Author's Address
Antun Jurkovikj
Email: antunjurkovic@gmail.com
Jurkovikj Expires 28 January 2027 [Page 14]