Jackson How-To: Ignoring Unknown Properties

(aka "How to ignore unknown properties")

When binding JSON data into Java objects, all JSON properties need to map to properties of Java object to bind to. If an unknown property is encountered, an exception is thrown. But sometimes it is necessary to ignore unknown JSON properties when reading content to bind to existing Java objects: either you do not control incoming data (or Java objects), don't know all properties there could be, or you are only interested in subset of properties anyway.

There are multiple ways you can handle such situations.

1. Add "Any setter" to handle any unknown properties

It is possible to define a 2-argument method to be called whenever otherwise unknown property is encountered, like so:

  // note: name does not matter; never auto-detected, need to annotate
  // (also note that formal argument type #1 must be "String"; second one is usually
   /  "Object", but can be something else -- as long as JSON can be bound to that type)
  public void handleUnknown(String key, Object value) {
    // do something: put to a Map; log a warning, whatever

If so, this method will be called once per unknown property. This is useful if you intend to do something for properties of various names, and do not want to add separate setter methods. A downside is that you have to use common value type (often just Object.class).

Note that you can only have one such method per class; adding annotation for two methods will result in exception when constructing deserializer.

This annotation has been supported since version 1.0 (although earlier javadocs claimed it was not supported)

2. Register Problem Handler

It is also possible to register a DeserializationProblemHandler (by calling ObjectMapper.addHandler()). When added, handler's handleUnknownProperty method will be called once for each unknown property.

This method is most useful when you just want to log a warning for unknown properties: that is, when these properties are probably problematic, but should not cause a hard data binding failure. Rather you want to be informed so that input data can be corrected later on.

3. Globally disable checking

It is also possible to just get rid of exceptions for any unknown properties. To do this, just disable DeserializationConfig.Feature.FAIL_ON_UNKNOWN_PROPERTIES (see Deserialization Features for details):

    objectMapper.configure(DeserializationConfig.Feature.FAIL_ON_UNKNOWN_PROPERTIES, false);

This is a good approach if the default behavior should be just to ignore any unknown properties. It will make handling similar to other "laissez-faire" frameworks, such as JAXB.

This feature is available with version 1.2 and later.

4. Per-class declaration of ignoral of unknown properties

Version 1.4 adds new annotation, @JsonIgnoreProperties which can be used to annotate classes, to:

This gives you more control over which properties to ignore and for which types, especially when used with Mix-in annotations.

Back to Documentation page


JacksonHowToIgnoreUnknown (last edited 2012-07-13 17:20:00 by TatuSaloranta)

Copyright ©2009 FasterXML, LLC