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, . 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, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . [RFC9111] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, June 2022, . 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, . [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, . [RFC8785] Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, DOI 10.17487/RFC8785, June 2020, . 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]