Skip to content

JsonParser Features

Jump to bottom
Tatu Saloranta edited this page Jun 22, 2022 · 10 revisions

Jackson Streaming: JsonParser.Feature

Jackson Streaming API has a set of on/off features that change the way streaming parsing is done. Features can be directly enabled/disabled on JsonParser instances, but more commonly default values are changed on JsonFactory instances. For example:

JsonFactory f = new JsonFactory();
f.enable(JsonParser.Feature.ALLOW_COMMENTS);
f.disable(JsonParser.Feature.ALLOW_SINGLE_QUOTES);
JsonParser p = f.createParser(jsonSource);
p.enable(JsonParser.Feature.STRICT_DUPLICATE_DETECTION);

Status

Jackson 2.10 introduced Feature refactoring so that entries specified here we split into 2 new features

These new features are mapped to old ones, wherever those exist: for backward-compatibility reason you can use either new settings, or old ones described here. With 3.0, only new ones will be usable.

General Notes

Although use of these features is shared by all data format modules (and despite many format modules specifying additional format-specific features), not all features listed here apply to all data formats. Sometimes choice of addition of a feature for specific format module, and generic generator feature is arbitrary. The intent is for all features that are likely to be needed by more than one format should be included here, to reduce/remove overlapping features with same semantics.

Features

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

Low-level I/O handling features

  • AUTO_CLOSE_SOURCE (default: true)
    • (in 2.10) Maps to StreamReadFeature.AUTO_CLOSE_SOURCE

Support for non-standard data format constructs

  • ALLOW_COMMENTS (default: false) (for textual formats with concept of comments)
    • For textual formats that do not have official comments, but for which "de facto" conventions exist (like JSON), determines whether use of such unofficial comments is allowed or not
    • Supported for: JSON
    • For JSON: enabling the feature allows recognition and handling of "C comments" (/* ... */) and "C++ comments" (// ....)
    • YAML supports its own "hash comments" regardless of this setting
    • (in 2.10) Maps to JsonReadFeature.ALLOW_JAVA_COMMENTS
  • ALLOW_YAML_COMMENTS (default: false)
    • Supported for: JSON (YAML allows by default)
    • For JSON: enabling the feature allows recognition and handling of "hash comments" (# .... )
    • (in 2.10) Maps to JsonReadFeature.ALLOW_YAML_COMMENTS
  • ALLOW_UNQUOTED_FIELD_NAMES (default: false)
    • Supported for: JSON
    • (in 2.10) Maps to JsonReadFeature.ALLOW_UNQUOTED_FIELD_NAMES
  • ALLOW_SINGLE_QUOTES (default: false)
    • Supported for: JSON
    • (in 2.10) Maps to JsonReadFeature.ALLOW_SINGLE_QUOTES
  • ALLOW_UNQUOTED_CONTROL_CHARS (default: false)
    • Supported for: JSON
    • (in 2.10) Maps to JsonReadFeature.ALLOW_UNESCAPED_CONTROL_CHARS
  • ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER (default: false)
    • Supported for: JSON
    • (in 2.10) Maps to JsonReadFeature.ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTER
  • ALLOW_NUMERIC_LEADING_ZEROS (default: false)
    • Supported for: JSON
    • (in 2.10) Maps to JsonReadFeature.ALLOW_LEADING_ZEROS_FOR_NUMBERS
  • ALLOW_NON_NUMERIC_NUMBERS (default: false)
    • Supported for: JSON
    • (in 2.10) Maps to JsonReadFeature.ALLOW_NON_NUMERIC_NUMBERS
  • ALLOW_MISSING_VALUES (default: false) (since 2.8)
    • Allow translation of "missing" values (white-space between two commas, in JSON Array context) into null values, instead of an exception
    • Supported for: JSON
    • (in 2.10) Maps to JsonReadFeature.ALLOW_MISSING_VALUES
  • ALLOW_TRAILING_COMMA (default: false) (since 2.9)
    • Allow for a single "trailing" comma (one that comes after the last Array value or Object entry
    • If enabled, would accept following non-standard values:
      • [ 1, 2, 3, ]
      • `{ "value" : 42, }
    • Supported for: JSON
    • (in 2.10) Maps to JsonReadFeature.ALLOW_TRAILING_COMMA

Additional input validation

  • STRICT_DUPLICATE_DETECTION (default: false) (added in 2.3)

    • (in 2.10) Maps to StreamReadFeature.STRICT_DUPLICATE_DETECTION

  • IGNORE_UNDEFINED (default: false) (added in 2.6)

    • With formats that require Schema for parsing (like Avro, Protobuf, CSV), determines what happens if decoded encounters content that Schema has no definition for: if disabled, exception is thrown; if enabled, such content is quietly ignored.
    • Supported for: Avro, CSV
    • Note: setting has no effect on Avro since it has no mechanism for recognizing such "unknown" content -- there is no way for decoder to ignore such content and instead a decoding error is thrown (or data corruption occurs)
    • (in 2.10) Maps to StreamReadFeature.IGNORE_UNDEFINED

Misc other

  • INCLUDE_SOURCE_IN_LOCATION (defalt: true) (added in 2.9)
    • Feature that determines whether {@link JsonLocation} (for exceptions and direct location access) instances should be constructed with reference to source or not.
    • If feature is disabled, no source reference is passed and source is only indicated as "UNKNOWN"
    • Most common reason for disabling this feature is to avoid leaking internal information; this may be done for security reasons.
    • (in 2.10) Maps to StreamReadFeature.INCLUDE_SOURCE_IN_LOCATION
Clone this wiki locally