# How should an API distinguish a calculated value from a manual override? > Separate manual override intent, the calculated value, and the effective result so computed fields remain predictable when inputs change. Canonical URL: https://www.devobs.io/articles/qa-computed-field-overrides/ By: Owen Park Published: 2025-03-25T22:02:08.625Z Updated: 2026-09-06T08:31:04.426Z Section: Architecture Use separate fields for intent and result. The safest contract is: store the user’s manual override explicitly, expose the system-calculated value separately, and return a distinct effective value that the application actually uses. Add an explicit way to clear the override and return to automatic mode. Do not let clients write the same field that the server recalculates, or a normal update can accidentally freeze a derived value. ## What contract should the API expose? For HTTP APIs, treat the calculated value as server-owned output and the override as client-owned input. That matches the guidance in [Google AIP-203 field behavior documentation](https://google.aip.dev/203), which says `OUTPUT_ONLY` is appropriate for "Derived or structured information based on original user input" and that documented field behavior helps clients understand what they can send. It also fits the purpose of [the OpenAPI Specification](https://spec.openapis.org/oas/latest.html): a description should let consumers "discover and understand the capabilities of a service" without guesswork. A practical resource shape looks like this: - `calculated_price`: output only, recomputed by the server - `price_override`: optional nullable input, set only when a human wants to pin a value - `effective_price`: output only, equal to `price_override` when present, otherwise `calculated_price` - `price_source`: output only enum such as `CALCULATED` or `MANUAL_OVERRIDE` That makes ownership obvious. Clients never wonder whether writing `price` will be preserved, recalculated, or silently converted into a manual override. ## How does reset-to-automatic mode work? Make reset explicit. The cleanest rule is: `price_override = null` means “remove the manual override and resume calculation.” If you use PATCH semantics, the boundary is the single resource write processed by the service: evaluate the stored override state after applying the patch, then recompute `effective_price` for that resource before returning it. That is the ordering guarantee you want. Avoid advice that depends on a separate read, client-side comparison, and later write. Worked example: 1. Product base inputs change, and the server computes `calculated_price = 1200`. 2. A merchandiser sets `price_override = 999`. 3. The API returns `effective_price = 999` and `price_source = MANUAL_OVERRIDE`. 4. Later, cost inputs change again. The server may recompute `calculated_price = 1100`, but `effective_price` stays `999`. 5. The merchandiser clears `price_override`. 6. The API returns `effective_price = 1100` and `price_source = CALCULATED`. This prevents the classic failure mode where a user edits some unrelated field and accidentally persists yesterday’s derived number as if it were authoritative. ## When does this pattern apply, and when does it not? Use this contract when the derived value belongs to server-side business rules, but a human may temporarily supersede it. Pricing, fulfillment dates, risk scores, shipping promises, and inventory buffers fit well. Do not use it when the value is purely client-local presentation data, or when the “override” is really a different upstream input to the formula. In that case, model the underlying input instead of adding an override layer. Also avoid a single writable `mode` field unless the mode has independent business meaning. In many APIs, the presence or absence of `price_override` already encodes the state with less room for contradiction. ## What should the API documentation make unambiguous? Document three things directly in the schema: - which fields are writable versus output only - what clearing the override means - when recalculation happens relative to the resource write In OpenAPI, reflect the split clearly in request and response schemas so SDK and docs do not imply that derived fields are normal inputs. ## Follow-up: Should I expose both `effective_price` and `calculated_price`? Yes, if operators need to see what the system would choose automatically. Keep both when auditability or UI explainability matters. ## Follow-up: Should a manual override expire automatically? Only if expiry is a business rule users can understand. If you add it, model it explicitly with fields such as an override timestamp or expiration time, not hidden recalculation behavior. Next step: pick one resource with an overridable derived field and rewrite its schema so override intent, calculated output, and reset behavior are separate and testable. Reviewed: 2026-09-05. ## Source references - -