StreamReadConstraints

Jackson core, Processing Limits: StreamReadConstraints

General

StreamReadConstraints were added in Jackson 2.15 to provide configurable limits on streaming input.
They act as guards against malicious or overly large JSON input by preventing processing of "too big" values or structures.

Constraints are registered with a TokenStreamFactory (such as JsonFactory).
If nothing is explicitly specified, default constraints are used.

Usage

Constraints can be configured in different ways:

// Option 1: (preferred) use builder directly when constructing JsonFactory
JsonFactory f = JsonFactory.builder()
    .streamReadConstraints(
        StreamReadConstraints.builder()
            .maxNestingDepth(500)
            .maxStringLength(10_000_000)
            .maxDocumentLength(5_000_000)
            .build()
    )
    .build();

// Option 2: (discouraged) override defaults globally (use with caution!)
StreamReadConstraints.overrideDefaultStreamReadConstraints(
    StreamReadConstraints.builder()
        .maxNestingDepth(200)
        .maxStringLength(5_000_000)
        .build()
);

Note: Option 2 changes the default constraints used by all new JsonFactory instances unless explicitly overridden.

Features

Currently constrained aspects:

Nesting Depth

• Maximum nesting depth

  • Default: 1000
  • Accessor: getMaxNestingDepth()
  • Builder method: builder().maxNestingDepth(int)
  • Depth is the number of open objects { and arrays [ that have not yet been closed.
  • Setting a negative value throws IllegalArgumentException.

• Validation helper: validateNestingDepth(int depth) Throws StreamConstraintsException if exceeded.

Document Length

• Maximum document length

  • Default: unlimited (-1)
  • Accessor: getMaxDocumentLength()
  • Builder method: builder().maxDocumentLength(long)
  • Checked when reading new chunks of input.

• Validation helper: validateDocumentLength(long len)

Token Count

• Maximum token count

  • Default: unlimited (-1)
  • Accessor: getMaxTokenCount()
  • Builder method: builder().maxTokenCount(long)

• Validation helper: validateTokenCount(long count)

Number Length

• Maximum number length

  • Default: 1000
  • Accessor: getMaxNumberLength()
  • Builder method: builder().maxNumberLength(int)

• Validation helpers: validateIntegerLength(int), validateFPLength(int)

String Length

• Maximum string length

  • Default: 20_000_000
  • Accessor: getMaxStringLength()
  • Builder method: builder().maxStringLength(int)

• Validation helper: validateStringLength(int)

Property Name Length

• Maximum name length

  • Default: 50_000
  • Accessor: getMaxNameLength()
  • Builder method: builder().maxNameLength(int)

• Validation helper: validateNameLength(int)

BigInteger Scale

• Maximum magnitude of BigDecimal scale

  • Default: 100_000

• Validation helper: validateBigIntegerScale(int)

Default Values

• DEFAULT_MAX_DEPTH = 1000
• DEFAULT_MAX_DOC_LEN = -1
• DEFAULT_MAX_TOKEN_COUNT = -1
• DEFAULT_MAX_NUM_LEN = 1000
• DEFAULT_MAX_STRING_LEN = 20_000_000
• DEFAULT_MAX_NAME_LEN = 50_000

Fetch the current defaults:

StreamReadConstraints defaults = StreamReadConstraints.defaults();

Notes

• Use overrideDefaultStreamReadConstraints(...) only in application code (never in libraries) to avoid interfering with other Jackson usage.
• For libraries, configure ObjectMapper or JsonFactory instances individually instead.