networknt/json-schema-validator

1. What this repository is

This is a Java JSON Schema validation library, not an application. Its core job is to take a schema plus input data, resolve any referenced schemas, evaluate the input against the correct dialect, and return assertions/annotations in one of several output shapes.

2. Primary public API surface

The main entry points are SchemaRegistry, Schema, Validator, and the execution/configuration types around them: SchemaRegistryConfig, ExecutionConfig, ExecutionContext, InputFormat, and OutputFormat. Architecturally, everything funnels through “load schema once, validate many inputs” semantics.

3. Validation pipeline

The flow is: parse schema and instance data with Jackson, build or reuse a Schema from the registry, then validate input by walking the schema tree and invoking keyword-specific validators. Validation produces Error objects by default, or structured OutputUnit / OutputFlag results when using explicit output formats.

4. Schema retrieval and identity resolution

The resource package is the retrieval boundary. It includes loaders for classpath resources, maps, IRIs, and schema-id resolution strategies. This is where $id, retrieval URI mapping, remote resolution, and caching/preloading are handled. The registry uses these components to turn a logical schema location into actual schema content.

5. Dialect layer

The dialect package models JSON Schema versions and OpenAPI dialects. There are concrete dialects for Draft 4, 6, 7, 2019-09, 2020-12, plus OpenAPI 3.0 and 3.1. Dialects define which vocabularies and keywords are active, and they are selected either explicitly or from $schema.

6. Keyword evaluation engine

The keyword package is the validation engine. Each keyword has a dedicated validator class, such as PropertiesValidator, ItemsValidator, RequiredValidator, RefValidator, AnyOfValidator, OneOfValidator, ContainsValidator, UnevaluatedPropertiesValidator, and many others. Factories and base classes wire schema nodes to validators, and unknown-keyword behavior can be made strict or permissive.

7. Annotations vs assertions

A major architectural boundary is between assertion keywords and annotation keywords. Assertion validators emit validation failures; annotation-related code records metadata used later by keywords like unevaluatedProperties, output reporting, or custom downstream processing. This distinction is important for later drafts where format may be annotation-only unless assertions are enabled.

8. Path, result, and output model

The path, result, and output packages define how validation context is reported. They track instance location, evaluation path, schema location, and error metadata. The library supports JSON Pointer or JSON Path-style reporting, and can materialize flat lists or hierarchical trees of results.

9. Serialization boundary

Input and schema documents are read through the serialization package, which is centered on Jackson JsonNode handling. There are readers for JSON and YAML, and optional location-aware node factories that preserve line/column information for better diagnostics. This is also where the repo supports both JSON and YAML schema/input documents.

10. Format and regex subsystem

The format package contains validators for common formats like date, date-time, duration, URI/IRI, email, hostname, IPv4/IPv6, and regex. The regex package abstracts the regular-expression backend: JDK is the default, while Joni and GraalJS provide closer ECMA-262 behavior when those optional dependencies are present.

11. Walker subsystem

The walk package is separate from validation and is used for traversing schemas and instances, especially for default application and custom walk callbacks. It provides handlers for keywords, properties, and array items, so consumers can inspect or mutate traversal behavior without hard-coding validation logic.

12. Localization and message customization

Error message generation is handled through the i18n package and resource bundles under src/main/resources/jsv-messages*.properties. The registry and execution context can select locale, and there is explicit support for custom error-message keywords and localized reporting.

13. Shared utilities and vendored helpers

The utils, vocabulary, and annotation packages provide support code for IRI/URI handling, type inspection, caching, Unicode and RFC-related helpers, vocabulary registration, and annotation collections. The com.networknt.org.apache.commons.validator subtree is vendored code used to avoid additional runtime dependencies for domain/email/IP validation.

14. Packaging, runtime, and native-image support

The project is built with Maven and targets Java 8+ according to the README. It includes GraalVM native-image configuration under META-INF/native-image, indicating the library is designed to work in native binaries as well as on the JVM.

15. Test and compatibility architecture

The repository is heavily driven by conformance tests. src/test/suite contains the JSON Schema Test Suite and remote-schema fixtures across multiple drafts, while src/test/java contains unit, regression, benchmark, and OpenAPI-specific tests. This test layout mirrors the production architecture: dialects, keywords, refs, formats, walkers, output, and localization all have dedicated coverage.