Walbottle: a JSON schema parser and validator

Walbottle is a library and set of utilities for parsing JSON schemas and using them to validate JSON documents and other schemas. It also supports generation of unit tests for JSON document parsers, using the document’s schema to generate the tests.

Walbottle is licenced under the LGPLv2.1+.

What is JSON Schema?

JSON Schema is a way of specifying the permitted format of JSON documents (‘instances’). It is entirely analogous to XML schema formats such as XML Schema or RELAX NG.

JSON instances can be

Validation of a JSON instance against a schema checks both of these properties. A JSON instance can be valid against one JSON schema but invalid against another.

JSON ‘meta-schemas’ are JSON schemas which define the JSON Schema specification itself. i.e. They define the types, structure and values which are permitted in a JSON Schema document. JSON meta-schemas are themselves JSON schemas. There are two meta-schemas: the meta-schema and the hyper-meta-schema. The hyper-meta-schema is a superset of the meta-schema, defining some additional hypertext properties which can be used in schemas.

The meta-schemas are here:

What is Walbottle?

Walbottle is an implementation of JSON Schema. It can:

The final use case is the most important: Walbottle mainly exists in order to generate ‘random JSON’ instances for use in testing parsers. If you have written a JSON parser, and the format it parses is described by a JSON Schema document (if it isn’t, write a schema now), then json-schema-generate can be used to generate a number of JSON instances which you can use as test vectors for your parser. Each JSON instance is annotated with whether it’s valid according to the schema.

The typical way to use these is to feed each one into your parser, and check that the parser accepts it if, and only if, it’s a valid instance according to the schema. And also check that the parser doesn’t crash or leak or do other bad things.

Download and installation

Tarballs for released versions of Walbottle are below. All have been signed with key 4B2EAFA0 (Philip Withnall).

Compilation follows the standard automake process:

tar -xJf ./walbottle-$VERSION.tar.xz
cd ./walbottle-$VERSION
./configure --prefix=$PREFIX
make
make install

Source code and bugs

Git repository

The source code for Walbottle is stored in git, which can be viewed online or cloned:

git clone https://github.com/pwithnall/walbottle.git

Bugs

Walbottle uses Bugs Everywhere for feature enhancement tracking, so to view all currently open bugs, clone the Walbottle git repository and run:

be list

To file a bug, please contact the authors by e-mail.

Contact

Walbottle is written by Philip Withnall, as part of R&D work by Collabora.

If you have any bug reports, questions, suggestions or criticism of the project, please e-mail me (philip tecnocode co uk).