Skip to content

JsonReadFeatures

Tatu Saloranta edited this page Jun 23, 2022 · 11 revisions

Jackson Streaming: JsonReadFeature

General

This set of features was added in Jackson 2.10, split off from earlier JsonParser.Feature. It contains features that are only relevant and usable on JSON backend.

Note: with 2.10 and later 2.x version there is overlap between new and old features: Jackson will keep "same" settings in sync so you can whichever; but recommendation is to use newer set of features to ease migration to 3.0.

These features can be modified when constructing JsonFactory or JsonMapper (or ObjectMapper since JsonMapper is a subtype of ObjectMapper), or when creating ObjectReader instance as shown below (using ALLOW_JAVA_COMMENTS as example):

// Option 1, modifying when constructing JsonFactory
JsonFactory f = JsonFactory.builder().enable(JsonReadFeature.ALLOW_JAVA_COMMENTS).build();
// Option 2, modifying when constructing JsonMapper or base type ObjectMapper
JsonMapper m = JsonMapper.builder().enable(JsonReadFeature.ALLOW_JAVA_COMMENTS).build();
ObjectMapper m = JsonMapper.builder().enable(JsonReadFeature.ALLOW_JAVA_COMMENTS).build();
// Option 3: defining when creating ObjectReader instance
ObjectReader r = mapper.readerFor(MyType.class).with(JsonReadFeature.ALLOW_JAVA_COMMENTS);

Features

Settings can be divided in couple of loose categories, as follows.

Support for non-standard JSON content (deviations from JSON specification)

  • ALLOW_JAVA_COMMENTS (default: false) (for textual formats with concept of comments)
    • Enabling the feature allows recognition and handling of "C comments" (/* ... */) and "C++ comments" (// ....)
    • Maps to JsonParser.Feature.ALLOW_COMMENTS (note naming difference!)
  • ALLOW_YAML_COMMENTS (default: false)
    • For JSON: enabling the feature allows recognition and handling of "hash comments" (# .... )
    • Maps to JsonParser.Feature.ALLOW_YAML_COMMENTS
  • ALLOW_SINGLE_QUOTES (default: false)
    • Feature that determines whether parser will allow use of single quotes (apostrophe, character "'") for quoting JSON Strings (names and String values). If so, this is in addition to other acceptable markers.
    • Maps to JsonParser.Feature.ALLOW_SINGLE_QUOTES
  • ALLOW_UNQUOTED_FIELD_NAMES (default: false)
    • Feature that determines whether parser will allow use of unquoted field names (which is allowed by Javascript, for example, but not by JSON specification).
    • Maps to JsonParser.Feature.ALLOW_UNQUOTED_FIELD_NAMES
  • ALLOW_UNESCAPED_CONTROL_CHARS (default: false)
    • Feature that determines whether parser will allow JSON Strings to contain unescaped control characters (ASCII characters with value less than 32, including tab and line feed characters) or not.
      • If feature is set false, an exception is thrown if such a character is encountered.
    • Maps to JsonParser.Feature.ALLOW_UNQUOTED_CONTROL_CHARS (Note the naming difference!)
  • ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER (default: false)
    • Feature that can be enabled to accept quoting of all character using backslash quoting mechanism: if not enabled, only characters that are explicitly listed by JSON specification can be escaped (see JSON spec for small list of these characters)
    • Maps to JsonParser.Feature.ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER
  • ALLOW_LEADING_ZEROS_FOR_NUMBERS (default: false)
    • Feature that determines whether parser will allow JSON integral numbers to start with additional (ignorable) zeroes (like: 000001).
    • If enabled, no exception is thrown, and extra zeroes are silently ignored (and not included in textual representation exposed via JsonParser.getText().
    • Maps to JsonParser.Feature.ALLOW_NUMERIC_LEADING_ZEROS (Note the naming difference!)
  • ALLOW_LEADING_PLUS_SIGN_FOR_NUMBERS (default: false) (added in 2.14)
    • Feature that determines whether parser will allow JSON decimal numbers to start with a plus sign (like: +123).
    • If enabled, no exception is thrown, and the number is parsed as though a leading sign had not been present.
  • ALLOW_LEADING_DECIMAL_POINT_FOR_NUMBERS (default: false) (added in 2.11)
    • Feature that determines whether parser will allow JSON decimal numbers to start with a decimal point (like: .123).
    • If enabled, no exception is thrown, and the number is parsed as though a leading 0 had been present.
  • ALLOW_TRAILING_DECIMAL_POINT_FOR_NUMBERS (default: false) (added in 2.14)
    • Feature that determines whether parser will allow JSON decimal numbers to end with a decimal point with no numbers after (like: 123.).
    • If enabled, no exception is thrown, and the number is parsed as if we had trailing .0 (or, just integer number but type is detected as floating point)
  • ALLOW_NON_NUMERIC_NUMBERS (default: false)
    • Feature that allows parser to recognize set of "Not-a-Number" (NaN) tokens as legal floating number values (similar to how many other data formats and programming language source code allows it).
    • Specific subset contains values that XML Schema (see section 3.2.4.1, Lexical Representation) allows (tokens are quoted contents, not including quotes):
      • "INF" (for positive infinity), as well as alias of "Infinity"
      • "-INF" (for negative infinity), alias "-Infinity"
      • "NaN" (for other not-a-numbers, like result of division by zero)
    • Maps to JsonParser.Feature.ALLOW_NON_NUMERIC_NUMBERS
  • ALLOW_MISSING_VALUES (default: false)
    • Allow translation of "missing" values (white-space between two commas, in JSON Array context) into null values, instead of an exception
    • Maps to JsonParser.Feature.ALLOW_MISSING_VALUES
  • ALLOW_TRAILING_COMMA (default: false)
    • Feature that determines whether JsonParser will allow for a single trailing comma following the final value (in an Array) or member (in an Object). These commas will simply be ignored.
    • For example, when this feature is enabled, [true,true,]` is equivalent to `[true, true] and {"a": true,} is equivalent to {"a": true}.
    • Maps to JsonParser.Feature.ALLOW_TRAILING_COMMA