Model JSON Mapping Details

Introduction

Page Model JSON API aggregates all the model objects, contributed by each HstComponent, into an AggregatedPageModel, and it writes the AggregatedPageModel to SPAs in JSON. Every model object is embedded in the AggregatedPageModel in a well-structured way, as explained in Page Model JSON API page, and serialized together into JSON in the end. Under the hood, this JSON serialization process is done by using com.fasterxml.jackson.databind.ObjectMapper bean. For a general understanding of Jackson library, see README.md of jackson-databind module.

Page Model JSON API registers some built-in Jackson Mixin Types (JacksonMixInAnnotations) in the ObjectMapper bean for various reasons. e.g, to avoid serializing unnecessary properties such as javax.jcr.Session and javax.jcr.Node, or to customize serialization behaviors.

Regarding domain-specific model beans contributed by your HstComponent code, it serializes those beans in the standard way how Jackson ObjectMapper scans the bean classes and serialize each property of them. Therefore, you may optionally use Jackson Annotations on your bean classes or even register custom Jackson Mixin Types (JacksonMixInAnnotations) as well if you want to customize the default Jackson Serialization behaviors.

About Jackson Mixin Types (JacksonMixInAnnotations)

Jackson Mixin Types (JacksonMixInAnnotations) play a big role in the JSON serialization process of Page Model JSON API. Most HstComponents retrieve content documents, folders, or gallery images/assets through HST Content Beans. In other words, the most popular types of model objects that HstComponents need to contribute are HST Content Beans. So, it is natural for an HstComponent to contribute HST Content Beans directly through HstRequest#setModel(String, Object).

However, there are many challenges:

• HST Content Bean classes contain properties that cannot be serialized into JSON. e.g, HippoBean#getNode(), HippoBean#getValueProvider(), ObjectConverterAware#getObjectConverter(), etc. Those properties should be marked not to be serialized to JSON somehow.
• Some HST Content Beans need to include some virtual properties additionally at runtime. e.g, _links field in document content bean or menu item bean.
• Some HST Content Beans need to be serialized into a simpler JSON form, instead of reflecting the whole object structure literally.
• If we want to solve the above problems without Jackson Mixin Types (JacksonMixInAnnotations), it will end up breaking compatibilities and HST Content Beans library might be too tightly-coupled with Jacksion library. 

Jackson Mixin Types (JacksonMixInAnnotations) provide a good solution to these challenges. Page Model JSON API registers some built-in Jackson Mixin Types (JacksonMixInAnnotations) in the ObjectMapper bean to exclude some non-serializable properties, include some virtual properties or change the default bean serialization behavior.

Serializing HST Content Beans to JSON

Some property types are marked not to serialize into JSON in Page Model JSON API for safety. Also, the built-in HST Content Bean classes and other HST Bean classes are associated with built-in Jackson Mixin Types (JacksonMixInAnnotations) by default.

Types Always Ignored In JSON Serialization

The following types are never serialized into JSON in Page Model JSON API.

• javax.jcr.Session
• javax.jcr.Node
• org.hippoecm.hst.provider.ValueProvider
• org.hippoecm.hst.content.beans.manager.ObjectConverter

Built-in Mixin Type Mappings for HST Content Beans

The following built-in HST Content Bean classes are associated with their Jackson Mixin Types (JacksonMixInAnnotations) by default to customize the serialization behaviors.

HST Content Bean Type	Mixin Type
o.h.h.c.b.s.HippoGalleryImageBean	o.h.h.p.v.c.b.j.HippoGalleryImageBeanMixin
o.h.h.c.b.s.HippoGalleryImageSetBean	o.h.h.p.v.c.b.j.HippoGalleryImageSetBeanMixin
o.h.h.c.b.s.HippoHtmlBean	o.h.h.p.v.c.b.j.HippoHtmlBeanMixin
o.h.h.c.b.s.HippoRequestBean	o.h.h.p.v.c.b.j.HippoRequestBeanMixin
o.h.h.c.b.s.HippoMirrorBean	o.h.h.p.v.c.b.j.HippoMirrorBeanMixin
o.h.h.c.b.s.HippoFolderBean	o.h.h.p.v.c.b.j.HippoFolderBeanMixin
o.h.h.c.b.s.HippoDocumentBean	o.h.h.p.v.c.b.j.HippoDocumentBeanMixin
o.h.h.c.b.s.HippoBean	o.h.h.p.v.c.b.j.HippoBeanMixin

Serializing Other HST Beans to JSON

The following built-in HST Bean classes are associated with their Jackson Mixin Types (JacksonMixInAnnotations) by default to customize the serialization behaviors, too.

HST Bean Type	Mixin Type	Notes
o.h.h.c.component.HstURL	o.h.h.p.v.c.b.j.HstURLMixin
o.h.h.c.linking.HstLink	o.h.h.p.v.c.b.j.HstLinkMixin
o.h.h.c.sitemenu.HstSiteMenuItem	o.h.h.p.v.c.b.j.HstSiteMenuItemMixin
o.h.h.c.sitemenu.HstSiteMenu	o.h.h.p.v.c.b.j.HstSiteMenuMixin
o.h.h.c.sitemenu.EditableMenuItem	o.h.h.p.v.c.b.j.EditableMenuItemMixin
o.h.h.c.sitemenu.EditableMenu	o.h.h.p.v.c.b.j.EditableMenuMixin
o.h.h.c.sitemenu.CommonMenuItem	o.h.h.p.v.c.b.j.CommonMenuItemMixin
o.h.h.c.sitemenu.CommonMenu	o.h.h.p.v.c.b.j.CommonMenuMixin

Serializing Domain-Specific Beans to JSON

By default, your own domain-specific beans or 3rd party beans you want to contribute in HstComponent code, will be serialized using the default Jacksion Bean Serialization mechanism.

If you want to customize the default bean serialization, you might want to consider adding Jackson Annotations to your custom classes. In most cases, this will be good enough.

In more advanced cases or if you need to customize the serialization of 3rd party beans, you can also consider injecting custom Jackson Mixin Types (JacksonMixInAnnotations) for the beans. See the Adding Custom Jackson Mixin Types section in Customization page for detail.

Summary

In JSON serialization process of Page Model JSON API, it uses com.fasterxml.jackson.databind.ObjectMapper bean internally. It registers some built-in Jackson Mixin Types (JacksonMixInAnnotations) in the ObjectMapper bean to customize the default bean serialization.

For domain-specific model beans or 3rd party beans, you may optionally use Jackson Annotations on the bean classes or even register custom Jackson Mixin Types (JacksonMixInAnnotations) for more advanced cases.