Some aspects of Genson can be configured via annotations used on your classes. This is nice since you have your configuration that leaves near the code that uses it.

Annotation NameUsage
JsonConverter Used on fields, methods and constructor parameters of a Pojo, to enable this specific Converter. This is useful when you don't want to use the same Converter for all instances of the same type, but only based on some contextual criteria, ie. if it is contained in some class.
JsonDateFormat Used on fields, methods and constructor parameters of a Pojo, to specify how dates should be formatted. Any pattern valid for SimpleDateFormat can be used as value. The pattern and asTimeInMillis options are exclusive, you can either ser/de this property as a long or using some pattern. If no lang is defined, the default Locale.getDefault will be used.
JsonIgnore Allows to exclude properties from serialization and deserialization. By default it excludes properties from both, but you can choose whether you some property to be serialized but not deserialized.
JsonProperty It is the opposite of JsonIgnore. This annotation allows to include properties in ser/de. By default, the property will be included in both, but you can include only in serialization or deserialization. This annotation can also be used to change the name of the property.
JsonCreator If you have multiple constructors in a Pojo, Genson might not use the one you would want. To tell Genson to use a specific Constructor or Factory Method, put @JsonCreator annotation on it. You can have at most, one item annotated with it per class.
WithBeanView Used on methods of JAX-RS services or Controller methods in Spring MVC. This will tell Genson to enable these BeanViews when serializing the resutling object from the call to the method and vice versa. The BeanView feature will change in the future.
HandleNull By default Converters serialize and deserialize method won't be called when the object is null. This is handled by Genson. If you annotate a Converter with @HandleNull, then it will be called for null values too. This is useful when you want to handle null values in some specific way.
HandleClassMetadata When class metadata serialization is enabled, annotating a Converter with HandleClassMetadata, will tell Genson to not serialize the metadata for the object it is handling.
HandleBeanView Used on Converters. Will disable the BeanView mechanism for the type handled by this Converter.

But in some cases you might not be able to modify the source code or just don’t want to, in that case you can’t use annotations.


GensonBuilder is the main class allowing to configure and create new instances of Genson. It tries to be easy to use through a fluent builder API. Most of those options are documented in the Javadoc. GensonBuilder provides several methods to register components such as Converters, Factories, etc, but it is not documented here.

Method NameDefaultDescription
setSkipNull False If true, null values will not be serialized.
setHtmlSafe False \,<,>,&,= characters will be replaced by \u0027, \u003c, \u003e, \u0026, \u003d
useClassMetadata False When true, the class of values is being serialized and then used during deserialization to know the concrete type. It is useful when you are working with polymorphic types that you want to deserialize back to the concrete implementation.
useDateFormat The default date formatting style for the default locale. By default dates are being ser. as a timestamp in milliseconds. A DateFormat to be used when converting Dates, Calendars...
useDateAsTimestamp True When enabled, will ser/de dates as long representing the time in milliseconds.
useRuntimeType False Will serialize values based on their real type and not compile type.
useConstructorWithArguments False When true, will enable deserialization to constructor with arguments.
useStrictDoubleParse False By default, it uses Genson optimizations to parse double types. There is a small accuracy loss compared to Double.parse() for very large numbers, but it is much faster. In most cases this optimization is fine, but if you need the exact same precision as Double.parse then you can enable strict double parsing.
acceptSingleValueAsList False Wrap a single value into a list when a list is expected. Useful when dealing with APIs that unwrap arrays containing a single value.
useIndentation False Enable it if you want to output nicely formatted Json.
useByteAsInt False By default byte arrays are ser/de as base64 encoded strings. When this feature is enabled, each byte will be ser/de as its numeric value.
useClassMetadataWithStaticType True If set to false, during serialization class metadata will be serialized only for types where the runtime type differs from the static one.
failOnMissingProperty False If set to true, Genson will throw a JsonBindingException when it encounters a property in the incoming json that does not match a property in the class. By default it skips this value silently.
wrapRootValues(inputKey, outputKey) Disabled Allows to wrap all the root objects in another object using outputKey during serialization and unwrap during deserialization the value under inputKey. Use this only if you need to communicate with some 3rd party library that needs this kind of json. A more flexible strategy to wrap root values is to use @XmlRootElement with JaxbBundle, see Extensions section.