json-schema-validator: JSON Schema draft 7 validation inside the nlohmann namespace

It lives in the nlohmann namespace for a reason

The library is a C++ implementation for validating JSON documents against a JSON Schema, and the schema itself is expected to validate with draft 7 of JSON Schema Validation. The name comes from its foundation. Niels Lohmann and others develop JSON for Modern C++, and this validator is based on that library, which is why the code lives in his namespace, now nlohmann::json_schema. The README is direct about the trade-off that implies, because the project deliberately did not add its own JSON parser, so you inherit the dependency, the parsing behaviour and the type model of nlohmann-json. Version 2 was a complete rewrite with significant changes, but the API stayed compatible with the 1.0.0 release, with the namespace being the one visible break. A separate OAuth-like point about licensing is not needed here, but the licence in the repository is one GitHub cannot classify, so the LICENSE file is the document to read.

Version 2 compiles the schema into C++ objects

The single biggest change in version 2 is how a schema is used, and the README explains it in operational terms. In version 1 the schema was kept as a JSON document and used again and again during validation, meaning every validation walked the schema structure. In version 2 the schema is parsed into compiled C++ objects that are then used during validation, and the README says validation speed improved by a factor of 100 or more, while conceding there are surely still optimizations to be done. That ratio is the reason to upgrade even if your schemas never change. The other change in version 2 is the draft, since version 2 supports JSON Schema draft 7 while version 1 supported draft 4 only, and the README says plainly that you should update your schemas. That last point is the practical trap for anyone porting an existing application.

Errors arrive as exceptions or through your own handler

The stated main goal is to produce human-comprehensible error messages when a document does not comply with its schema, and by default that is done with exceptions thrown at the user with a helpful message telling what is wrong with the document while validating. From 2.0.0 onward there is a second route. You can pass a json_schema::basic_error_handler derived object along with the instance to validate, and you receive a callback each time a validation error occurs, at which point you decide what to do, whether that is throwing, counting or collecting. The design implication is worth stating plainly. If you are validating untrusted input in a request handler, exceptions are the wrong default, and the callback is the API you want, because it lets you count errors, log them in your own format or turn them into a field-level error report.

Validation is thread safe, construction is not

The thread safety section draws a line that is easy to get wrong. Instance validation is thread-safe and the same validator object can be used by different threads, because the validate method is const, which indicates the object is not modified when it is called. The declaration is even shown:

	json json_validator::validate(const json &) const;

Validator object creation, on the other hand, is not thread-safe, and a validator has to be created in one thread, the main one by implication, once. That is a normal pattern for this kind of compiled artefact, and it is the difference between a validator you build at start-up and hand to a pool of workers, and one you lazily build on first use. If your service validates per request, the construction cost and the thread-safety constraint are the two things to design around.

Out-of-source CMake, and how nlohmann-json is found

The build is a normal CMake project with one rule, that you should not run cmake inside the source directory but create a dedicated build directory:

git clone https://github.com/pboettch/json-schema-validator.git
cd json-schema-validator
mkdir build
cd build
cmake [..]
make
make install # if needed
ctest # run unit, non-regression and test-suite tests

A static library is built by default, and a shared one with the JSON_VALIDATOR_SHARED_LIBS option, which by default takes the value of CMake's BUILD_SHARED_LIBS:

cmake [..] -DJSON_VALIDATOR_SHARED_LIBS=ON [..]

The dependency resolution order for nlohmann-json is spelled out, which is the part worth memorising. If a CMake target named nlohmann_json already exists, that is used, which is the case when a parent project added nlohmann-json with add_subdirectory or FetchContent first. Otherwise an installed nlohmann-json is found with find_package, and if there is none it is fetched from GitHub with FetchContent, with the version set by JSON_FETCH_VERSION, default v3.12.0:

cmake [..] -DJSON_FETCH_VERSION=v3.11.3 [..]

At least version 3.8.0 of the JSON library is required, and the README warns that the library and the code using it must be compiled with the same version, since the symbols are versioned from 3.11 onwards and a mismatch produces link errors.

Installing through FetchContent has one trap

The library can be added to a parent project with add_subdirectory or FetchContent, and in that case its tests, examples and install rules are disabled by default, and you link the nlohmann_json_schema_validator::validator target. Since version 2.1.0 the library can be installed and CMake package files are created, so a consumer can find it with find_package and link the same namespaced target. Before version 2.3.0 the target was named without the namespace, which is a detail that breaks older build files when you upgrade. The trap the README warns about is with installation. When the library comes in through FetchContent or add_subdirectory its install rules are off by default, and you should not add nlohmann_json_schema_validator to your own install(TARGETS ...), because the header will not be found or will land in the wrong location. The fix is to enable the library's own install rules before making it available:

include(FetchContent)

set(JSON_VALIDATOR_INSTALL ON)
FetchContent_Declare(nlohmann_json_schema_validator
    GIT_REPOSITORY https://github.com/pboettch/json-schema-validator
    GIT_TAG        2.4.1)
FetchContent_MakeAvailable(nlohmann_json_schema_validator)

target_link_libraries(<your-target> PRIVATE nlohmann_json_schema_validator::validator)

If nlohmann-json is fetched as well, it is installed alongside, with JSON_Install enabled automatically.

Known weaknesses and the release rhythm

The weaknesses section is short and specific. Numerical validation uses the integer, unsigned and floating point types of nlohmann-json depending on whether the schema type is integer or number, and bignum, meaning arbitrary precision and range, is not supported at this time. If your schema allows values beyond 64 bit, that is a real boundary rather than a rounding detail. The project also opens with a disclaimer that it is work in progress and that contributions, hints and discussions are welcome, and it admits that external documentation is missing even though the API is rather simple. The repository is well equipped around that, though, with a ChangeLog.md, a CMakePresets.json, a conanfile.py for Conan users, a schema/ directory, a test_package/ directory for distribution testing, an example/ directory and a pre-commit configuration. The releases are 2.4.1 on 2026-10-13, 2.4.0 on 2025-12-16 and 2.3.0 on 2024-01-02, and the last push was on 2026-10-14, so patch releases are frequent and minor versions are roughly annual.

Editorial conclusion

Adopt json-schema-validator if your C++ project already uses JSON for Modern C++ and you need schema validation with error messages that point at the offending part of the document rather than a boolean. Do not adopt it if your documents carry arbitrary precision numbers, because the README lists bignum support as a weakness, and treat it as a project with thin external documentation and an explicit work in progress disclaimer. Verify first that the nlohmann-json version you compile against matches the one the library was built with, since versioned symbols cause link errors on a mismatch, and that your schemas are draft 7, because version 1 only supported draft 4.

Frequently asked questions

Official sources

1. Issues
2. pboettch/json-schema-validator on GitHub
3. README
4. Releases