diff --git a/README.md b/README.md index 5d50806..0b84f1d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # JSON schema validator for JSON for Modern C++ -# What is it? +## What is it? This is a C++ library for validating JSON documents based on a [JSON Schema](http://json-schema.org/) which itself should validate with @@ -16,7 +16,7 @@ library, hence the name. External documentation is missing as well. However the API of the validator is rather simple. -# New in version 2 +## New in version 2 Although significant changes have been done for the 2nd version (a complete rewrite) the API is compatible with the 1.0.0 release. Except for @@ -31,7 +31,7 @@ is parsed into compiled C++ objects which are then used during validation. There still optimizations to be done, but validation speed has improved by factor 100 or more. -# Design goals +## Design goals The main goal of this validator is to produce *human-comprehensible* error messages if a JSON-document/instance does not comply to its schema. @@ -46,7 +46,7 @@ a validation error occurs and decide what to do (throwing, counting, collecting) Another goal was to use Niels Lohmann's JSON-library. This is why the validator lives in his namespace. -# Thread-safety +## Thread-safety Instance validation is thread-safe and the same validator-object can be used by different threads: @@ -61,13 +61,13 @@ being called: Validator-object creation however is not thread-safe. A validator has to be created in one (main?) thread once. -# Weaknesses +## Weaknesses Numerical validation uses nlohmann-json's integer, unsigned and floating point types, depending on if the schema type is "integer" or "number". Bignum (i.e. arbitrary precision and range) is not supported at this time. -# Building +## Building This library is based on Niels Lohmann's JSON-library and thus has a build-dependency to it. @@ -77,7 +77,7 @@ is required. Various methods using CMake can be used to build this project. -## Build out-of-source +### Build out-of-source Do not run cmake inside the source-dir. Rather create a dedicated build-dir: @@ -92,7 +92,7 @@ make install # if needed ctest # run unit, non-regression and test-suite tests ``` -## Building as shared library +### Building as shared library By default a static library is built. Shared libraries can be generated by using the `BUILD_SHARED_LIBS`-cmake variable: @@ -103,14 +103,14 @@ In your initial call to cmake simply add: cmake [..] -DBUILD_SHARED_LIBS=ON [..] ``` -## nlohmann-json integration +### 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 +#### 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 @@ -118,14 +118,14 @@ To enable access to nlohmann json library, Hunter can be used. Just run with `JS cmake [..] -DJSON_VALIDATOR_HUNTER=ON [..] ``` -### Building as a CMake-subdirectory from within another project +#### 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) +#### 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. @@ -133,7 +133,7 @@ CMake's `find_package()` to be used. This library is using this mechanism if `nlohmann_json::nlohmann_json`-target does not exist. -### Install +#### 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 @@ -152,7 +152,7 @@ target_link_libraries( [..] nlohmann_json_schema_validator) to build and link. -## Code +### Code See also `app/json-schema-validate.cpp`. @@ -250,7 +250,7 @@ int main() } ``` -# Compliance +## Compliance There is an application which can be used for testing the validator with the [JSON-Schema-Test-Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite). @@ -261,7 +261,7 @@ cmake-variable `JSON_SCHEMA_TEST_SUITE_PATH` will enable the test-target(s). All required tests are **OK**. -# Format +## 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 @@ -285,7 +285,7 @@ json_validator validator(nullptr, // or loader-callback my_format_checker); // create validator ``` -## Default Checker +### Default Checker The library contains a default-checker, which does some checks. It needs to be provided manually to the constructor of the validator: @@ -299,7 +299,7 @@ Supported formats: `date-time, date, time, email, hostname, ipv4, ipv6, uuid, re More formats can be added in `src/string-format-check.cpp`. Please contribute implementions for missing json schema draft formats. -## Default value processing +### Default value processing As a result of the validation, the library returns a json patch including the default values of the specified schema. @@ -353,7 +353,7 @@ The example above will output the specified default values `{"height":10,"width" > Note that the default value specified in a `$ref` may 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-09` or `2020-12`). -# Contributing +## Contributing This project uses [`pre-commit`](https://pre-commit.com/) to enforce style-checks. Please install and run it before creating commits and making pull requests.