]>

antunjurkovic@gmail.com

Web and Internet Transport HTTP, validator, concurrency, semantic state 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.

Introduction HTTP entity tags identify selected representations and support cache revalidation and conditional requests . 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.

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 is one such profile.

Relationship to TCT and AST The Collaboration Content Transfer protocol 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.

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 when, and only when, they appear in all capitals, as shown here. This document uses the Augmented Backus-Naur Form (ABNF) notation of and the list extension defined in Section 5.6.1 of . It imports the opaque-tag rule from Section 8.8.3 of .

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.

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. 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: 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.

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.
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) 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.

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.

The If-Semantic-Match Request Field The If-Semantic-Match request field makes a request conditional on the origin server's current semantic validator. 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.

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.

Evaluation with Standard Preconditions Standard HTTP preconditions retain their meanings and ordering under . After authentication, authorization, request validation, and other normal checks that precede precondition evaluation, an origin server MUST:

1. evaluate applicable standard HTTP preconditions according to ;
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.

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.

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.

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: 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.

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 and . For example, HTML and JSON representations can share a semantic validator while retaining different ordinary ETags: 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.

Security Considerations

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.

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.

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.

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.

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.

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.

IANA Considerations IANA is requested to register the following field names in the "Hypertext Transfer Protocol (HTTP) Field Name Registry".

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.

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.

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.

References Normative References The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. This document obsoletes RFC 7234. Informative References HTTP resources are frequently exposed in multiple representations (e.g., text/html for rendering and application/json for processing) via Content Negotiation. Standard HTTP validators such as ETags identify selected representations, while many applications need concurrency control over a shared logical resource state. This creates a synchronization gap where a client modifying one representation cannot guarantee consistency with the underlying state of another representation, leading to race conditions and "lost updates" in multi-client environments. This document specifies Agentic State Transfer (AST), an HTTP profile for managing Canonical Resource State (CRS) across multiple synchronized representations of the same resource. It defines a State-Bearing Representation (SBR) whose strong ETag acts as the AST semantic validator for the CRS. It further mandates the use of Optimistic Concurrency Control via If-Match headers for state-changing operations, ensuring that mutations applied by agents (whether automated clients, scripts, or human- driven applications) are atomic and consistent across all views. This document specifies the Collaboration Content Transfer (TCT) Protocol, an HTTP-based method for efficient, verifiable delivery of web content to automated agents. TCT defines a JSON envelope that encapsulates resource content in negotiated text-based formats (such as Markdown or plain text) together with canonical metadata. It uses bidirectional URL discovery between human-facing and machine-facing URLs, JSON sitemaps, strong ETag validators, and conditional requests to reduce bandwidth while preserving semantic structure and canonical identity. Cryptographic operations like hashing and signing need the data to be expressed in an invariant format so that the operations are reliably repeatable. One way to address this is to create a canonical representation of the data. Canonicalization also permits data to be exchanged in its original form on the "wire" while cryptographic operations performed on the canonicalized counterpart of the data in the producer and consumer endpoints generate consistent results. This document describes the JSON Canonicalization Scheme (JCS). This specification defines how to create a canonical representation of JSON data by building on the strict serialization methods for JSON primitives defined by ECMAScript, constraining JSON data to the Internet JSON (I-JSON) subset, and by using deterministic property sorting.

Appendix A. Complete Example A representation-oriented read can expose both validators: After obtaining positive knowledge that the target enforces semantic preconditions, the client can submit: A successful transition can return: A conflict can return: The client retrieves or otherwise validates the current state, reconciles the intended change, and only then sends a new request.