Network Working Group                                     A. Jurkovikj
Internet-Draft
Intended status: Standards Track                            12 May 2026
Expires: November 13, 2026

Semantic Validators for HTTP
draft-jurkovikj-http-semantic-validator-00

Abstract

   This document defines the Semantic-ETag HTTP response header field
   and two associated conditional request header fields.  Unlike the
   standard ETag field, which identifies a selected representation,
   Semantic-ETag identifies a server-defined semantic equivalence class
   for the underlying resource state.  This enables origin servers to
   support representation-independent validation and optimistic
   concurrency control across different representations, such as HTML,
   JSON, and Markdown views of the same logical resource.

   This document does not update or replace the semantics of the ETag
   header field defined in 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."

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

1.  Introduction

   The Hypertext Transfer Protocol (HTTP) [RFC9110] defines entity tags
   (ETags) as validators for selected representations.  ETags are used
   for cache validation, conditional requests, and optimistic
   concurrency control.  RFC 9110 distinguishes between strong and weak
   validators, but both are scoped to representation metadata rather
   than to an application-defined logical resource state shared across
   multiple representations.

   Many resources are exposed through several representations.  For
   example, a resource might have a browser-facing HTML representation,
   an API-facing JSON representation, and an editable Markdown
   representation.  A client might read one representation and later
   update another.  Standard representation validators are not
   sufficient to express that those representations were derived from
   the same underlying resource state.

   This document defines Semantic-ETag, a response header field that
   identifies a server-defined semantic equivalence class for the
   resource state.  It also defines If-Semantic-Match and
   If-Semantic-None-Match for conditional requests against that semantic
   validator.

   Semantic-ETag is intended for origin-server validation.  HTTP
   caches and intermediaries that do not explicitly implement this
   specification will not use Semantic-ETag for cache revalidation.

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

   Canonical Resource State (CRS):  A server-defined deterministic model
      of the logical resource state used to decide semantic equivalence.
      The CRS excludes representation-specific artifacts such as
      templates or insignificant serialization details, but includes all
      state that affects the resource's logical meaning, authorization,
      or integrity for the relevant equivalence domain.

   Semantic equivalence domain:  The scope within which a server
      considers two representations to have the same CRS.  The domain
      might be a single resource across media types, a tenant-scoped
      resource, an authorization-scoped view, or another server-defined
      boundary.

   Semantic validator:  The opaque value carried in Semantic-ETag that
      identifies the current CRS within a semantic equivalence domain.

3.  The Semantic-ETag Header Field

   The Semantic-ETag response header field provides the current semantic
   validator for the selected representation's resource state.

   Semantic-ETag = opaque-tag

   The weak prefix ("W/") MUST NOT be used in Semantic-ETag.  A
   recipient MUST NOT treat a weak entity-tag value as matching a
   Semantic-ETag.

   Semantic-ETag is representation metadata.  A server MAY include both
   ETag and Semantic-ETag in the same response.  The two fields are
   independent: ETag validates the selected representation, while
   Semantic-ETag validates the server-defined CRS for the applicable
   semantic equivalence domain.

3.1.  Generation and Equivalence

   A server that generates Semantic-ETag MUST construct its CRS in a
   deterministic and reproducible manner for the applicable semantic
   equivalence domain.

   Semantic-ETag values are opaque to clients.  A server MAY derive the
   value from a collision-resistant hash of the CRS, an HMAC, a revision
   identifier, a version vector, or another server-controlled mechanism,
   provided that the value changes whenever the CRS changes in a way
   that matters for semantic equivalence.

   If a server provides Semantic-ETag for multiple representations in
   the same semantic equivalence domain, the opaque string MUST be
   identical when the server considers their CRS identical, even if
   their standard ETag values differ.

   This specification does not define a universal CRS algorithm that
   different implementations can use to compute identical validators for
   the same real-world object.  Interoperability is defined at the HTTP
   field and conditional request level; semantic equivalence is defined
   by the origin server.

3.2.  CRS Construction Guidance

   CRS construction is application-specific.  Servers are encouraged to
   use deterministic normalization techniques when the underlying data
   model has a standard canonical form.  For example, if the CRS is
   represented as JSON, a server can apply the JSON Canonicalization
   Scheme (JCS) [RFC8785] before deriving a validator.

   Servers MUST include all state that affects authorization decisions,
   integrity, visible logical content, or mutation safety for the
   semantic equivalence domain.  Servers MUST NOT share a Semantic-ETag
   across representations or authorization contexts that do not have the
   same CRS.

4.  Conditional Requests with Semantic Validators

   This document defines two request header fields for conditional
   requests against Semantic-ETag.

4.1.  If-Semantic-Match

   The If-Semantic-Match request header field makes the request method
   conditional on the origin server's current semantic validator
   matching one of the provided validators.

   If-Semantic-Match = "*" / 1#opaque-tag

   If the field value is "*", the condition evaluates to true if the
   target resource has a current CRS in the applicable semantic
   equivalence domain, and false otherwise.

   If the field value is a list of validators, the condition evaluates
   to true if the current Semantic-ETag matches one of the provided
   validators.  Otherwise, the condition evaluates to false.

   If the condition evaluates to false, the origin server MUST NOT
   perform the requested method.  The origin server MUST respond with a
   412 (Precondition Failed) status code.

