How to map a JSON collection using JPA and Hibernate

Imagine having a tool that can automatically detect if you are using JPA and Hibernate properly. Hypersistence Optimizer is that tool!


The open-source hibernate-types project allows you to map Java objects or Jackson JsonNode as JPA or Hibernate entity properties, and, thanks to our awesome contributors, we have added support for storing type-safe JSON collections.

In this article, you are going to see how to achieve this goal.

Maven dependency

First of all, you need to set up the following Maven dependency in your project pom.xml configuration file:


If you’re using older versions of Hibernate, check out the hibernate-types GitHub repository for more info about the matching dependency for your current Hibernate version.

Domain Model

Let’s assume we have the following Location Java object type.

public class Location implements Serializable {

    private String country;

    private String city;

    //Getters and setters omitted for brevity

    public String toString() {
        return "Location{" +
                "country='" + country + ''' +
                ", city='" + city + ''' +

And, one Event entity:

@Entity(name = "Event")
@Table(name = "event")
public class Event extends BaseEntity {

    @Type(type = "jsonb")
    @Column(columnDefinition = "jsonb")
    private Location location;

    @Type(type = "jsonb")
    @Column(columnDefinition = "jsonb")
    private List<Location> alternativeLocations = new ArrayList<Location>();

    //Getters and setters omitted for brevity

The BaseEntity defines some basic properties (e.g. @Id, @Version) and several custom Hibernate types, among which, we are interested in the JsonBinaryType one.

    @TypeDef(name = "string-array", typeClass = StringArrayType.class),
    @TypeDef(name = "int-array", typeClass = IntArrayType.class),
    @TypeDef(name = "json", typeClass = JsonStringType.class),
    @TypeDef(name = "jsonb", typeClass = JsonBinaryType.class),
    @TypeDef(name = "jsonb-node", typeClass = JsonNodeBinaryType.class),
    @TypeDef(name = "json-node", typeClass = JsonNodeStringType.class),
public class BaseEntity {

    private Long id;

    private Integer version;

    //Getters and setters omitted for brevity

For more details about using @MappedSuperclass, check out this article.

To store both the Location object or the List<Location> in a jsonb PostgreSQL column, we just need to annotate the location property with @Type(type = "jsonb").

That’s it!

Testing time

When saving the following Event entity:

Location cluj = new Location();

Location newYork = new Location();

Location london = new Location();

Event event = new Event();
    Arrays.asList(newYork, london)


Hibernate will generate the following SQL INSERT statement:


Also, when retrieving back the Event entity, both the location and thealternativeLocations` properties are properly fetched:

Event event = entityManager.find(Event.class, eventId);


assertEquals(2, event.getAlternativeLocations().size());


Cool, right?

I'm running an online workshopk on the 14th of May about The Best Way to Fetch Data with Java Persistence and Hibernate.

If you enjoyed this article, I bet you are going to love my Book and Video Courses as well.


The hibernate-types project supports more than JSON types. You can map PostgreSQL ARRAY types or PostgreSQL-specific Enums, nullable Character, or even provide your own immutable Hibernate custom Types.

Transactions and Concurrency Control eBook

8 Comments on “How to map a JSON collection using JPA and Hibernate

  1. TelephoneNumberType is my own type similar to EmailAddressType.

    • I also have no idea what EmailAddressType is. Anyway, I could only helped you if you were using the Types provided by my hibernate-types project, which is also the subject of the article your are now commenting on.

  2. I’ve tried this, i’m currently using hibernate 5.3.9 with hibernate-types-52 2.5.0 and i’m getting ” org.postgresql.util.PSQLException: ERROR: malformed array literal: “[{“id”:”Mycah”,”name”:”Sven Goldner”}]””
    Anyone faced this before ? thanks

    • Try to replicate it and provide a fix for it via a Pull Request. I’ll review it once it’s done.

  3. Hi Vlad,
    Some questions.
    Is it possible to use @OneToMany instead of @Column for List alternativeLocations?
    Can I write HQL query for fields within the Locations? Say pull all events held in specific city?

    • The answer is no and no. Associations and entity queries are one thing while basic properties and DB-specific querying capabilities are another thing.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.