# networknt/json-schema-validator architecture

> Architecture diagram of the GitHub repository networknt/json-schema-validator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/networknt/json-schema-validator
- Repository: https://github.com/networknt/json-schema-validator

## Overview

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.

Main entry points: [`src/main/java/com/networknt/schema/SchemaRegistry.java`](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/SchemaRegistry.java) (SchemaRegistry), [`src/main/java/com/networknt/schema/keyword`](https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/keyword) (Keywords), [`src/main/java/com/networknt/schema/Schema.java`](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/Schema.java) (Schema), [`src/main/java/com/networknt/schema/dialect/Dialects.java`](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/dialect/Dialects.java) (Dialects)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_schema_registry["SchemaRegistry<br/>entry/config"]
  node_schema["Schema<br/>[Schema.java]"]
  node_validator["Validator<br/>validation API<br/>[Validator.java]"]
  node_exec_config["Exec config<br/>runtime config"]
  node_schema_registry_config["Registry config"]
  node_execution_context["Exec context<br/>runtime context"]
end

subgraph group_engine["Validation Engine"]
  node_dialect_registry["Dialect registry<br/>dialect routing"]
  node_dialects["Dialects<br/>dialect model<br/>[Dialects.java]"]
  node_keyword_engine["Keywords<br/>validation engine"]
  node_annotations["Annotations<br/>metadata model"]
end

subgraph group_infra["Infrastructure"]
  node_resource_loader["Resource load<br/>retrieval boundary"]
  node_schema_loader["Schema loader<br/>identity resolution<br/>[SchemaLoader.java]"]
  node_serialization["Serialization<br/>jackson I/O"]
  node_path_result["Path & result<br/>reporting model"]
  node_output_model["Output model<br/>result shapes"]
  node_format_regex["Formats & regex<br/>constraint helpers"]
  node_i18n["Messages<br/>localization"]
  node_walk["Walker<br/>traversal"]
  node_utils_vocab["Utils & vocab<br/>shared support"]
  node_native_image["Native image<br/>build/runtime support"]
end

subgraph group_tests["Tests"]
  node_test_suite["Test suite<br/>conformance tests"]
  node_unit_tests["Unit tests<br/>regression tests"]
end

node_schema_registry -->|"loads"| node_resource_loader
node_schema_registry -->|"resolves"| node_schema_loader
node_schema_registry -->|"selects"| node_dialect_registry
node_schema_registry -->|"builds"| node_schema
node_validator -->|"uses"| node_schema
node_validator -->|"runs in"| node_execution_context
node_schema -->|"delegates"| node_keyword_engine
node_schema -->|"records"| node_annotations
node_dialect_registry -->|"registers"| node_dialects
node_dialects -->|"activates"| node_keyword_engine
node_keyword_engine -->|"checks"| node_format_regex
node_keyword_engine -->|"reports"| node_path_result
node_keyword_engine -->|"emits"| node_output_model
node_path_result -->|"materializes"| node_output_model
node_serialization -->|"feeds"| node_schema_registry
node_i18n -->|"configures"| node_execution_context
node_walk -->|"traverses"| node_schema
node_walk -->|"observes"| node_path_result
node_utils_vocab -.->|"supports"| node_dialects
node_utils_vocab -.->|"supports"| node_schema_loader
node_native_image -.->|"configures"| node_serialization
node_test_suite -.->|"verifies"| node_schema_registry
node_unit_tests -.->|"verifies"| node_keyword_engine

