eduKate Singapore

VIEW THIS AS

Auto mode follows the Route Engine until you choose a viewpoint.

YOU ARE HERE

ROUTE CHECK

CONNECTED TO

WHAT NEXT

Use the canonical route for this room, or HELP if you are unsure.

Next useful routeCanonical hubHELP

How Superintelligence Works | Agent JSON Patch — Pointer Escapes, Atomic Edits and Safe Preconditions

—

by

eduKate Asia

Did you know? An AI agent can use a perfectly valid JSON document to describe an edit and still change the wrong field. JSON Patch is a standard language for changing an existing JSON document, but its path syntax, array positions and operation order are exact. The safe method is to identify the intended resource and version, validate every path and operation, require preconditions on fragile assumptions, apply the patch atomically under the server’s rules, and read the saved state back. A syntactically accepted patch is not proof that the intended real-world change happened.

The reader’s concrete problem is how to make a narrow change—say, adjust one quantity in a shared inventory record—without replacing the entire resource or swallowing somebody else’s concurrent work. RFC 6902 defines six JSON Patch operations: add, remove, replace, move, copy and test. RFC 6901 defines the pointer syntax used by their paths. An HTTP PATCH request is distinct from a full PUT and has atomic application rules. However, none of those standards automatically grants an agent permission to edit an account, verifies a business rule, or guarantees protection from a stale read.

This is present-day API and agent engineering, not a claim that artificial superintelligence exists. All payloads, quantities and records in the worked examples are fictional. The official protocols are cited directly so an engineer can test their own service rather than trusting the plausible appearance of an illustrative request.

Contents

The actual job: change only what the user authorised

Suppose a user says, “Increase the stock quantity for the blue notebook to five.” The agent reads a JSON record containing product identifiers, quantities, reorder limits and historical notes. Its authorisation is narrow: identify the right notebook and change the one quantity if the business rule permits. It does not authorise deleting another item, modifying the supplier’s cost, resetting an audit counter or rewriting an entire record from the agent’s memory. A patch can express an authorised intention precisely, but only after the system knows what that intention is.

The distinction begins before syntax. The agent needs a trusted resource identifier, account or tenant scope, allowed fields, expected version, and a definition of success. “The second item” may be how the user describes the row on a screen; it is not necessarily a durable identifier. A JSON array position can move when another worker inserts a record. A product ID is better for discovering the intended target, but the patch still must use the API’s supported path semantics.

Treat the fetched document as evidence about current state, not a command source. It can contain a string that resembles a new instruction, a URL, or a proposed tool action. None of those values grants authority to change scopes. The agent should translate the human’s approved request into a minimal structured change under a separate policy validator. Prompt text and object contents should not become replacement access controls.

This topic differs from the existing concurrent document edits guide. That article covers general versioned document cooperation. Here the focus is the byte-level and value-level semantics of JSON Patch: operation sequences, pointer escaping, array positions, conditional tests, and the distinction between an accepted protocol operation and a checked business outcome.

What RFC 6902 actually specifies

A JSON Patch document is a JSON array of operation objects, processed in order. Each operation includes an “op” member naming its operation and a “path” member holding a JSON Pointer. Some operations need “value”, and move and copy need “from”. The registered media type is application/json-patch+json. A conventional request carries this format to a resource that explicitly supports it; not every endpoint accepting PATCH supports JSON Patch.

The six standard operations have different rules. Add places a value in an object or array at a permitted target, and it can replace an existing object member. Remove deletes an existing target. Replace requires an existing target and substitutes a value. Move removes a value from one location and adds it to another, with restrictions on source and destination. Copy copies a value from an existing source. Test compares the current target value with a supplied expected value and fails if they differ.

These are not mere English verbs. The distinction between adding a new member and replacing an existing one matters in safety-critical edits. An add to an existing object key can overwrite it under RFC 6902 semantics, while a replace of a missing member is an error. Code that assumes “add can never overwrite” may inadvertently change sensitive existing data. Validation must enforce task-specific rules on top of the protocol.

