Path targeting

Every patch operation requires a path that specifies which part of the record to modify. Paths use forward-slash notation to navigate the record hierarchy.

Common path patterns

Entire product: /product-123
Product's fields container: /product-123/fields
Single product field: /product-123/fields/title
Product's variants container: /product-123/variants
Single variant: /product-123/variants/variant-ABC
Variant's fields container: /product-123/variants/variant-ABC/fields
Single variant field: /product-123/variants/variant-ABC/fields/color

Path escaping

According to the JSON patch (RFC 6901) specification, you must escape special characters in path segments:

Tilde character (~): escape as ~0
Forward slash character (/): escape as ~1

For example, a product record ID containing a forward slash (product-123/v2) must appear in the path as:

"/product-123~1v2"

A product record ID containing a tilde (prod~test) must appear as:

"/prod~0test"

Apply these escapes whenever specifying paths that include ~ or / in identifiers.

Remove operation at container level

Remove operation at the container level doesn't remove the container, but empties the contents of the container. It's equivalent to an add or upsert operation at the container and setting the value to an empty object.

Path targeting examples

The following examples demonstrate operations at each level of the record hierarchy.

Product record

{
  "op": "add",
  "path": "/product-123",
  "value": {
    "fields": {
      "title": "High-End Laptop",
      "price": 1299
    },
    "variants": {
      "var-001": {
        "fields": {
          "sku": "LAP-001",
          "color": "Silver",
          "inventory": 25
        }
      }
    }
  }
}

Creates a new product record or completely replaces it if it exists. Add product completely replaces all the nested variants if any exist with the new set of variants.

Product's fields container

{
  "op": "upsert",
  "path": "/product-123/fields",
  "value": {
    "brand": "TechPro",
    "warranty": "2 years"
  }
}

Merges new fields into the existing fields container. If the product doesn't exist, upsert creates it with these fields.

Single product field

{
  "op": "remove",
  "path": "/product-123/fields/title"
}

Removes the title field if it exists. No error occurs if the field doesn't exist.

Product's variants container

{
  "op": "add",
  "path": "/product-123/variants",
  "value": {
    "var-002": {
      "fields": {
        "sku": "LAP-002",
        "color": "Black",
        "inventory": 10
      }
    },
    "var-003": {
      "fields": {
        "sku": "LAP-003",
        "color": "Rose Gold",
        "inventory": 8
      }
    }
  }
}

Replaces the entire variants container with exactly var-002 and var-003. Any existing variants not listed are removed.

Single variant

{
  "op": "upsert",
  "path": "/product-123/variants/variant-ABC",
  "value": {
    "fields": {
      "sku": "ABC-111",
      "color": "Green",
      "inventory": 20
    }
  }
}

Creates variant-ABC if it doesn't exist. Otherwise, merges the fields container with existing variant fields.

Variant's fields container

{
  "op": "remove",
  "path": "/product-123/variants/variant-ABC/fields"
}

Removes all fields in variant-ABC, leaving an empty fields container. The variant itself still exists.

Single variant field

{
  "op": "upsert",
  "path": "/product-123/variants/variant-ABC/fields/color",
  "value": "Dark Green"
}

Updates the color field to "Dark Green". If the product or variant doesn't exist, upsert creates them as needed.

Multi-operation example

A single patch can combine multiple operations at different levels:

[
  {
    "op": "remove",
    "path": "/product-789"
  },
  {
    "op": "upsert",
    "path": "/product-123/variants/var-001/fields/inventory",
    "value": 47
  },
  {
    "op": "add",
    "path": "/product-111",
    "value": {
      "fields": {
        "title": "Basic T-Shirt",
        "price": 9.99
      },
      "variants": {
        "white-s": {
          "fields": {
            "color": "White",
            "size": "S",
            "inventory": 100
          }
        }
      }
    }
  },
  {
    "op": "remove",
    "path": "/product-123/fields/discontinued"
  }
]

This patch:

Removes product-789 entirely.
Updates inventory for one variant under product-123.
Adds a new product with one variant.
Removes a specific field from product-123.