JSON Merge Patch

WHEN TO USE: Apply simple partial-object updates using RFC 7396. Object members recursively merge, null members delete, arrays replace wholesale, and non-object patches replace the entire target. The target is never mutated. Maximum 100,000 serialized characters, 1,000 entries per collection, depth 32; reserved prototype-related keys are rejected.

structured · Operation ID: json-merge-patch

Choose this operation when

Merge partial objects, with null deleting members and arrays replacing wholesale.

Outside this profile

Element-wise array merging or preserving explicit null object members.

Exact release references

Static JSON contract · Markdown reference · Fixed example response

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "target": {
      "$ref": "#/$defs/__schema0"
    },
    "patch": {
      "$ref": "#/$defs/__schema0"
    }
  },
  "required": [
    "target",
    "patch"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

Complete output-envelope schema

{
  "type": "object",
  "required": [
    "operation",
    "version",
    "result",
    "provenance"
  ],
  "properties": {
    "operation": {
      "const": "json-merge-patch",
      "type": "string"
    },
    "version": {
      "const": "0.29.0",
      "type": "string"
    },
    "result": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "document": {
          "$ref": "#/properties/result/$defs/__schema0"
        }
      },
      "required": [
        "document"
      ],
      "additionalProperties": false,
      "$defs": {
        "__schema0": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/properties/result/$defs/__schema0"
              }
            },
            {
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {
                "$ref": "#/properties/result/$defs/__schema0"
              }
            }
          ]
        }
      }
    },
    "provenance": {
      "type": "object",
      "required": [
        "inputSha256",
        "outputSha256",
        "deterministic",
        "externalRequests"
      ],
      "properties": {
        "inputSha256": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "outputSha256": {
          "type": "string",
          "pattern": "^[a-f0-9]{64}$"
        },
        "deterministic": {
          "const": true
        },
        "externalRequests": {
          "const": 0
        }
      }
    }
  },
  "additionalProperties": false
}

Fixed example

One accepted fixed example, not a custom-input trial. No operation runs when this static page is requested.

Example input

{
  "target": {
    "name": "Ada",
    "preferences": {
      "theme": "light",
      "language": "en"
    },
    "obsolete": true
  },
  "patch": {
    "preferences": {
      "theme": "dark"
    },
    "obsolete": null
  }
}

Example response

{
  "operation": "json-merge-patch",
  "version": "0.29.0",
  "result": {
    "document": {
      "name": "Ada",
      "preferences": {
        "theme": "dark",
        "language": "en"
      }
    }
  },
  "provenance": {
    "inputSha256": "5e708cad77d8f9ada135e40e77b8b6a13770eb705090add5c6ea4979c50624da",
    "outputSha256": "7b2fc4fbc15ed1600fdd36aa9e1082189347d9206aca39b296dc0835527e1b45",
    "deterministic": true,
    "externalRequests": 0
  }
}

Bounds and precision

JavaScript IEEE-754 numbers; use strings for large integer IDs/exact decimals where the schema accepts strings. No lossless numeric parsing.

{
  "global": {
    "requestBytes": 131072,
    "responseBytes": 524288,
    "jsonDepth": 32,
    "jsonNodes": 20000,
    "requestsPerMinute": 60,
    "paidAttemptsPerMinute": 20,
    "idempotencyHours": 24
  },
  "operation": {
    "requestBytes": 131072,
    "responseBytes": 524288,
    "jsonDepth": 32
  }
}

Complete schemas, descriptions and cross-field validation may impose additional limits.

Proposed price and protocol definitions

{
  "unit": "one successful operation call",
  "proposedNominalUsd": "0.005",
  "sixDecimalTokenBaseUnits": "5000",
  "subscription": false,
  "includesPayerWalletOrNetworkFees": false,
  "liveQuoteVerified": false,
  "condition": "Actual SDK challenge is authoritative only within the caller's explicit authorization; configured six-decimal token peg is an operator assertion, not a conversion guarantee."
}

Protocol definitions: x402, mpp. MPP uses Tempo charge. Paid MCP execution is unsupported. All runtime readiness is not evaluated in this build.

API path templates, not endpoints on this documentation host

{
  "x402": "/v1/x402/json-merge-patch",
  "mpp": "/v1/mpp/json-merge-patch"
}

Required headers

{
  "Content-Type": "application/json",
  "Idempotency-Key": "random 16–128 character operation identifier"
}

Actual SDK challenge amount, asset, network, recipient and wallet costs must pass independent authorization. Preserve identical key, body, protocol and credential on retries; on PAYMENT_UNCERTAIN stop and reconcile.

Execution profile and provider conditions

{
  "deterministic": true,
  "externalRequests": 0,
  "maxExternalRequests": 0,
  "resultSnapshotPersisted": false,
  "fixedExampleIsIllustrativeSnapshot": false,
  "requiresPayment": true,
  "supportsMcpExecution": false
}

Deterministic supplied-input operation with no external requests or stored request/result bodies. Payment infrastructure retains payment metadata and hashes.

Failure handling

HTTP 400: Malformed JSON, missing/invalid idempotency key, or payment identifier mismatch Correct the request before payment
HTTP 402: Payment challenge or rejected payment Use official protocol SDK; inspect payment outcome before another payment
HTTP 409: Idempotency conflict, duplicate proof, or PAYMENT_UNCERTAIN Keep original key, body, and proof; reconcile uncertainty with operator; never blindly repay
HTTP 413: Input or generated output too large Reduce input; no payment attempted for validation failure
HTTP 415: Unsupported media type or compression Send uncompressed application/json
HTTP 422: Schema or service-specific semantic validation failure Correct input using returned error code; no payment attempted
HTTP 429: Request/payment-attempt rate exceeded Wait for rate limit window; preserve existing payment identity
HTTP 503: Payment configuration/provider/state unavailable, or live DNS preparation failed before settlement Check readiness; DNS preparation failures may retry the identical key/body/credential only; uncertainty requires reconciliation

Declared requirements

Before any paid call, refresh the live operation contract and POST the complete bounded budgeted plan to the separate API's /preflight. Unknown requirements block selection; compatible preflight is not permission to spend.

Related contracts

json-patch