-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
129 lines (96 loc) · 4.53 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
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 <philip@tecnocode.co.uk>
https://gitlab.com/groups/walbottle