Skip to content

JsonWriteFeatures

Manda Jensen edited this page Nov 24, 2020 · 4 revisions

Jackson Streaming: JsonWriteFeature

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 ObjectWriter instance as shown below (using WRITE_NUMBERS_AS_STRINGS as an enable example and QUOTE_FIELD_NAMES as a disable example):

// Option 1, modifying when constructing JsonFactory
JsonFactory f = JsonFactory.builder()
   .enable(JsonWriteFeature.WRITE_NUMBERS_AS_STRINGS)
   .disable(JsonWriteFeature.QUOTE_FIELD_NAMES)
   .build();
// Option 2, modifying when constructing JsonMapper or base type ObjectMapper
JsonMapper m = JsonMapper.builder()
   .enable(JsonWriteFeature.WRITE_NUMBERS_AS_STRINGS)
   .disable(JsonWriteFeature.QUOTE_FIELD_NAMES)
   .build();
ObjectMapper m = JsonMapper.builder()
   .enable(JsonWriteFeature.WRITE_NUMBERS_AS_STRINGS)
   .disable(JsonWriteFeature.QUOTE_FIELD_NAMES)
   .build();
// Option 3: defining when creating ObjectWriter instance
ObjectWriter r = mapper.writer()
   .with(JsonWriteFeature.WRITE_NUMBERS_AS_STRINGS)
   .without(JsonWriteFeature.QUOTE_FIELD_NAMES);

Features

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

Content escaping/quoting/encoding

  • QUOTE_FIELD_NAMES (default: true)
    • Feature that determines whether JSON Object field names are quoted using double-quotes, as specified by JSON specification or not. Ability to disable quoting was added to support use cases where they are not usually expected, which most commonly occurs when used straight from Javascript.
    • Maps to JsonGenerator.Feature.QUOTE_FIELD_NAMES
  • WRITE_NAN_AS_STRINGS (default: true)
    • Feature that determines whether "NaN" ("not a number", that is, not real number) float/double values are output as JSON strings.
    • The values checked are Double.Nan, Double.POSITIVE_INFINITY and Double.NEGATIVE_INIFINTY (and associated Float values).
    • If feature is disabled, these numbers are still output using associated literal values, resulting in non-conforming output.
    • Maps to JsonGenerator.Feature.QUOTE_NON_NUMERIC_NUMBERS
  • WRITE_NUMBERS_AS_STRINGS (default: false)
    • Feature that forces all regular number values to be written as JSON Strings, instead of as JSON Numbers (that is, enclosed in double-quotes)
    • Maps to JsonGenerator.Feature.WRITE_NUMBERS_AS_STRINGS
  • ESCAPE_NON_ASCII (default: false)
    • Feature that specifies that all characters beyond 7-bit ASCII range (i.e. code points of 128 and above) need to be output using backslash-escape.
    • Maps to JsonGenerator.Feature.ESCAPE_NON_ASCII