Overview

Jackson module that adds support for serializing and deserializing Google's Protocol Buffers to and from JSON.

Compatibility

The original version line supports jackson versions up to 2.18. Jackson 2.20+ introduces some breaking changes, which are supported in the 0.10.x line. For jackson3, use 1.x (and the jackson3-datatype-protobuf artifactId).

jackson-datatype-protobuf	jackson-databind
0.9.x	2.18
0.10.x	2.21
1.x	3.x

Usage

Maven dependency

To use module on Maven-based projects, use following dependency:

<dependency>
  <groupId>com.hubspot.jackson</groupId>
  <artifactId>jackson3-datatype-protobuf</artifactId>
  <version><!-- latest --></version>
</dependency>

Registering module

Registration is done as follows:

JsonMapper.builder().addModule(new ProtobufModule());

or to customize behavior:

ProtobufJacksonConfig config = // create config
JsonMapper.builder().addModule(new ProtobufModule(config));

after which functionality is available for all normal Jackson operations.

Interop with Protobuf 3 Canonical JSON Representation

Protobuf 3 specifies a canonical JSON representation (available here). This library conforms to that representation with a few exceptions:

• unsigned numbers (uint32, fixed32, uint64, fixed64) can be improperly serialized as negative numbers. This can be overridden by enabling ProtobufJacksonConfig#properUnsignedNumberSerialization
• int64, fixed64, uint64 are written as JSON numbers instead of strings. This can be overridden by enabling ProtobufJacksonConfig#serializeLongsAsString
• Any objects don't have any special handling, so the value will be a base64 string, and the type URL field name is typeUrl instead of @type
• original field names are not accepted on deserialization. This can be overridden by enabling ProtobufJacksonConfig#acceptLiteralFieldnames

If you want interop with canonical serialization/deserialization, you can call ProtobufJacksonConfig#useCanonicalSerialization. This will enable all the available options to get as close to the canonical behavior as possible. The behavior of this method may change in the future as new options are added.

Gotchas

This library assumes that field names in proto files will be lowercase with underscores, as is recommended by the protobuf style guide: https://developers.google.com/protocol-buffers/docs/style#message-and-field-names

Use underscore_separated_names for field names – for example, song_name.

If your field names don't match this convention, you may need to set a PropertyNamingStrategy on your ObjectMapper for things to work as expected. For example, if your proto field names are camel case, you could configure your ObjectMapper to use PropertyNamingStrategy.LOWER_CAMEL_CASE.