How to map JSON collections using JPA and Hibernate

(Last Updated On: February 2, 2018)


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?

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.

Subscribe to our Newsletter

* indicates required
10 000 readers have found this blog worth following!

If you subscribe to my newsletter, you'll get:
  • A free sample of my Video Course about running Integration tests at warp-speed using Docker and tmpfs
  • 3 chapters from my book, High-Performance Java Persistence, 
  • a 10% discount coupon for my book. 
Get the most out of your persistence layer!


12 thoughts on “How to map JSON collections using JPA and Hibernate

    1. It was static because it was nested in the JUnit test class. As for being final, it depends on your use case. Most often, I guess it could be also final as it’s unlikely that you will have to extend it.

  1. Vlad, can you improve `org.hibernate.usertype.DynamicParameterizedType.ParameterType` to add a new method like `java.lang.reflect.Field.getGenericType()` ?
    We can use `objectMapper.getTypeFactory().constructType(type)` to deserialize collections from json.

      1. Why would you want that? I still don’t understand your use case. You can save both Java objects and collections as JSON using this framework. Is there a use case you have that does not work with the current JSON type implementation?

      2. If there is genericReturnClass, jackson can use it infer generic types, and no need TypeReferenceFactory, currently your solution need declare List twice, one for entity and the other for TypeReferenceFactory, It’s superfluous and error prone.

      3. It’s unlikely that anyone will change Hibernate core just to add genericReturnClass so that you avoid this duplication in this example which doe snot even belong to thee official Hibernate framework. You say it’s error prone, but I think that, if you have integration tests the entire data access layer, how could that fail in any way?

      4. It’s just a viable suggestion to make hibernate-types-52 better, and genericReturnClass is necessary in modern java world.

      5. As I already mentioned, if you think it can be improved without requiring changing Hibernate ORM, then send me Pull Request with your proposed changes.

      1. Thanks. I’m going to review it after I manage to finish the material for the firsts part of my video course.

Leave a Reply

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