The normative authority is RFC 6902, JavaScript Object Notation (JSON) Patch. Its examples show that operations are sequential and that a failed test invalidates the intended patch. It also distinguishes the JSON Patch representation from other JSON update mechanisms. Engineers should use this specification rather than copy an informal array-operation recipe from a forum.

The server remains the enforcement point. A client can choose a minimal patch, but a malicious or confused caller might submit a different array. The server must still authenticate, authorise, validate shape, apply protocol rules, enforce business invariants and record the outcome under its own transaction and persistence model.

JSON Pointers: why a slash in a key is not a path separator

RFC 6901 names a location using a JSON Pointer. An empty pointer string refers to the entire document. A pointer such as /order/items/0/quantity follows the key “order”, then the key “items”, then array index zero, then the key “quantity”. This is a path over parsed JSON values, not a filesystem path, JSONPath query or SQL selector. A pointer points to one location under the standard’s resolution rules.

Object keys can contain a slash or a tilde. The pointer syntax must escape a tilde as ~0 and a slash as ~1 within a reference token. Therefore a field literally named “tax/rate” is addressed by /tax~1rate, not /tax/rate. A field named “a~b” is addressed by /a~0b. The slash separates tokens only when it is not represented by the escape sequence inside a token.

Decode escaping in the specified order: convert ~1 to / first, then ~0 to ~. Consider a literal key “~1”. Its encoded reference token is ~01. Correct decoding first leaves ~01 unchanged by the ~1 rule, then turns ~0 into ~, producing “~1”. A decoder that replaces ~0 first would create “~1” and then incorrectly convert it to “/”, selecting the wrong member. This is an excellent tiny unit test of a pointer library.

The pointer string “” and “/” are different. The empty string refers to the root. The pointer “/” refers to a root object member whose key is the empty string. Likewise numeric-looking object member names should not be treated as array indexes when the current value is an object. Resolve the path against the actual parsed type at each step rather than guessing by appearance.

The authoritative source is RFC 6901, JSON Pointer. An agent should use a well-tested standard-conforming implementation and verify that paths resolve to the intended fields. Path correctness is an independent gate from whether the replacement value itself is reasonable.

Array indexes, insertion and the dangerous meaning of minus

Array indexes are zero-based. Suppose items is [A, B, C]. The pointer /items/1 refers to B in the current document. Add at /items/1 inserts before B, resulting in [A, new, B, C]. It does not simply overwrite B. Replace at /items/1 changes B to the new value without shifting the remaining items. Remove at /items/1 removes B, shifting C into index one.

For an add operation on an array, the special final path token “-” indicates an append. It is not an ordinary array index that test or replace can use to address the latest element. A coding agent that routinely emits /items/- for all changes will violate the operation rules and may append records when the user meant to correct existing records.

Array positions can be unstable across time. An agent reads index one as product B, but another editor inserts a product ahead of B before the patch arrives. The same numeric path now points to a different item. A test operation on /items/1/id can catch that mismatch if included and if the service applies the whole sequence to the correct version. A stronger approach combines a resource version condition with identity checks.

Duplicate identifiers within an array complicate matters further. Do not claim a product ID uniquely identifies a row unless the server enforces uniqueness. A patch protocol does not know the application’s identity rules. If duplicate IDs are valid, the user may need an immutable row identifier or other disambiguating key. A search result in an agent’s context cannot by itself supply that guarantee.

Before committing array edits, rehearse the transformation on a safe copy of the actual snapshot. Compare ordered identifiers before and after, not only the changed numeric value. If a request fails on a shifted index, fetch and re-resolve the intended object; do not blindly repeat the same array-position patch.

Reading six operations as precise state transitions

A useful mental model is that each patch operation has a pre-state, a target location and a new state. Add may introduce or overwrite an object member and insert into an array. Remove deletes an existing location. Replace requires an existing location, preserving the structural position while changing its value. For each operation, the validator should ask whether the path exists when required and whether this caller may affect that path.

