JarCastingJackson 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.