You are adding ETag-based preconditions to a resource with many independently edited fields and embedded sub-objects. How do you decide what the ETag value should be computed over, and what breaks if you choose badly?

## What the validator is promising An ETag is a promise: "if this token is unchanged, nothing you care about has changed." The design question is what *this* covers. Two failure directions exist, pulling in opposite ways. - **Too coarse** → false conflicts. One version per aggregate means an edit to a comment invalidates a pending edit to the shipping address. Clients see 412s for changes that could never have conflicted, and each costs a re-read, a re-merge, and possibly a user prompt. - **Too fine** → missed conflicts. If the validator covers only the fields you *think* the caller edits, a `PUT` that replaces the whole representation can still wipe fields outside the validator's scope, and the precondition happily passes. You have built ceremony with no safety. ## The rule that resolves it The validator must cover **at least** the union of (a) everything the write can modify and (b) everything the client's decision depended on. For a `PUT` that replaces the representation, that is the entire representation, so a whole-resource validator is the only correct choice. If that produces too many false conflicts, the fix is not a narrower validator on the same URL — it is **splitting the resource**. ## Splitting instead of narrowing If `note` and `shippingAddress` are independently edited, promote them: `PUT /orders/42/shipping-address` with its own ETag over the address only. Now write scope and validator scope match exactly, so the safety property holds while conflicts narrow. The parent `/orders/42` keeps a validator over the whole aggregate, which is right for callers that replace the whole thing. The cost is more URLs, more round trips to assemble a view, and a parent ETag that must change whenever a child does, or a cached parent goes stale. `PATCH` deserves special mention. A patch that only touches `note` conflicts with another patch only if that one also touched `note`, yet a whole-resource validator rejects both. Some teams accept the false conflicts for simplicity; others define field-scoped validators for a patch-only endpoint, which is defensible precisely because the write scope is narrow and explicit. If you do that, document it loudly — it changes what the 412 means. ## How to compute the value Prefer a monotonic version (or a hash over the version columns of the covered rows) rather than a hash over serialized response bytes. Byte hashes are seductive because they are automatic, but they bind the token to representation details: content negotiation, sparse fieldsets (`?fields=id,status`), field ordering, and serializer upgrades all change the bytes without changing state. A deploy then invalidates every outstanding validator and conditional writes fail all at once. Also decide about derived and volatile fields. If the representation embeds a computed `viewCount` or a recomputed price, including them makes the token churn on activity nobody edited. Keep such fields out of the aggregate's version, or move them to their own sub-resource. ## Judging the result in production Instrument it: measure the 412 rate and, where you can, how often the conflicting writes actually touched overlapping fields. A high 412 rate with low true overlap means the granularity is too coarse and the resource should be split. A near-zero rate alongside reports of lost edits means the validator is not covering what the write changes.