4.2.  If-Semantic-None-Match

   The If-Semantic-None-Match request header field makes the request
   method conditional on the origin server's current semantic validator
   not matching any of the provided validators.

   If-Semantic-None-Match = "*" / 1#opaque-tag

   If the field value is "*", the condition evaluates to false if the
   target resource has a current CRS in the applicable semantic
   equivalence domain, and true otherwise.

   If the field value is a list of validators, the condition evaluates
   to false if the current Semantic-ETag matches one of the provided
   validators.  Otherwise, the condition evaluates to true.

   If the condition evaluates to false for a GET or HEAD request, the
   origin server MUST NOT perform the requested method and MUST respond
   with a 304 (Not Modified) status code.  The origin server SHOULD
   include the current Semantic-ETag field in the 304 response when one
   is available.

   If the condition evaluates to false for any other request method, the
   origin server MUST NOT perform the requested method and MUST respond
   with a 412 (Precondition Failed) status code.

4.3.  Evaluation with Standard Preconditions

   If a request contains both standard HTTP conditional request header
   fields and semantic conditional request header fields, an origin
   server that implements this specification MUST evaluate all
   applicable preconditions.  If any required precondition evaluates to
   false, the server MUST NOT perform the requested method.

   Standard HTTP preconditions retain their meaning and precedence as
   defined by [RFC9110].  Semantic preconditions are evaluated by the
   origin server after representation-scoped preconditions that can fail
   the request have been evaluated, and before the requested method is
   performed.

   When both If-Semantic-Match and If-Semantic-None-Match are present,
   the origin server MUST evaluate both semantic preconditions.  The
   request proceeds only if both evaluate to true.

   If a semantic precondition fails and a standard precondition has not
   already determined a response status, the response status is:

   * 304 (Not Modified), when If-Semantic-None-Match fails for GET or
     HEAD.

   * 412 (Precondition Failed), for other semantic precondition
     failures.

   When returning 412 (Precondition Failed), the origin server SHOULD
   include the current Semantic-ETag field when one is available.  It
   MAY also include ETag if a selected representation validator is
   available and useful to the client.

5.  Interaction with Caches, Content Negotiation, and Range Requests

   Semantic-ETag does not replace ETag and does not define a cache key.
   Intermediaries MUST NOT use Semantic-ETag as a cache key for stored
   responses unless they explicitly implement this specification and all
   relevant HTTP caching requirements.

   A cache that does not implement this specification will treat
   Semantic-ETag as an ordinary extension field.  Such a cache will not
   use If-Semantic-Match or If-Semantic-None-Match for cache
   revalidation.  Clients that require semantic validation therefore
   SHOULD expect these preconditions to be evaluated by the origin
   server.

   Semantic-ETag does not itself create a Vary dimension.  However,
   servers MUST NOT use the same Semantic-ETag across content
   negotiation variants, tenants, authorization contexts, or other
   boundaries unless those variants are in the same semantic
   equivalence domain.

   Because Semantic-ETag guarantees semantic equivalence but not byte-
   for-byte identity, it MUST NOT be used to evaluate If-Range
   preconditions.  Servers MUST evaluate If-Range using only validators
   permitted by [RFC9110] for range requests.

6.  Security Considerations

6.1.  Overbroad Normalization

   If CRS construction omits state that affects authorization,
   integrity, or mutation safety, a client might incorrectly treat stale
   or unauthorized state as current.  Servers MUST include such state in
   the CRS or use a narrower semantic equivalence domain.

6.2.  Cross-Representation Confusion

   If two representations are generated from divergent internal models,
   they MUST NOT share a Semantic-ETag.  Sharing a semantic validator in
   that case can cause unsafe cross-representation updates.

6.3.  Validator Correlation

   Identical Semantic-ETag values can reveal that two representations,
   tenants, or authorization-scoped views share the same underlying CRS.
   If that correlation is sensitive, servers MUST use separate semantic
   equivalence domains or privacy-preserving validator construction.

6.4.  Validator Guessing and Tracking

   Predictable Semantic-ETag values can expose information about
   resource update frequency or internal revision state.  Servers
   SHOULD use validator construction mechanisms that do not reveal
   sensitive internal state when validators are exposed to untrusted
   clients.

6.5.  Cache Safety

   This specification defines Semantic-ETag as a separate field and does
   not alter ETag parsing.  This separation reduces the risk that legacy
   caches confuse semantic equivalence with representation identity.
   Nevertheless, servers SHOULD test deployments with intermediaries
   that might normalize, remove, or mishandle unknown fields.

7.  IANA Considerations

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

   Field Name:  Semantic-ETag
   Status:  Permanent
   Change Controller:  IETF
   Reference:  This document
   Notes:  This field uses the opaque-tag syntax and is not a Structured
      Field.

   Field Name:  If-Semantic-Match
   Status:  Permanent
   Change Controller:  IETF
   Reference:  This document
   Notes:  This field uses the opaque-tag syntax and is not a Structured
      Field.

   Field Name:  If-Semantic-None-Match
   Status:  Permanent
   Change Controller:  IETF
   Reference:  This document
   Notes:  This field uses the opaque-tag syntax and is not a Structured
      Field.

8.  References

8.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC5234]  Crocker, D., Ed., and P. Overell, "Augmented BNF for
              Syntax Specifications: ABNF", STD 68, RFC 5234,
              January 2008.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, May 2017.

   [RFC9110]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", STD 97, RFC 9110, June 2022.

8.2.  Informative References

   [RFC8785]  Rundgren, A., Jordan, B., and S. Erdtman, "JSON
              Canonicalization Scheme (JCS)", RFC 8785, June 2020.

   [I-D.jurkovikj-httpapi-agentic-state]
              Jurkovikj, A., "HTTP Profile for Synchronized Resource
              State in Agentic Workflows", Work in Progress, Internet-
              Draft, 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.

Author's Address

   Antun Jurkovikj
   Email: antunjurkovic@gmail.com
