Walbottle
=========

Walbottle is a project for generating JSON unit test vectors from JSON Schemas.
It provides a library, libwalbottle, which implements JSON Schema parsing and
test vector generation.

See the test programs in libwalbottle/tests/ for simple examples of how to use
the code.

libwalbottle’s API is currently unstable and is likely to change wildly.

What is JSON Schema?
====================

 • http://json-schema.org/latest/json-schema-core.html
 • http://json-schema.org/latest/json-schema-validation.html
 • http://spacetelescope.github.io/understanding-json-schema/index.html

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
 • well-formed: the JSON is syntactically valid
 • valid: the JSON has types, structure and values which match those permitted
          by a given JSON schema

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:
 • http://json-schema.org/schema
 • http://json-schema.org/hyper-schema

What is Walbottle?
==================

Walbottle is an implementation of JSON Schema. It can:
 • validate JSON instances against a schema (the json-validate utility);
 • validate JSON Schemas against the meta-schema (the json-schema-validate
   utility); and
 • generate JSON instances from a schema (the json-schema-generate utility).

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.

Using Walbottle
===============

Walbottle can be used as a set of utility programs or as a library.

The utility programs:
 • json-validate:
     Validate one or more JSON files against zero or more JSON schemas. If no
     schemas are specified, the JSON files are checked for well-formedness only.

     Example:
       json-validate --schema my-schema.json instance1.json instance2.json

 • json-schema-validate:
     Validate a JSON schema against the JSON meta-schema. This checks the schema
     is well-formed and valid, and hence suitable for use in validating JSON
     instances.

     Example:
       json-schema-validate schema1.json schema2.json

 • json-schema-generate:
     Generate JSON instances for a given schema, either generating valid or
     invalid instances. The generated instances are designed to test boundary
     conditions of the validity of the schema, to be used for unit testing code
     which parses instances of the schema.

     Example (valid instances only):
       json-schema-generate --valid-only schema.json
     Example (invalid instances only):
       json-schema-generate --invalid-only schema.json

     An example of how to integrate json-schema-generate into an autotools
     build system and GLib-based test suite is given in the libwalbottle
     documentation.

As a library, the core object is a WblSchema, representing a single top-level
JSON schema. See the API documentation for more explanation and examples.

Dependencies
============

 • glib-2.0 ≥ 2.34.0
 • gio-2.0 ≥ 2.34.0
 • json-glib

Licensing
=========

libwalbottle is licensed under the LGPL; see COPYING.LIB for more details.

Bugs
====

Bug reports and patches should be added on gitlab:
https://gitlab.com/walbottle/walbottle/issues/new

Thank you!

Contact
=======

Philip Withnall <[email protected]>
https://gitlab.com/groups/walbottle