The JSON validator is a web application that validates JSON and YAML content against JSON Schema (Core Draft v4, v6, v7, v2019-09 and v2020-12). Its core is fully reusable: configuration alone determines the supported specifications, the validation types and other customisations. You can validate content through:
- A web form, for validation through the user interface.
- A REST API, for machine-to-machine integrations.
- A SOAP API, for contract-based machine-to-machine integrations.
The SOAP API conforms to the GITB validation service API. This lets you use the validator in GITB Test Description Language (TDL) conformance test cases, as a verify step handler. You can also build the validator as a command-line tool (an executable JAR) with pre-packaged or provided configuration.
This validator is maintained by the European Commission's DIGIT and specifically the Interoperability Test Bed, a conformance testing service for projects involved in the delivery of cross-border public services. Learn more on the Interoperability Test Bed page.
With Docker installed, run:
docker run -p 8080:8080 isaitb/json-validatorThen open http://localhost:8080/json/any/upload, upload a JSON or YAML file and its JSON Schema, and validate. The
generic any domain you see here has no built-in validation artefacts, so you provide your own schema.
To validate against your own preconfigured schemas, see Configuration.
The validator is a generic core that you configure to validate any supported specification. Configuration is organised in domains: logically separate setups served by the same application instance. Each domain defines:
- The validation types it offers and their options.
- The validation artefacts needed for validation, which can be local, remote or user-provided.
A domain's configuration lives in a folder containing a configuration property file and any other resources it needs.
The Test Bed's JSON validation guide documents setup and configuration as a step-by-step tutorial.
If you don't plan to modify the validator's source, use the Test Bed's packages:
- Docker: the isaitb/json-validator image on Docker Hub.
- JAR file: the generic web application package. This is the same executable JAR you get when building from this repository. See the installation guide for how to run and configure it.
- Command-line tool: the generic command-line package. This is built from the
jsonvalidator-jarmodule, with an extra post-processing step to configure the domain(s).
Once the web application is running, it is available at:
| Channel | URL |
|---|---|
| Web form | http://localhost:8080/json/DOMAIN/upload |
| REST API | http://localhost:8080/json/DOMAIN/api/validate (Swagger docs: http://localhost:8080/json/swagger-ui/index.html) |
| SOAP API | http://localhost:8080/json/soap/DOMAIN/validation?wsdl |
DOMAIN is the name of a domain's configuration folder under your validator.resourceRoot. You can change it by
providing validator.domainName.DOMAIN mapping(s). These are application-level configuration properties
that you can set in the default application.properties,
or through environment variables and system properties.
To run the validator you need a few basic properties. Set them as environment variables or system properties (see the full list of configuration properties):
| Property | Purpose |
|---|---|
validator.resourceRoot |
The root folder from which all domain configurations are loaded. |
logging.file.path |
The validator's log output folder. |
validator.tmpFolder |
The validator's temporary work folder. |
Within validator.resourceRoot, add a folder for each domain, with its configuration property file and any other
resources. The JSON validation guide's configuration step
includes a simple example you can download and reuse.
If you don't load any configuration, the validator falls back to a generic configuration with a single domain called
any. It has no validation artefacts, so you upload your own schemas through the UI and APIs. Open it like any other
domain, at http://localhost:8080/json/any/upload.
To build your own image, use the sample Dockerfile as a starting point:
- Create a folder and copy into it the Dockerfile and the JAR produced by the
jsonvalidator-warmodule. - (Optional) Create a sub-folder (for example
resources) as your resource root, and place your domain configuration folder(s) in it. - (Optional) Adapt the Dockerfile to copy the
resourcesfolder and set it as thevalidator.resourceRoot:
COPY resources /validator/resources/
ENV validator.resourceRoot=/validator/resources/If you skip steps 2 and 3, only the generic validator is available, under the any domain.
The validator is a multi-module Maven project. The artefact to use is the all-in-one Spring Boot web application
produced by the jsonvalidator-war module.
- A JDK installation (17+).
- Maven (3+).
- The itb-commons libraries, installed in your local Maven repository.
All dependencies are on public repositories except the itb-commons libraries, which are shared by all Test Bed validators and are not published publicly. Install them first:
git clone https://github.com/ISAITB/itb-commons.git
cd itb-commons
mvn install -DskipTests=truegit clone https://github.com/ISAITB/json-validator.git
cd json-validator
mvn clean installThe web application is jsonvalidator-war/target/validator.jar. Run it with the basic properties, for example:
java -Dvalidator.resourceRoot=/path/to/resources \
-Dlogging.file.path=/path/to/logs \
-Dvalidator.tmpFolder=/path/to/tmp \
-jar jsonvalidator-war/target/validator.jarThe JSON validator supports custom plugins that extend the validation report. Plugins are implementations of the GITB validation service API and must be built as "all-in-one" JARs.
The validator calls plugins in sequence, passing the following input:
| Input name | Type | Description |
|---|---|---|
contentToValidate |
String |
The absolute and full path to the input provided to the validator. |
domain |
String |
The validation domain relevant to the specific validation call. |
validationType |
String |
The validation type of the domain that is selected for the specific validation call. |
tempFolder |
String |
The absolute and full path to a temporary folder for plugins. This will be automatically deleted after all plugins complete validation. |
locale |
String |
The locale (language code) to use for reporting of results (e.g. "fr", "fr_FR"). |
locationAsPointer |
Boolean |
Whether report item locations should be JSON pointers or not. |
yaml |
Boolean |
Whether content should be treated as YAML (false - the default - meaning JSON). |
A plugin's output is a GITB ValidationResponse that wraps a TAR instance. The report items in this TAR are merged
with the reports produced by JSON Schema validation.
Plugin configuration is part of a validator's domain configuration.
Once your plugins are implemented, configure them with the validator.defaultPlugins and validator.plugins properties,
listing for each plugin:
- The path to its JAR file.
- The fully qualified class name of its entry point.
To report a security vulnerability, please follow this repository's security policy.
To support transparency and the security monitoring needs of downstream users, signed Software Bill of Materials (SBOM) and Vulnerability Disclosure Report (VDR) documents in CycloneDX format are published for every release of the JSON validator in the release-reports repository:
- The reports of the JSON validator.
- An overview of the vulnerability status of all releases.
- A mirror of the reports for automated integrations, with a machine-readable index, at https://www.itb.ec.europa.eu/release-reports/reports/index.json.
The best way to contribute is to share your feedback, questions and suggestions by opening an issue in this repository. For more elaborate contributions, and for more information, see CONTRIBUTING.md.
This software is shared using the European Union Public Licence (EUPL) version 1.2.
Third-party library licences and attributions are listed in NOTICE.md.
The authors of this software waive any and all liability linked to its usage or the interpretation of results it produces.
For feedback or questions about this validator, please post an issue in this repository. You can also contact the Test Bed team by email at DIGIT-ITB@ec.europa.eu.
The Test Bed provides similar validators for other content types. Check these out for more information:
- The RDF validator: see overview, source, detailed guide and Docker Hub image.
- The XML validator: see overview, source, detailed guide and Docker Hub image.
- The CSV validator: see overview, source, detailed guide and Docker Hub image.