docs/PATCH_IR.md

Payo Patch IR

Payo updates an existing structured record by emitting a minimal JSON array of operations. It does not regenerate the full state and does not use RFC 6902.

Shape

A patch is a JSON array. Each operation targets a JSON Pointer path listed in the supplied Payo Schema View.

[{"op":"set","path":"/status","value":"confirmed"}]

Supported operations:

• set — create or replace a value at a schema-approved path whose parent object already exists.
• delete — remove an existing field when the schema allows deletion.
• append — append one value to an existing append-only array.
• [] — a genuine no-op: no represented state change is justified.

The model should emit the smallest patch that produces the justified current state. An invalid operation invalidates the whole patch.

Null, deletion, and no-op

These are not interchangeable.

Set an existing field to JSON null:

[{"op":"set","path":"/assignee","value":null}]

Remove the field:

[{"op":"delete","path":"/assignee"}]

Make no change:

[]

A null value means the field remains present with a null value. Delete means the field is absent. An empty array means that no state change is justified.

Operations

set

Set creates or replaces the value at a schema-approved path. The parent object must already exist. Payo v0 does not create missing intermediate objects.

[{"op":"set","path":"/status","value":"confirmed"}]

The value must satisfy the path's type and any deterministic constraints such as enum, const, or numeric bounds.

delete

Delete removes an existing field. The field must exist, and the schema must allow deletion. Required fields are not deletable.

[{"op":"delete","path":"/assignee"}]

append

Append adds one item to an existing append-only array. It does not replace or edit existing array items.

[{"op":"append","path":"/events","value":{"type":"checked_in","minute":64}}]

Array paths support append only; indexed mutation is outside this IR.

Paths and application

Paths use JSON Pointer escaping: a literal tilde is written as ~0 and a literal slash in a key as ~1. Operations are applied in array order. The target path must exist in the supplied schema and the current state must satisfy the patch operation's preconditions.

A patch is not silently repaired. Do not substitute a nearby path, coerce a value, drop a bad operation, or replace an invalid patch with [].