Update one field on a passport

Patch a single field on a passport. The value is validated against the field key (must exist on the passport's template) and persisted with an audit trail entry naming the credential (via API key <prefix> or via OAuth app <client>) and, when the X-Source header is set, the calling client, e.g. (mcp). Use this in preference to writing the whole fields map when you only need to update one number — it's a smaller write and the per-field audit entry is what dashboard reviewers see.

The status follows who is writing, not the channel. An API key writes status: "approved" (it is a company-scoped service account). An OAuth token writes with its user's dashboard rights, so a role below admin lands pending_review. A value sent with source: "ai_suggested" always lands pending_review, and the request is refused (status 400) when only the economic operator may state the value or it must be measured (e.g. battery stateOfHealth); send it with another source if your organisation is making that statement. ai_approved and system are set by TracePass and are refused as request values.

An alternate addressing form exists at PATCH /api/v1/passports/by-serial/{serial}/fields/{key} — same body, same response, useful when your ERP only knows the customer-side serial. Counts as one v1 write. Honours Idempotency-Key.

No-op (200 unchanged: true): when the incoming value, computed status and source locale are all identical to the stored state, the endpoint skips the write entirely — no version bump, no audit entry, no snapshot — and returns 200 with unchanged: true alongside the current field and version. This prevents spurious version increments from ERP integrations that re-push the full product record on every sync cycle. The response body shape is the same as a real write; check the unchanged key to distinguish the two cases.

Required-field guard (400): once a passport is published, sending null or an empty string for a field that the regulation requires for this passport's category is refused with required_field_empty (HTTP 400). The fields array in the response body names every affected key. Drafts remain free to edit.

Size limits (400 / 413): a value may hold at most 1,000 array items (nested arrays included), 20,000 characters in any single string (each language of a translatable value counts separately) and 256 KB in total, nested at most 8 levels deep. A larger value is refused with field_value_too_large, naming the field, the limit type (items, characters, bytes or depth) and the limit. A request body declared larger than 1 MB is refused with 413 payload_too_large.

Write lock (409): once a passport is published, identity fields (gtin, serialNumber, uniqueProductIdentifier, globalUniqueProductIdentifier, productIdentifier, identifierStandard, batteryUniqueIdentifier, batteryIdDmcCode, batteryPassportIdentifier) cannot change if they already hold an approved value — the response is 409 identifier_locked with the field names in keys. A pending_review value can be corrected; an empty field can be filled. Writing the same value back (including a GTIN padded to 14 digits, or a whitespace-trimmed match) is accepted when the write keeps the value approved, as an API key does. A write with source: "ai_suggested", or from an OAuth user below admin, lands as pending_review and is refused. Writing to an archived passport returns 409 passport_archived. A concurrent write race returns 409 concurrent_update — reload and retry. Suspended and expired passports remain editable.