Move and copy use a “from” pointer. Copy reads the source value and places a copy at the destination. Move removes the source and places its value at the destination; RFC 6902 forbids moving a value into its own child. These operations can have unintuitive effects on arrays because removing the source shifts indexes before the destination is interpreted in sequence. Test small examples and avoid using a move operation as a convenient way to conceal reordering.

Test does not change the resource. It asserts that the addressed current value matches a supplied JSON value under the RFC’s structural equality rules. An object comparison does not depend on the serialized order of its members. Numbers are compared by value under the specified JSON number semantics, and arrays preserve element order. A mere substring check on raw JSON text is not an adequate implementation of test.

Operation order matters. A test placed after a replace checks the replaced value, not the original. In an optimistic update, test expected old values before changing them. A failing operation prevents the intended patch from being deemed successful; for an HTTP PATCH server, the atomicity rule means the server must not expose a partially applied update. Clients still need to verify the resource and any external side effects according to the service contract.

Whenever a change can be expressed as a simple replace, prefer an explicitly allowed replace rather than an elaborate move and copy sequence. Fewer operations reduce the number of fragile assumptions. Minimality is not merely elegance: it helps reviewers see what was authorised, what changed and which invariants remain unaffected.

Worked case: two quantities, a protected version and a checked total

Here is a fictional record. An inventory resource has version 7 and items A and B. Item A has quantity 2 and unit value $4; item B has quantity 3 and unit value $6. The user authorises changing B’s quantity to 5 and appending one unit of a new item C valued at $10. The total value before the change is 2×$4 + 3×$6 = $8 + $18 = $26.

The agent first verifies that B really is at /items/1 and that the resource is version 7. It can prepare a sequence conceptually equivalent to: test /version equals 7; test /items/1/id equals “B”; replace /items/1/quantity with 5; add the C object at /items/-; replace /version with 8. All operations belong in one patch transaction on the intended resource. The server must still enforce access control and validate that new item C is allowed.

Under these fictional assumptions, the new total becomes 2×$4 + 5×$6 + 1×$10 = $8 + $30 + $10 = $48. The change is $48−$26=$22. That increase has two components: B’s extra two units add 2×$6=$12, and C adds $10. Checking $12+$10=$22 confirms the arithmetic from a different direction. Quantity and monetary totals are different fields; neither should be inferred from a model’s prose without calculation.

The JSON Patch standard itself does not automatically recompute the total value. If total is stored and maintained by the server, the business layer should derive it from authoritative quantities and prices or verify consistency before commit. If the patch independently supplies a total, the server should not trust it merely because it equals the agent’s stated sum. Unit prices may change, discounts may exist and tax rules may be applied elsewhere.

After the API reports success, fetch the resource with its authoritative identifier. Confirm version, B’s immutable ID, B’s new quantity, C’s new row, A’s unchanged quantity and the server’s reported total or derived value. The result should explicitly distinguish “patch accepted”, “resource read back as intended” and any downstream stock-count or accounting update, which might use a separate system.

Concurrent edits: the server’s current version must win

Imagine two workers read inventory version 7. Worker one submits an authorised change, and the server saves version 8. Worker two has a patch built from the old version 7 and refers to /items/1. If it simply sends that patch unconditionally, the array may have changed in the meantime and its original assumptions may be false. A model’s memory of version 7 has no power to freeze the resource.

A test operation on the /version value is useful, but an HTTP conditional request can provide a stronger resource-level precondition. RFC 5789 advises use of a conditional request such as a strong ETag in If-Match when a patch depends on a known base. If the resource version no longer matches, the server can refuse the update without applying the changes. This is the right kind of failure: it preserves other people’s work and gives the agent a chance to rebase its intent.

The governing protocol is RFC 5789, PATCH Method for HTTP. It requires atomic application of the directly affected resource changes. A server should not expose a half-applied patch if one operation fails. Application services should specify how ETags are calculated, what condition is accepted and whether the patch updates a field that is itself an application version counter.

