JsonWriteFeatures

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

• COMBINE_UNICODE_SURROGATES_IN_UTF8 (default: false) (added in 2.18)
  • Feature that specifies how characters outside "Basic Multilingual Plane" (BMP) -- ones encoded as 4-byte UTF-8 sequences but represented in JVM memory as 2 16-bit "surrogate" chars -- should be encoded as UTF-8 by JsonGenerator
    • If enabled, surrogate pairs are combined and flushed as a single, 4-byte UTF-8 character.
    • If disabled, each char of surrogate pair is written as 2 separate characters: that is, as 2 separate 3-byte UTF-8 characters with values in Surrogate character ranges(0xD800 - 0xDBFF and 0xDC00 - 0xDFFF)
• ESCAPE_FORWARD_SLASHES (default: false (2.x), true (3.x)) (added in 2.17)
  • Feature that specifies whether JsonGenerator should escape forward slashes ("/") by default (without other encoding configuration)
    • If enabled, forward slashes are escaped (as '/')
    • If disabled, forward slashes are written as-is (as /)
  • Feature is disabled by default in Jackson 2.x, but enabled by default in Jackson 3.0.
• 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
• 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_HEX_UPPER_CASE (default: true)
  • Feature that specifies whether hex values are encoded using upper-case letters (true) or lower-case letters (false)
  • JSON uses hex-values for character escapes
• 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