How to Update Fields and Nested Values with jq

All jq tools and guides

Use .status = "paid" to replace a field with a fixed value. Use .shipping.city |= ascii_upcase to update a nested field from its current value. Both return the whole JSON document; selecting .shipping.city with a plain pipe instead would return only the city.

Save this input as input.json for both examples:

{
  "id": "order-7",
  "status": "draft",
  "shipping": {"city": "Oslo", "method": "standard"},
  "items": [
    {"sku": "A", "price": 10},
    {"sku": "B", "price": 20}
  ]
}

Run each filter in the playground, or replace FILTER in jq 'FILTER' input.json with the expression shown.

Replace a value and update a nested field

.status = "paid" | .shipping.city |= ascii_upcase

Output:

{
  "id": "order-7",
  "status": "paid",
  "shipping": {
    "city": "OSLO",
    "method": "standard"
  },
  "items": [
    {"sku": "A", "price": 10},
    {"sku": "B", "price": 20}
  ]
}

Run the field and nested-field update in the jq playground

= assigns the right-hand value; |= runs its right-hand filter on the existing city value ("Oslo"), not on the whole order. | chains these two changes, so the method, items, and ID are preserved in the returned document.

Change only matching objects in an array

To add 2 to the price of SKU A without changing SKU B or replacing the order with just its items array:

.items |= map(if .sku == "A" then .price |= . + 2 else . end)

Output from the same original input:

{
  "id": "order-7",
  "status": "draft",
  "shipping": {
    "city": "Oslo",
    "method": "standard"
  },
  "items": [
    {"sku": "A", "price": 12},
    {"sku": "B", "price": 20}
  ]
}

Run the matching-item update in the jq playground

Here the outer |= passes the current items array to map; the if inspects each item; and the inner |= passes only a matching item's numeric price to . + 2. For other SKUs, else . returns the item unchanged. This example assumes matching items have numeric prices; validate incoming data before using arithmetic on missing or non-numeric values.

These filters use core jq assignment syntax (jq 1.6+). jq emits a new result rather than editing input.json in place; redirect output to a separate file if you need to save it. For other operations, see remove keys with jq, check whether a key exists, and the jq cheatsheet. Reference: jq manual, assignment.