Preconditions are not interchangeable. Test on /version compares a JSON value during patch evaluation; If-Match compares a validator on the resource representation under HTTP semantics. A field-level test can prevent changing the wrong row even when a representation’s ETag is valid; an ETag can detect a broader update that a field-level test does not mention. Use both when the task and API justify their separate protections.

On a version mismatch, do not automatically replace the new version value with 8 and resend the rest of the old patch. Fetch the current resource, re-identify the target B, examine the competing edit and reconstruct a new patch if the user’s intent is still valid. If the two edits change the same business field incompatibly, escalate to the appropriate owner.

Atomic does not mean every external side effect is rolled back

HTTP PATCH atomicity means the patch modifications to the directly affected resource must not leave a partially modified representation when application fails. This is essential: otherwise a failed test after a replace could produce a half-written state. However, a practical API may trigger workflows, messages or notifications outside that resource. Whether those side effects participate in a wider transaction is an application design question, not an automatic property of RFC 6902.

Suppose the server validates and saves a quantity, then asynchronously posts an inventory-changed event. If the event delivery fails, the saved quantity can still be correct. The agent must not interpret lack of an event as proof the patch was rejected. Conversely, an event arriving at a consumer is not proof that a particular user’s permitted change was committed under the intended record version. Treat each component’s receipt separately.

A robust architecture can use a transactional outbox to couple database changes with durable event intent, but that is a broader workflow decision. The transactional outbox guide describes how to reason about reliable events. A JSON Patch client should observe final resource state and any required downstream effect through the source of truth responsible for each.

Repeated PATCH requests need special care. Some patches are naturally idempotent, for instance replacing a field with an exact value under appropriate assumptions. Others, such as adding a new array element, can append a duplicate every time. The PATCH method is not inherently idempotent. After an unknown network outcome, read and reconcile before trying again.

Keep a durable change receipt containing resource ID, intended version, patch hash or operation summary, request identifier where supported, server result, readback version and observed changed fields. This is not a reason to store secrets or unnecessary personal data; records should match the system’s privacy and audit policy.

JSON Patch is not JSON Merge Patch

JSON Patch and JSON Merge Patch sound similar but have different shapes and semantics. JSON Patch uses an array of explicit operations with paths. JSON Merge Patch, defined in RFC 7396, uses an object-like merge document and treats a null value specially as a request to remove a member. It does not provide the same ordered test, move or copy operations. Arrays in merge patch are treated differently from fine-grained JSON Patch array insertions.

For instance, if a resource contains {“notes”:”keep”,”status”:”draft”}, the JSON Merge Patch document {“status”:”ready”} changes status without deleting notes. But if a merge patch contains {“notes”:null}, that requests removal of the notes member; it is not an instruction to store a JSON null there in the usual object merge semantics. JSON Patch can use replace to store an actual null value at an existing path. The difference matters whenever null itself has business meaning.

The normative reference for the other format is RFC 7396, JSON Merge Patch. A service’s advertised supported media types determine which format is accepted. An agent should not guess based solely on the HTTP verb PATCH. Sending JSON Patch to a merge-patch endpoint may fail, or worse, an endpoint might interpret a payload under an undocumented rule.

Choose the format from the API contract and the reader’s intended operation. Fine-grained guarded array edits are a strong use case for JSON Patch. Simple partial updates of object members may fit JSON Merge Patch if null-removal behaviour is understood. A conventional full resource replacement may be preferable for some strongly versioned systems. No format obviates business validation or concurrency checks.

When preparing tools for an AI system, make the accepted content type, path conventions, allowed operation names, error codes and version controls explicit. This prevents a generic model from improvising a patch language that resembles two distinct standards but follows neither reliably.

Validation needs two layers: syntax and business rules

