---
title: "The old release deletes JSON fields it does not know | Proofline"
description: "When a new release adds a field to a stored JSON document, the old release reads the document into a model without that field and saves the whole model back."
url: https://proofline.sh/learn/json-unknown-fields-dropped-old-release/
---

[Learning center](/learn/)

# The old release deletes JSON fields it does not know

When a new release adds a field to a stored JSON document, the old release reads the document into a model without that field and saves the whole model back. The new field disappears. In our lab, a gift note written by the new release was gone after the old release added an item to the cart. Have the old release change only the keys it owns, and know that || merges only the top level.

Schema conflicts The Proofline team November 22, 2026 2 min read

## The lost field

Carts live in a `jsonb` column. Release `2026.11.4` adds `gift_note`. Release `2026.11.3` models a cart with the fields it knows. We ran this on PostgreSQL 16.15 with Python 3.11 and psycopg 3.2:

```
@dataclass
class Cart:                                   # 2026.11.3
    items: list
    coupon: str | None = None

    @classmethod
    def from_doc(cls, d):
        return cls(items=d["items"], coupon=d.get("coupon"))

doc = db.execute("SELECT doc FROM carts WHERE id = 1").fetchone()[0]
# {'items': ['sku-1'], 'coupon': None, 'gift_note': 'Happy birthday, Lea'}
cart = Cart.from_doc(doc)
cart.items.append("sku-2")
db.execute("UPDATE carts SET doc = %s WHERE id = 1", (Jsonb(asdict(cart)),))
```

```
{'items': ['sku-1', 'sku-2'], 'coupon': None}
```

The customer's gift note is gone, and the new release has no way to know it ever existed. Many JSON libraries behave like this by default: Pydantic models and Go's `encoding/json` ignore unknown fields when reading, and a struct has nowhere to keep them. The new field survives only until the old release next saves that document.

## Change only the keys you own

`jsonb_set` changes one path and leaves the rest of the document alone:

```
UPDATE carts
SET doc = jsonb_set(doc, '{items}', (doc->'items') || to_jsonb('sku-2'::text))
WHERE id = 1;
-- {"items": ["sku-1", "sku-2"], "coupon": null, "gift_note": "Happy birthday, Lea"}
```

When the old release has to send the document it built, merge it into the stored one with `||` instead of replacing it:

```
UPDATE carts SET doc = doc || $1 WHERE id = 1;
-- {"items": ["sku-1", "sku-2"], "coupon": null, "gift_note": "Happy birthday, Lea"}
```

The merge keeps keys the old release did not send. It works one level deep only, as the [JSON functions table](https://www.postgresql.org/docs/16/functions-json.html) notes for `jsonb || jsonb`. A new field inside a nested object is still lost:

```
SELECT '{"items":["sku-1"],"shipping":{"city":"Berlin","door_code":"4711"}}'::jsonb
    || '{"items":["sku-1","sku-2"],"shipping":{"city":"Berlin"}}'::jsonb;
-- {"items": ["sku-1", "sku-2"], "shipping": {"city": "Berlin"}}
```

The door code is gone. Add new fields at the top level while an old release still writes the document, or make the old release preserve unknown fields in its model, which some libraries support with a catch-all field.

## Release order

The release that preserves unknown fields, or writes only its own keys, has to ship before the release that adds the field, and has to be the rollback target while the new field is in use. A rollback past it deletes the field again on the next save.

## The compatibility test

Write a document with the new release, including a field inside a nested object, then run each of the previous release's save paths on it. Pass when every field the new release wrote is still present. Versioning whole documents is covered in [migrate JSON documents on read, and finish with a backfill](/learn/lazy-migration-on-read-version-field/).

## One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. [Eligibility and fair-use terms](/free-code-review/).

[Start free with GitHub](https://proofline.sh/orgs/plan?offer=free_month)

## Related reading

-   ### [Migrate JSON documents on read, and finish with a backfill](/learn/lazy-migration-on-read-version-field/)
    
    Breaking migrations The Proofline team November 22, 2026 2 min read
    
-   ### [Moving data while two application releases share one database](/learn/data-migration-across-service-versions/)
    
    Breaking migrations The Proofline team November 22, 2026 7 min read
