Operations · Guide
A customer did not mention a phone number. That is not a delete request.
Distinguish omitted fields, null and array replacement in JSON Merge Patch so unknown data does not become a deletion.
A customer did not mention a phone number. That is not a delete request.
Original AAHouse explanatory video. AI-assisted conceptual visuals and neural narration; original music.
English transcript · Simplified Chinese Mandarin transcript · Taiwan Mandarin transcript · Macao Cantonese transcript
A note at the service desk
Imagine a U.S. bicycle repair shop. A customer asks: “Change the pickup note to Friday afternoon.” An AI assistant prepares a profile update. The existing record also contains a phone number. The key question is not whether the new note reads well, but what the tool encodes for the unmentioned phone field. This is a hypothetical change review, not a reported customer incident or measured result.
- Customer changes pickup note only
- Existing profile still has a phone number
- Review the change, not just the prose
Unchanged original source explanatory diagram.
Candidate A: phone is absent
If the endpoint explicitly implements JSON Merge Patch, a patch that changes pickupNote and omits phone leaves the existing phone member untouched.[1] Our recommendation is to represent the business intent first—change the note and retain other fields—then have deterministic code construct the allowed update. Do not fill unmentioned fields with null just to make the generated object look complete.
- Patch: pickupNote only
- phone is absent
- Result: existing phone is retained
Unchanged original source explanatory diagram.
Candidate B: phone is null
Under that same protocol, {"phone":null} removes an existing phone member; it does not mean “I do not know the number.”[1] An unknown value from extraction therefore should not flow directly into a write patch. Removing contact details needs explicit intent and the relevant permission. Syntactically valid output is not business authorization.
- Patch: {"phone": null}
- Merge Patch null → remove member
- Unknown information ≠ delete instruction
Unchanged original source explanatory diagram.
A list can be replaced wholesale
Suppose the customer also asks to add a weekend-contact tag. Do not automatically submit an array containing only that new tag. Merge Patch replaces an array as a whole rather than appending individual items.[1] Show reviewers the complete before-and-after list and any entries that disappear. If the API offers a dedicated append action, verify that action’s contract before choosing it.
- Before: [service reminder, email]
- Patch: [weekend contact]
- Replacement: prior entries are removed
Unchanged original source explanatory diagram.
Identify the format before interpreting it
These rules apply only after confirming the endpoint’s format. JSON Patch is different: it describes changes through an ordered sequence of operations such as add, remove and replace.[2] A shared HTTP PATCH method does not make the formats interchangeable. Record the actual Content-Type, vendor documentation and field constraints. If the business needs to store a literal null, confirm that the chosen contract expresses that intent unambiguously.
- Merge Patch: object-shaped changes
- JSON Patch: ordered operations
- Same PATCH method ≠ same semantics
Unchanged original source explanatory diagram.
A handoff acceptance sheet
Use synthetic profiles to rehearse four inputs: an omission, an explicit deletion, an empty string and a replacement list. Specify the expected differences first, inspect the final serialized request, and read back the result in an isolated environment. Our proposed acceptance criteria are unchanged unmentioned data, justified deletions and no unintended list loss—not merely a green JSON validator. This is a suggested test plan, not a test performed on your business system.
- Inputs: absent / delete / empty string / list
- Compare: intent → serialized request → result
- Pass: no unintended deletion or list loss
Unchanged original source explanatory diagram.
Keep “unknown” on the reading side
The team agreement can be short: reading may produce “unknown”; writing must distinguish retain, set and remove. AAHouse’s related guide, “Missing fields need a workflow,” covers the intake side. This article adds the write-semantics check. As structured output becomes easier to generate, making this business translation explicit remains important.
- Reading: known / unknown
- Writing: retain / set / remove
- Review differences, not just sentences
Unchanged original source explanatory diagram.