A standards-conforming JSON Patch parser answers whether the payload is a valid patch and whether the operations resolve under the current document. That is necessary but not sufficient. A tenant-specific application may forbid an agent from changing billing details, deletion flags, owners, security policy or protected identifiers even though those fields exist and a replace operation could technically address them.

Authorisation should be bound to the authenticated principal, resource, action and field where the application supports field-level policy. A path allowlist can help for narrow tools, but implement it on parsed pointer tokens rather than raw string prefixes. A string check that accepts everything starting with “/items” could accidentally allow unrelated fields named /itemsSecret. Exact matching and a typed schema are safer than substring checks.

Value validation must consider types, ranges, units and cross-field constraints. Setting quantity to the JSON string “five” may satisfy the instruction in natural language but violate an integer field requirement. Setting quantity to -500 may be syntactically valid JSON but violate stock rules. Changing currency without adjusting amount units may silently corrupt financial meaning. Reject untrusted or unsupported values before commit.

If the schema allows unknown fields, distinguish forward compatibility from unbounded writing. A new field may be useful in a legitimate API version, but it should not become a way to smuggle executable instructions, references to private accounts or arbitrary workflow triggers into an otherwise narrow tool call. A patch’s path and value should both be reviewed against the authorised task.

An agent can propose a candidate operation list, but a deterministic server-side validator should enforce the envelope. The broader structured output validation guide covers valid JSON and tool boundary checks; the JSON Patch problem adds operation ordering, pointer resolution and conditional mutation of existing state.

Why an attacker likes tiny patches

Small changes can have large consequences. Replacing a single “owner” identifier or “allowExternal” Boolean may create a privilege escalation without changing much text. A diff of only one line is not evidence that the action is safe. The agent must check whether the field is sensitive and whether the actor is entitled to modify it under the current tenant and workflow.

Pointer confusion can become a security problem. An API might accept a key containing ‘/’ or ‘~’ and a poorly implemented filter might inspect only the raw path, while the patch engine resolves escaped tokens into sensitive names. The enforcement layer must decode and normalise pointers consistently with the engine and then validate exact resolved targets. Do not rely on visual similarity between two path strings.

Array operations can also bypass naive field checks. If a policy forbids replacing /roles/0 directly but allows an add to /roles/0, the resulting shift can change role ordering or interpretation. Evaluate the semantic effect of each operation, not merely whether its verb sounds benign. An allowlist must cover all permitted combinations of operation and target.

For an untrusted remote object, use the server’s real authenticated resource binding, never a resource identifier the model learned only from an external document. If the user requested work on tenant A, an item’s field that mentions tenant B does not grant cross-tenant authority. Each patch tool call should be independently scoped by a trusted identity and the current request.

Audit logs need care. Store enough to investigate which fields changed and why, but do not indiscriminately log every sensitive before-and-after value. Data minimisation, retention and access rules still apply. An agent’s helpful diagnostic description must not inadvertently expose secrets in a public comment or notification.

Twelve practical failure patterns and their repairs

Failure one: the model treats / as a JSON member name rather than a path separator. Repair by using RFC 6901 tokenisation and explicit escaping. Failure two: a decoder processes ~0 before ~1 and resolves the wrong key. Repair with a “~01” unit test. Failure three: the model assumes “/” means document root. Repair by distinguishing the empty root pointer “” from the empty-name member “/”.

Failure four: add at an array index is treated as replace. Repair by testing insertion and index shifting. Failure five: an append path “-” is used with replace. Repair by enforcing operation-specific pointer rules. Failure six: a stale array index names another item. Repair with stable identity checks and a current version precondition.

Failure seven: a later failed test leaves an earlier replace saved. Repair by requiring proper atomic server application and verifying rollback behaviour in test environments. Failure eight: a caller uses JSON Merge Patch syntax against a JSON Patch endpoint. Repair by checking Content-Type and the documented resource contract.

Failure nine: an agent writes outside its field authority because the server assumes every valid patch is authorised. Repair with principal, resource and field-level checks. Failure ten: a business total is trusted from a model instead of recomputed from authoritative values. Repair with deterministic unit-aware validation.