click node_schema_registry "https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/SchemaRegistry.java"
click node_schema "https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/Schema.java"
click node_validator "https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/Validator.java"
click node_exec_config "https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/ExecutionConfig.java"
click node_schema_registry_config "https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/SchemaRegistryConfig.java"
click node_execution_context "https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/ExecutionContext.java"
click node_dialect_registry "https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/dialect/DialectRegistry.java"
click node_dialects "https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/dialect/Dialects.java"
click node_keyword_engine "https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/keyword"
click node_annotations "https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/annotation"
click node_resource_loader "https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/resource/ResourceLoaders.java"
click node_schema_loader "https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/resource/SchemaLoader.java"
click node_serialization "https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/serialization"
click node_path_result "https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/path"
click node_output_model "https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/output"
click node_format_regex "https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/format"
click node_i18n "https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/i18n"
click node_walk "https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/walk"
click node_utils_vocab "https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/utils"
click node_native_image "https://github.com/networknt/json-schema-validator/tree/master/src/main/resources/META-INF/native-image"
click node_test_suite "https://github.com/networknt/json-schema-validator/tree/master/src/test/suite"
click node_unit_tests "https://github.com/networknt/json-schema-validator/tree/master/src/test/java/com/networknt/schema"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_schema_registry,node_schema,node_validator,node_exec_config,node_schema_registry_config,node_execution_context toneBlue
class node_dialect_registry,node_dialects,node_keyword_engine,node_annotations toneAmber
class node_resource_loader,node_schema_loader,node_serialization,node_path_result,node_output_model,node_format_regex,node_i18n,node_walk,node_utils_vocab,node_native_image toneMint
class node_test_suite,node_unit_tests toneRose
```

## Components

### Public API

Top-level entry points for loading schemas and running validation

- [SchemaRegistry](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/SchemaRegistry.java): entry/config · Central registry for loading, caching, and reusing schemas · `src/main/java/com/networknt/schema/SchemaRegistry.java`
- [Schema](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/Schema.java): compiled schema · Compiled schema handle used for repeated validation · `src/main/java/com/networknt/schema/Schema.java`
- [Validator](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/Validator.java): validation API · Validation entry point for instance data · `src/main/java/com/networknt/schema/Validator.java`
- [Exec config](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/ExecutionConfig.java): runtime config · Execution and input/output configuration types · `src/main/java/com/networknt/schema/ExecutionConfig.java`
- [Registry config](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/SchemaRegistryConfig.java): registry config · Schema registry configuration and defaults · `src/main/java/com/networknt/schema/SchemaRegistryConfig.java`
- [Exec context](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/ExecutionContext.java): runtime context · Per-run execution state passed through validation · `src/main/java/com/networknt/schema/ExecutionContext.java`

### Validation Engine

Dialect selection and keyword evaluation

- [Dialect registry](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/dialect/DialectRegistry.java): dialect routing · Resolves schema dialects from $schema or explicit configuration · `src/main/java/com/networknt/schema/dialect/DialectRegistry.java`
- [Dialects](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/dialect/Dialects.java): dialect model · Concrete JSON Schema and OpenAPI dialect definitions · `src/main/java/com/networknt/schema/dialect/Dialects.java`
- [Keywords](https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/keyword): validation engine · Keyword validator implementations and factories · `src/main/java/com/networknt/schema/keyword`
- [Annotations](https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/annotation): metadata model · Collected annotations used by unevaluated and output processing · `src/main/java/com/networknt/schema/annotation`

### Infrastructure

Serialization, retrieval, output, paths, localization, and supporting utilities

- [Resource load](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/resource/ResourceLoaders.java): retrieval boundary · Loads schema content from classpath, maps, and IRIs · `src/main/java/com/networknt/schema/resource/ResourceLoaders.java`
- [Schema loader](https://github.com/networknt/json-schema-validator/blob/master/src/main/java/com/networknt/schema/resource/SchemaLoader.java): identity resolution · Resolves schema IDs, retrieval URIs, and references · `src/main/java/com/networknt/schema/resource/SchemaLoader.java`
- [Serialization](https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/serialization): jackson I/O · Reads JSON and YAML documents into JsonNode trees · `src/main/java/com/networknt/schema/serialization`
- [Path & result](https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/path): reporting model · Instance location, evaluation path, and validation result tracking · `src/main/java/com/networknt/schema/path`
- [Output model](https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/output): result shapes · Flat and hierarchical output units plus output flags · `src/main/java/com/networknt/schema/output`
- [Formats & regex](https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/format): constraint helpers · Format validators and regex backend abstraction · `src/main/java/com/networknt/schema/format`
- [Messages](https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/i18n): localization · Localized message formatting and error text resolution · `src/main/java/com/networknt/schema/i18n`
- [Walker](https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/walk): traversal · Schema/instance traversal for defaults and custom walk callbacks · `src/main/java/com/networknt/schema/walk`
- [Utils & vocab](https://github.com/networknt/json-schema-validator/tree/master/src/main/java/com/networknt/schema/utils): shared support · IRI, type, Unicode, caching, and vocabulary helpers · `src/main/java/com/networknt/schema/utils`
- [Native image](https://github.com/networknt/json-schema-validator/tree/master/src/main/resources/META-INF/native-image): build/runtime support · GraalVM native-image configuration and resources · `src/main/resources/META-INF/native-image`

### Tests

Conformance, regression, and feature coverage

- [Test suite](https://github.com/networknt/json-schema-validator/tree/master/src/test/suite): conformance tests · JSON Schema test suite, remote fixtures, and draft coverage · `src/test/suite`
- [Unit tests](https://github.com/networknt/json-schema-validator/tree/master/src/test/java/com/networknt/schema): regression tests · Focused tests for keywords, formats, refs, output, and dialects · `src/test/java/com/networknt/schema`

## Connections

- SchemaRegistry → Resource load: loads · Turns schema locations into schema content
- SchemaRegistry → Schema loader: resolves · Resolves identities, IDs, and references
- SchemaRegistry → Dialect registry: selects · Chooses the schema dialect to compile against
- SchemaRegistry → Schema: builds · Produces compiled schema instances
- Validator → Schema: uses · Validates data through a compiled schema
- Validator → Exec context: runs in · Carries per-validation settings and state
- Schema → Keywords: delegates · Schema nodes map to keyword validators
- Schema → Annotations: records · Collects annotations during evaluation
- Dialect registry → Dialects: registers · Maintains concrete dialect implementations
- Dialects → Keywords: activates · Controls which vocabularies and keywords are active
- Keywords → Formats & regex: checks · Uses format validators and regex backends
- Keywords → Path & result: reports · Emits validation locations and failures
- Keywords → Output model: emits · Supports structured output shapes
- Path & result → Output model: materializes · Converts collected results into output forms
- Serialization → SchemaRegistry: feeds · Supplies parsed schema and instance documents
- Messages → Exec context: configures · Locale and message settings flow through execution
- Walker → Schema: traverses · Walks schema structure for defaults and callbacks
- Walker → Path & result: observes · Produces traversal events and path context
- Utils & vocab → Dialects: supports · Shared helpers for vocabularies and identifiers
- Utils & vocab → Schema loader: supports · Supports IRI and reference handling
- Native image → Serialization: configures · Registers reflective and resource access for native builds
- Test suite → SchemaRegistry: verifies · Exercises registry, refs, and remote retrieval behavior
- Unit tests → Keywords: verifies · Covers keyword validators and boundary behavior