The entity tag carries the body variant, not just the schema version
A missing variant in the tag was a live cross-repo cache bug: a client holding the plain body asked for the annotated one, was told it was unchanged, and went on serving a document with every title and description missing.
The rule
Normative: this is the rule
- The entity tag for a workflow schema is the quoted schema version for the plain document, and the quoted schema version plus a variant marker for the annotated one.
- Any request argument that changes the body must join the tag the same way: two documents that differ must never share a tag, whatever else varies on them.
What it means
The schema version alone is not enough to tag the response: ?annotated=1
returns a different body from the same version, so a tag keyed on the
version alone makes the two bodies indistinguishable to a conditional
request. A caller holding the plain body's tag can send it back while asking
for the annotated one and, if the tag does not carry the variant, be told
nothing has changed — and go on serving a document with every title and
description missing.
Example
GET /api/flowdrop/workflows/{id}/schema
ETag: "3.4.5"GET /api/flowdrop/workflows/{id}/schema?annotated=1
ETag: "3.4.5+annotated"Same workflow, same schema version, two tags that must never collide.
Rule identifiers are permanent and are never renumbered. Each implementation publishes its own standing against these rules; this specification does not.spec 1.0-draft · META-6 · changed in spec 1.0