Failure eleven: an unknown timeout is treated as definitive failure and an add is blindly retried, producing duplicates. Repair by fetching the authoritative state before retry. Failure twelve: the model reports a successful financial or stock update merely because a JSON parser accepted the request. Repair by recording the server acknowledgement and reading back the exact committed fields.

The shared diagnosis is to locate the earliest unverified assumption. Is it resource identity, pointer resolution, permission, current version, operation semantics, business value or saved outcome? Repair at that boundary. Adding a more elaborate prompt is not a substitute for a server that enforces the boundary mechanically.

Recovery after a lost network response

Imagine the inventory patch was transmitted, but the client connection dropped before the response reached the agent. There are at least three possibilities: the request never reached the server, it reached the server and failed, or it succeeded and only the acknowledgement was lost. A fourth is that the patch succeeded and another authorised worker has since made a further edit. Repeating the original request without checking could corrupt state.

The first recovery action is a fresh read from the authoritative API. Identify the same resource, current version and stable row identifiers. If the desired effect is already present and consistent, record completion based on that evidence. If the patch was rejected with a version mismatch, explain the conflict and reconstruct a new candidate against current data. If the state is still uncertain, do not invent a completed outcome.

If an item append has already happened, the new C item will exist under its stable ID. A second append could create another C row if uniqueness is not enforced. A model’s output repeating “append C” twice is not an idempotency strategy. Where possible, the API should support operation identifiers or idempotency keys in addition to conditional versions. The idempotency guide explains how to handle tool calls with uncertain responses more generally.

Retry only when the reconciled state shows the intended change is absent and the operation remains authorised. Re-run relevant preconditions and watch for a changed schema or business limit. Limit retries so a persistent validation failure does not become uncontrolled repeated traffic. For a non-transient refusal, seek human resolution rather than attempting a series of alternate paths around policy.

The final response should identify exactly what was verified: “The inventory API shows product B quantity five at version eight, and item C is present once.” Do not claim the physical shelf has five units unless that was separately measured. Keeping the scope of the claim aligned with the evidence is a key engineering habit.

Transfer exercise: change a schedule without shifting the wrong person

Now move from inventory to a staff rota. A fictional JSON document has revision 12 and an ordered assignments array: [Ava on Monday, Ben on Tuesday, Chao on Wednesday]. The user asks to change Ben’s Tuesday location, not to reorder the roster. The agent initially sees Ben at /assignments/1. How should it prepare an update if another planner may insert a new assignment during the same period?

The unsafe solution is to issue an unconditional replace at /assignments/1/location. If a new Monday assignment is inserted before Ava, Ben moves to index two while index one refers to Ava. The field path remains syntactically valid but names the wrong person. The safe plan identifies Ben by a stable assignment ID, obtains the latest revision, and uses an appropriate version guard and an identity test for the resolved array position before replacing the location.

Suppose a guard requires revision 12, but the server is now at revision 13. The correct result is a refused stale update, not a forced replacement. Fetch revision 13, locate Ben’s assignment again and inspect whether its Tuesday location was already changed. If the user still authorises the update and Ben remains assigned Tuesday, construct a fresh operation sequence with the new expected revision. If Ben was moved to Thursday, the original request is ambiguous and may need user review.

For a numeric check, imagine the rota permits at most three people at Location East on Tuesday. Before the change, two people are assigned there; changing Ben to East would produce three, so the cap is not exceeded. If another worker has already assigned one more person there, the same change would produce four, exceeding the cap by one. The JSON Patch protocol cannot decide that policy. The server must check the current Tuesday location count within an appropriate transaction.

The transfer answer is not “always use test” in isolation. It is to bind the operation to the correct resource, immutable subject identity, current revision and business invariant, then read back the resulting rota. Those are the aspects of safe mutation that survive when the domain changes from stock counts to staff schedules.

What successful standards conformance still cannot prove

