How do you map a JSON document column — for example a PostgreSQL jsonb column — onto an entity attribute with Hibernate, and what must you watch out for once it is mapped?

## The mapping options **Hibernate 6 — built in.** The JDBC type system was reworked, and JSON is a first-class type code: ```java @JdbcTypeCode(SqlTypes.JSON) @Column(columnDefinition = "jsonb") private ShippingPreferences preferences; ``` The attribute can be a POJO, a `Map`, or a collection. Hibernate serializes it with an available mapper — Jackson if it is on the classpath — and binds it in the form the dialect expects. This is the mapping to reach for on any current version. **Hibernate 5 — bring your own.** Options were a hand-written `UserType` implementing binding and extraction against the driver's JSON support, a community type library, or the lowest-tech approach: an `AttributeConverter<Payload, String>` that serializes to text. The converter route is worth understanding because it still appears in codebases and because it exposes the underlying binding issue. If the column is declared `jsonb` and the driver binds the parameter as `varchar`, PostgreSQL rejects the statement — "column is of type jsonb but expression is of type character varying". The two standard workarounds are to declare the column as `json`/`jsonb` and tell the driver to send string parameters untyped, or to store the document in a plain `text` column and give up the database's JSON operators. Both are compromises; the native type-code mapping is cleaner. ## Dirty checking and mutability This is the trap that produces silent data loss. Hibernate detects changes by comparing current state against the snapshot taken at load. For a JSON attribute, whether an in-place mutation is noticed depends on how the type compares values — by serializing and comparing the output, or by `equals` on the deserialized object. Mutating a nested field of a `Map` or POJO in place may compare equal and never be written. Two defences, both worth stating in an interview: 1. **Treat the payload as an immutable value.** Build a new instance and assign it to the attribute: `entity.setPreferences(old.withCurrency("EUR"))`. A reference change is always noticed. 2. **Give the payload a correct `equals`/`hashCode` over its full contents**, so comparison is meaningful whichever route is taken. Avoid handing out the live object for callers to mutate. ## Writes are whole-document There is no partial update through the mapping. Change one key and the entire document is serialized and written. For a small preferences blob that is irrelevant; for a megabyte document updated frequently by concurrent requests it is both a bandwidth cost and a lost-update hazard — two transactions each read the document, each change a different key, and the second write erases the first. Optimistic version checking on the entity is what turns that silent loss into a detectable conflict, and it is the reason a hot JSON column and a version column belong together. Genuinely partial updates require vendor JSON functions in a native statement, outside the mapping. ## Querying and indexing JPQL has no path syntax into a JSON document — `where p.preferences.currency = :c` does not compile, because the provider only knows the attribute, not its interior. Your options are: - a **native query** using the database's JSON operators; - **registering a database function** with Hibernate so it can be called from HQL, which keeps the query in the ORM but is vendor-specific; - **promoting the field to a real column** when it is queried often — which is usually the right answer. Indexing follows the same logic: filtering inside a document requires an index the database can use for those operators (a GIN index on jsonb, or an expression index on an extracted field). Neither is created by the mapping; both belong in migrations. Without one, every filter is a full scan that deserializes each row. ## What you give up A JSON column is schemaless from the database's point of view. No `NOT NULL` on an interior field, no foreign key, no check constraint, no type enforcement — every guarantee moves into application code, and every historical version of the document must remain readable by the current deserializer. That last point is the one teams underestimate: a renamed field in the POJO silently reads as null for every old row unless you handle the migration, and there is no schema tool that will tell you. ## When it is the right call Good fits: genuinely open-ended attributes that no query filters on, per-tenant or per-integration extension data, captured third-party payloads, event or audit detail. Bad fits: anything you filter, sort, join or aggregate on regularly; anything with referential meaning; anything a report writer will need to understand. The honest framing in a design discussion is that a JSON column buys schema flexibility by spending queryability and database-enforced integrity — so use it where the flexibility is real and the querying is not.