networknt JSON Schema Validator

The networknt/json-schema-validator is a high-performance Java implementation of the JSON Schema specification. It is designed for microservices environments where validation performance is critical.

Key features include:

• Specification Support: Compatible with JSON Schema Core Drafts v4, v6, v7, v2019-09, and v2020-12.
• Extensibility: Supports customizing Dialects, Vocabularies, Keywords, and Formats.
• OpenAPI Support: Supports OpenAPI 3 request/response validation using the appropriate dialect.
• Jackson Integration: Uses the Jackson parser for JSON processing.

This library is a core component of the light-4j microservices framework.

The validator's performance is highly dependent on the input data workloads and the specific JSON Schema keywords used.

Performance Considerations:

• Annotation Collection: Using unevaluatedProperties or unevaluatedItems triggers annotation collection in related validators (like properties or items), which can adversely affect performance.
• Inefficient Schemas: Deeply nested oneOf or anyOf structures that lack if/then conditions to short-circuit evaluation will force the validator to perform all evaluations, potentially leading to confusing error messages.
• Benchmarks: Performance varies by workload. For high-performance requirements, benchmark your specific schemas and data using the JSON Schema Validator Perftest project.

The library uses a versionCode (a bitmask) within ValidatorTypeCode to determine which schema versions a specific validator supports.

• A versionCode of 31 (binary 11111) indicates the validator is compatible with all supported versions (V4, V6, V7, V2019-09, and V2020-12).
• Specific bitmasks are used for features introduced in later drafts. For example, if-then-else (introduced in V7) uses a code that only enables it for V7, V2019-09, and V2020-12.

The library provides three built-in RegularExpressionFactory implementations for pattern and format: regex validators. Choose based on your requirements for ECMA-262 compliance, performance, and dependency footprint:

1. JDKRegularExpressionFactory (Default): Uses standard java.util.regex via the find() method. It requires no additional libraries and offers the best performance, but does not strictly follow ECMA-262.
2. JoniRegularExpressionFactory: Uses org.joni.Regex with Syntax.ECMAScript. Requires the org.jruby.joni:joni dependency (~2MB). It attempts to match ECMA-262 but has known issues with newlines and ^/$ anchors.
3. GraalJSRegularExpressionFactory: Uses GraalJS with new RegExp(pattern, 'u'). Requires the org.graalvm.js:js dependency (~50MB). This is the only implementation that provides strict compliance with the ECMA-262 dialect.

When typeLoose is set to true, the validator performs type conversion to match the schema. This is particularly useful for validating HTTP components (headers, query parameters, cookies) which are natively strings but may be defined as other types in a schema.

Key behaviors:

• String Conversion: Strings may be interpreted as number, integer, or boolean to match the schema.
• Array Interpretation: Any single value can be interpreted as a size-1 array containing that item, allowing it to be validated against the array's item type definition.

This setting controls how the nullable keyword (from OpenAPI specifications) interacts with the validator:

• If true: If a field is marked nullable and the incoming value is null, the validation succeeds.
• If false: If a field is marked nullable and the incoming value is null, the outcome depends on the specific type validator used by the SchemaValidator to handle nulls.

When writing JSON Schemas that use regular expressions, follow these specification guidelines:

Compliance

• Regular expressions SHOULD follow the ECMA-262 dialect.
• Use the "u" flag (or equivalent) for Unicode support.

Recommended Tokens

To ensure cross-implementation compatibility, limit regex patterns to:

• Individual Unicode characters (RFC8259).
• Simple character classes ([abc]) and ranges ([a-z]).
• Complemented character classes ([^abc]).
• Simple quantifiers: +, *, ? and their lazy versions (+?, *?, ??).
• Range quantifiers: {x}, {x,y}, {x,} and their lazy versions.
• Anchors: ^ (beginning-of-input) and $ (end-of-input).
• Grouping (...) and alternation |.

Anchoring Behavior

Implementations MUST NOT treat regular expressions as implicitly anchored. A pattern like es should match the string expression.

When validating durations, be aware of the following behavioral differences between the RFC 3339 standard used by JSON Schema (Draft 2019-09 and later) and the standard Java Date/Time API:

Note: If you enable strict("duration", false) in your configuration, the validator will permit fractional seconds, negative durations, and combining weeks with other terms.

This library supports multiple versions of the JSON Schema specification:

• Draft 4
• Draft 6
• Draft 7
• Draft 2019-09
• Draft 2020-12

Note on the format keyword: Starting from Draft 2019-09, the format keyword only generates annotations by default and does not generate assertions. To enable assertions for the format keyword, you must set formatAssertionsEnabled to true in either SchemaRegistryConfig or ExecutionConfig.