RFC 6902 and RFC 6901 specify interoperable ways to address and change a JSON document. RFC 5789 specifies HTTP PATCH behaviour. None of them certifies that the user’s request was wise, that an item is the correct real-world object, that a quantity agrees with a warehouse sensor, or that a server’s permissions are properly configured. Good standards remove ambiguity about the representation while leaving substantive responsibility with the application.

Atomic application is valuable but scoped. A saved patch can cause separate workflows with their own delay or failure semantics. A single resource’s ETag does not lock the entire distributed business process. A successful test condition checks a value at one moment of the patch transaction; it does not prove that the value will remain unchanged forever.

The examples here assume JSON documents and a service that implements the cited standard. An API may implement partial updates with its own field masks, custom JSON paths or a proprietary change format. It is not safe to guess that a familiar verb implies RFC 6902 support. Read the endpoint contract and confirm the actual supported media type.

The strongest practical control is a verified chain: trusted request, scoped identity, exact resource version, validated patch, atomic server commit, independent saved-state readback and an honest report that stops at the observed boundary. The chain is more useful than a model’s confident statement that it knows how JSON works.

Frequently asked questions

What is JSON Patch? It is an RFC 6902 format containing an ordered array of operations for changing an existing JSON document. It is not just an arbitrary JSON object of fields to update.

Is JSON Patch the same as JSON Merge Patch? No. RFC 7396 defines a different object-based format with special null-removal behaviour and different array semantics.

Does add overwrite an existing object key? Under RFC 6902 it can replace an existing object member’s value. Do not interpret “add” as proof that a field was absent.

Is an array index a permanent identifier? No. Insertions and deletions shift indexes. Use version guards and identity tests where applicable, and prefer stable application identifiers.

How does /a~1b differ from /a/b? The former names one key “a/b” at the root. The latter traverses the key “a”, then its child “b”.

What does the test operation do? It compares the target’s current JSON value with an expected value. It changes nothing and fails if the condition does not hold.

Do I still need If-Match when a patch contains test? They check different scopes. An ETag-based condition can guard the whole resource representation while a test can guard a specific path or identity.

Can a failed HTTP PATCH leave half the document updated? A conforming PATCH server must apply directly affected resource changes atomically. Broader asynchronous effects remain subject to the application’s workflow guarantees.

May the agent retry a timed-out append immediately? No. First reconcile the authoritative resource to learn whether the original append already succeeded.

Does a successful response prove the physical-world action happened? No. It establishes only what the API actually committed and returned. Verify any downstream or physical outcome separately when the user needs it.

Where to go next and what to verify in primary sources

An API engineer can start with a small test matrix: each of the six operations; object and array targets; root and empty-key pointers; escaped slash and tilde tokens; failure on missing paths; failed test; stale ETag; and a lost-response retry. Assert unchanged state after rejected atomic patches and log the precise failure code without leaking protected values.

A coding-agent developer should make the patch generator produce an explicitly typed operation list rather than free-form instructions. A separate gate then validates paths, roles, supported operations, value constraints and expected resource version. The agent reads back and explains the result. For adjacent problems see structured output validation and concurrent document editing.

A student can rehearse the invented inventory calculation with a JSON array. Apply add and replace to a copy, write the before and after ordered IDs, compute the $22 value change and then try deliberately shifting the array before the patch. If a test fails, explain the mismatch rather than treating it as the tool “being fussy”.

Normative references: RFC 6902 JSON Patch, RFC 6901 JSON Pointer, RFC 5789 HTTP PATCH and RFC 7396 JSON Merge Patch. These are real sources with exact URLs, not imagined citations. Their scope is the protocol; an endpoint’s application policy must be learned from that endpoint’s own documentation.

Continue into the broader How Super Intelligence Works library or the education-to-life learning framework. No network patch, inventory system or staff roster was actually changed in the fictional examples.

Discover more from eduKate Singapore

Subscribe now to keep reading and get access to the full archive.

Continue reading