Jackson Module Unknown Property

Unknown Property is a Jackson extension module that adds standardized logging of unknown properties.

Consumers of RESTful APIs should be resilient to changes, most importantly they shouldn't break when a server sends a new, unknown property. The goal of this module is to let clients know that a new property exists, so they can decide to either ignore it explicitly or to use it, in case it proves to be useful.

Features

• log new, unknown properties in JSON messages as soon as they appear
• increases awareness of API changes on consumer side

Dependencies

• Java 8
• Any build tool using Maven Central, or direct download
• Jackson
• SLF4J

Installation

Add the following dependency to your project:

<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>jackson-module-unknown-property</artifactId>
    <version>${jackson-module-unknown-property.version}</version>
</dependency>

Configuration

Register the module with your ObjectMapper:

ObjectMapper mapper = new ObjectMapper()
    .registerModule(new UnknownPropertyModule());

Alternatively, you can use the SPI capabilities:

ObjectMapper mapper = new ObjectMapper()
    .findAndRegisterModules();

Typically you will disable the FAIL_ON_UNKNOWN_PROPERTIES feature, as it contradicts the whole idea of being a resilient API client:

ObjectMapper mapper = new ObjectMapper()
    .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
    .registerModule(new UnknownPropertyModule());

Beware this module is implemented as a DeserializationProblemHandler. If you register multiple handlers they are running in reverse order, i.e. the handler that is registered last will run first.

Customization

The logging category defaults to org.zalando.jackson.module.unknownproperty.UnknownPropertyModule but can be customized by passing a logger:

ObjectMapper mapper = new ObjectMapper()
    .registerModule(new UnknownPropertyModule(LoggerFactory.getLogger("unknown-property")));

The logging format defaults to Unknown property in {}: {} but can also be customized:

ObjectMapper mapper = new ObjectMapper()
    .registerModule(new UnknownPropertyModule("Well this is odd... somebody changed {} and added '{}'"));

Please note that the first parameter is the type and the second one is the property name.

The log level defaults to TRACE but can also be customized:

ObjectMapper mapper = new ObjectMapper()
    .registerModule(new UnknownPropertyModule(Level.INFO));

Usage

After configuring the module when for example the following JSON ...

{
  "name": "Alice",
  "age": 31
}

... is deserialized into the following class ...

public class Person {
    private String name;
    ...
}

... then, depending on the underlying logging framework, the entry in the logfile may look like this:

2016-03-24T09:33:13 [main] TRACE UnknownPropertyModule - Unknown property in class Person: age

To suppress the warning you just explicitly ignore the property:

@JsonIgnoreProperties("age")
public class Person {
    ...
}

Getting help

If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker.

Getting involved

To contribute, simply make a pull request and add a brief description (1-2 sentences) of your addition or change. For more details check the contribution guidelines.