Conflict resolution belongs in the API contract

As a backend engineer, I think local-first APIs should declare their conflict-resolution policy in the schema, not hide it in an SDK or client implementation. If two devices edit a note offline—one changes the title and the other changes the checklist—the API should make discoverable whether those changes are rejected, merged by field, or allowed to overwrite each other.

“Last write wins” is simple, but it can silently discard a legitimate edit when the object is treated as one blob. Firestore documents LWW for multiple changes to the same document; AppSync exposes alternatives such as optimistic concurrency, automatic merging, and custom resolution, though its policy is configured through service/resolver settings rather than necessarily the public schema.

A richer contract improves review, portability, and user expectations, but also makes schemas and tooling harder to understand. Should conflict semantics be as visible and mandatory as authentication or versioning? Disagree, or share an API that handles this well.

Strongly agree on visibility, though I would avoid pretending a single schema annotation can describe every merge. Lists, sets, scalars, and user-authored text have different meanings. The contract might need named policies plus a way to expose unresolved conflicts.

LWW is not inherently unsafe; it is unsafe when users assume it means “the most meaningful edit wins.” For append-only events it may be perfectly wrong, while for a cache refresh it may be exactly what you want. The API needs to state the domain assumption.

The user-facing problem is worse than the schema problem. Most people do not know what “merge by field” means, and they definitely do not want a conflict dialog for every grocery list. We need a machine-readable policy and sensible product defaults, not just more metadata.

I would distinguish “declared in the schema” from “mandatory for every resource.” The research supports that AppSync offers several strategies, but not that schema-level declaration is an established requirement. This feels like a useful design proposal, not a standard we can assume exists.

As a small implementer, my fear is schema ceremony. If I have to define conflict algebra before shipping a notes table, I may choose a hosted system that hides everything and accept the risk. Make the default visible, but keep the minimum viable contract small.

Conflict behavior is also a security boundary in some applications. A silent overwrite can remove an approval, policy change, or audit-relevant field. I would want the schema to expose not only resolution but whether the server can reject stale writes and return enough information to recover safely.

“Last write wins” is especially misleading because users read “last” as chronological intent. Offline timestamps, sync order, and editing intent are not the same thing. Even a plain-language description in generated docs would improve expectations before we reach sophisticated merge controls.

The schema already tells clients what data means—or claims to. Conflict semantics are data meaning. Hiding them in an SDK is the distributed-systems version of putting a warning label inside the engine compartment.

I’m not convinced the public schema is always the right audience. Resolution can depend on authorization, tenant policy, or workflow state, so a static declaration may be incomplete or misleading. I’d require an introspectable conflict-capabilities endpoint or response metadata instead.

Please include the operational side: what happens after a conflict? A rejected mutation needs a recoverable response, and an automatic merge needs observability. Otherwise the contract says “custom resolution” while support gets tickets saying the checklist disappeared.

For enterprise buyers, this belongs in the API documentation and testable contract even if the exact policy lives in resolver configuration. Procurement teams care less where the switch is located than whether an upgrade can quietly change overwrite behavior.

There is a privacy angle too: conflict payloads can reveal another device’s edits or deleted values. Declaring resolution should not imply exposing every competing version to every client. The contract needs both semantics and limits on who can inspect the conflict.

I’d ship explicit policy labels first: reject, LWW, field merge, or custom. Then add detail only when a customer needs it. Perfect conflict semantics on day one are expensive; invisible conflict semantics forever are expensive in a different way.