9.0 KiB
JSON schema validator for JSON for Modern C++
This is a C++ library for validating JSON documents based on a JSON Schema which itself should validate with draft-7 of JSON Schema Validation.
First a disclaimer: It is work in progress and contributions or hints or discussions are welcome.
Niels Lohmann et al develop a great JSON parser for C++ called JSON for Modern C++. This validator is based on this library, hence the name.
Building
This library is based on Niels Lohmann's JSON-library and thus has a build-dependency to it.
Currently at least version 3.6.0 of NLohmann's JSON library is required.
Various methods using CMake can be used to build this project.
Build out-of-source
Do not run cmake inside the source-dir. Rather create a dedicated build-dir:
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
Building as shared library
By default a static library is built. Shared libraries can be generated by using
the BUILD_SHARED_LIBS-cmake variable:
In your initial call to cmake simply add:
cmake [..] -DBUILD_SHARED_LIBS=ON [..]
nlohmann-json integration
As nlohmann-json is a dependency, this library tries find it.
The cmake-configuration first checks if nlohmann-json is available as a cmake-target. This may be the case, because it is used as a submodule in a super-project which already provides and uses nlohmann-json.
Otherwise, it calls find_package for nlohmann-json and requires nlohmann-json to be installed on the system.
Building with Hunter package manager
To enable access to nlohmann json library, Hunter can be used. Just run with JSON_VALIDATOR_HUNTER=ON option. No further dependencies needed
cmake [..] -DJSON_VALIDATOR_HUNTER=ON [..]
Building as a CMake-subdirectory from within another project
Adding this library as a subdirectory to a parent project is one way of building it.
If the parent project already used find_package() to find the CMake-package of nlohmann_json or includes it as a submodule likewise.
Building directly, finding a CMake-package. (short)
When nlohmann-json has been installed, it provides files which allows
CMake's find_package() to be used.
This library is using this mechanism if nlohmann_json::nlohmann_json-target
does not exist.
Install
Since version 2.1.0 this library can be installed and CMake-package-files will be created accordingly. If the installation of nlohmann-json and this library is done into default unix-system-paths CMake will be able to find this library by simply doing:
find_package(nlohmann_json_schema_validator REQUIRED)
and
target_link_libraries(<your-target> [..] nlohmann_json_schema_validator)
to build and link.
Code
See also app/json-schema-validate.cpp.
#include <iostream>
#include <iomanip>
#include <nlohmann/json-schema.hpp>
using nlohmann::json;
using nlohmann::json_schema::json_validator;
// The schema is defined based upon a string literal
static json person_schema = R"(
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "A person",
"properties": {
"name": {
"description": "Name",
"type": "string"
},
"age": {
"description": "Age of the person",
"type": "number",
"minimum": 2,
"maximum": 200
}
},
"required": [
"name",
"age"
],
"type": "object"
}
)"_json;
// The people are defined with brace initialization
static json bad_person = {{"age", 42}};
static json good_person = {{"name", "Albert"}, {"age", 42}};
int main()
{
/* json-parse the schema */
json_validator validator; // create validator
try {
validator.set_root_schema(person_schema); // insert root-schema
} catch (const std::exception &e) {
std::cerr << "Validation of schema failed, here is why: " << e.what() << "\n";
return EXIT_FAILURE;
}
/* json-parse the people - API of 1.0.0, default throwing error handler */
for (auto &person : {bad_person, good_person}) {
std::cout << "About to validate this person:\n"
<< std::setw(2) << person << std::endl;
try {
validator.validate(person); // validate the document - uses the default throwing error-handler
std::cout << "Validation succeeded\n";
} catch (const std::exception &e) {
std::cerr << "Validation failed, here is why: " << e.what() << "\n";
}
}
/* json-parse the people - with custom error handler */
class custom_error_handler : public nlohmann::json_schema::basic_error_handler
{
void error(const nlohmann::json_pointer<nlohmann::basic_json<>> &pointer, const json &instance,
const std::string &message) override
{
nlohmann::json_schema::basic_error_handler::error(pointer, instance, message);
std::cerr << "ERROR: '" << pointer << "' - '" << instance << "': " << message << "\n";
}
};
for (auto &person : {bad_person, good_person}) {
std::cout << "About to validate this person:\n"
<< std::setw(2) << person << std::endl;
custom_error_handler err;
validator.validate(person, err); // validate the document
if (err)
std::cerr << "Validation failed\n";
else
std::cout << "Validation succeeded\n";
}
return EXIT_SUCCESS;
}
Compliance
There is an application which can be used for testing the validator with the JSON-Schema-Test-Suite. In order to simplify the testing, the test-suite is included in the repository.
If you have cloned this repository providing a path the repository-root via the
cmake-variable JSON_SCHEMA_TEST_SUITE_PATH will enable the test-target(s).
All required tests are OK.
Format
Optionally JSON-schema-validator can validate predefined or user-defined formats. Therefore a format-checker-function can be provided by the user which is called by the validator when a format-check is required (ie. the schema contains a format-field).
This is how the prototype looks like and how it can be passed to the validation-instance:
static void my_format_checker(const std::string &format, const std::string &value)
{
if (format == "something") {
if (!check_value_for_something(value))
throw std::invalid_argument("value is not a good something");
} else
throw std::logic_error("Don't know how to validate " + format);
}
// when creating the validator
json_validator validator(nullptr, // or loader-callback
my_format_checker); // create validator
Default Checker
The library contains a default-checker, which does some checks. It needs to be provided manually to the constructor of the validator:
json_validator validator(loader, // or nullptr for no loader
nlohmann::json_schema::default_string_format_check);
Supported formats: date-time, date, time, email, hostname, ipv4, ipv6, uuid, regex
More formats can be added in src/string-format-check.cpp. Please contribute implementions for missing json schema draft formats.
Default value processing
As a result of the validation, the library returns a json patch including the default values of the specified schema.
#include <iostream>
#include <nlohmann/json-schema.hpp>
using nlohmann::json;
using nlohmann::json_schema::json_validator;
static const json rectangle_schema = R"(
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "A rectangle",
"properties": {
"width": {
"$ref": "#/definitions/length",
"default": 20
},
"height": {
"$ref": "#/definitions/length"
}
},
"definitions": {
"length": {
"type": "integer",
"minimum": 1,
"default": 10
}
}
})"_json;
int main()
{
try {
json_validator validator{rectangle_schema};
/* validate empty json -> will be expanded by the default values defined in the schema */
json rectangle = "{}"_json;
const auto default_patch = validator.validate(rectangle);
rectangle = rectangle.patch(default_patch);
std::cout << rectangle.dump() << std::endl; // {"height":10,"width":20}
} catch (const std::exception &e) {
std::cerr << "Validation of schema failed: " << e.what() << "\n";
return EXIT_FAILURE;
}
return EXIT_SUCCESS;
}
The example above will output the specified default values {"height":10,"width":20} to stdout.
Note that the default value specified in a
$refmay be overridden by the current instance location. Also note that this behavior will break draft-7, but it is compliant to newer drafts (e.g.2019-09or2020-12).