Argo: JSON Schema Adventures🔗ℹ

Argo is a JSON Schema validator. Work with your JSON data knowing that it adheres to some sensible constraints. If you have to work with JSON, even if only occasionally, you may want to consider validating it (that is, checking that is satisfies the constraints specified by the schema).

1 Installation🔗ℹ

To install Argo from the command line, use the raco pkg install command, like so:

After Argo has been installed, you can keep it up-to-date using raco pkg update:

2 Running Argo🔗ℹ

Argo can be executed as a command-line tool using raco. This section discusses the five available commands: validate, schema, pp, point, and equal.

2.1 validate🔗ℹ

The validate command takes a JSON Schema file and a JSON file as input and checks that the data adheres to the schema.

Run it like this:

You will see either Validation succeeded or Validation failed.

In case of validation success, seeing “Validation succeeded” is probably enough. In case of failure, “Validation failed” is, admittedly, not the most informative thing you’ve seen today. See also Error reporting.

Exit code

The validate command exits cleanly (with code 0) provided:

• exactly two arguments, schema.json and data.json, were supplied to it,

• schema.json exists and is a file,

• data.json exists and is a file,

• schema.json is well-formed JSON,

• data.json is well-formed JSON,

• schema.json is a (draft 6) JSON Schema, and

• data.json adheres to schema.json (following the draft 6 semantics).

If any of these conditions fails, the exit code will be 1.

Options

validate accepts only one option, quiet, which, if set, will cause all output to be suppressed. By default, this option is unset. In such a case, the exit code will be your only indication about the validity of your data. Here’s how you can use this option:

As discussed in the above concerning exit codes, there are seven conditions that need to be met for validate to exit cleanly. Looking at that list there, another way to think of it is that there are six preconditions that need to be met for validation to even make sense. Even if the quiet flag is set, you will see error output if any of these preconditions is not met. Thus

will cause an error message to be printed, despite the –quiet, because this isn’t even a well-formed invocation of validate (notice that the second argument is missing).

2.2 schema🔗ℹ

The schema command takes a JSON file as input and checks that it is a schema. (Recall that “schema” for Argo is “draft 06 schema”.)

Run it like this:

The output will tell you whether schema.json really is a JSON Schema.

Exit code

schema exits cleanly (with code 0) provided:

• exactly one argument, schema.json, was supplied to it,

• schema.json exists and is a file, and

• schema.json is well-formed JSON.

(Though see below for a way in which the exit code may be non-zero even if all these conditions are met.)

Options

schema accepts only one option, quiet, which, if set, will cause all output to be suppressed. By default, this option is unset. In such a case, the exit code will be your only indication about whether your JSON really is a schema.

2.3 pp🔗ℹ

The pp command takes a JSON file as input and pretty prints it to the console.

Run it like this:

Exit code

pp exits cleanly (with code 0) provided:

• exactly one argument, data.json, was supplied to it,

• data.json exists and is a file, and

• data.json is well-formed JSON.

If any of these conditions fails, the exit code will be 1.

Options

The command accepts no options.

2.4 oneline🔗ℹ

The oneline command takes a JSON file as input and renders it in a single line. It doesn’t get more compressed than this.

Exit code

The oneline command exits cleanly (with code 0) provided:

• exactly one argument, data.json, was supplied to it,

• data.json exists and is a file, and

• data.json is well-formed JSON.

If any of these conditions fails, the exit code will be 1.

Options

oneline accepts no options.

2.5 point🔗ℹ

The point command takes a JSON file and a JSON Pointer expression as input and outputs the part of the JSON file to which the expression refers.

Run it like this:

Exit code

point exits cleanly (with code 0) provided:

• exactly two arguments, data.json and expression, were supplied to it,

• data.json exists and is a file,

• data.json is well-formed JSON,

• expression is a well-formed JSON Pointer expression, and

• expression refers to something in data.json.

If any of these conditions fails, the exit code will be 1.

Options

point accepts no options.

2.6 equal🔗ℹ

The equal command takes a two JSON files as input and checks that they represent identical JSON content.

Run it like this:

Depending on whether the contents of json-1.json and json-2.json are the same content, you will see either JSON files are equal or JSON files are not equal.

See the documentation for json-equal? to see the definition of what it means for two JSON documents to be equal.

Exit code

equal with arguments exits cleanly (with code 0) provided:

• exactly two arguments, json-1.json and json-2.json, were supplied to it,

• json-1.json exists and is a file,

• json-2.json exists and is a file,

• json-1.json is well-formed JSON, and

• json-2.json is well-formed JSON.

If any of these conditions fails, the exit code will be 1.

If the quiet flag is used, the exit code will be 1 if the two inputs are represent different JSON documents. If the quiet flag is not used, the exit code will always be 0 (provided, of course, that all of the above conditions are met).

Options

equal accepts only one option, quiet, which, if set, will cause all output to be suppressed. By default, this option is unset. In such a case, the exit code will be your only indication about the equality of your data.

3 Library interface🔗ℹ

Returns two values. The first a jsexpr? representing the parsed content of jsonish. The second indicates whether the result could be parsed as JSON at all. #f means that the argument represents invalid JSON; in that case, it doesn’t matter what the first return value is.

“JSON Schema” for Argo means “draft 6 JSON Schema”, which was the current version of the JSON Schema specification when Argo was conceived. If you’ve worked with JSON Schema over the years, chances are good you’ve become accustomed to draft 4 schemas. They’re largely the same, and for many users, they may be indistinguishable; but they’re not identical. This means that what passed for a schema in the halcyon days of 2016 may not be a schema in Argo’s eyes. (And vice versa: Argo may accept as a schema something that would be rejected according to the draft 4 rules.)

The meatiest function of Argo is adheres-to-schema?.

Equality of two JSON documents doc-1 and doc-2 is defined as follows: doc-1 and doc-2 have the same type (both are JSON objects, both are JSON strings, etc.) and adhere to the type-specific rules for equality, which are:

• two strings are equal is they are equal as Unicode strings (codepoint-for-codepoint equal sequences)

• two null values are equal unconditionally

• two number values are equal if they are mathematically equal representations of numbers in decimal notation

• two objects are equal if they have precisely the same keys (which are JSON strings) and, for each key, their corresponding values are equal, and

• two arrays are equal if they have the same length and if, for each index, the value of the first array, at that index, is equal to the value at that index of the second array, at that index.

If expr is a malformed JSON Pointer expression, or refers to nothing in data, an exception will be raised.

4 Technical information🔗ℹ

4.1 Semantic validation🔗ℹ

Argo supports all the semantic validation keywords:

• date-time (RFC 3399)

• email (RFC 5322)

• hostname (RFC 1034)

• ipv4 (RFC 2673)

• ipv6 (RFC 2373)

• uri (RFC 3986)

• uri-reference (ditto)

• uri-template (RFC 6570), and

• json-pointer (RFC 6901)

4.2 JSON Schema versions🔗ℹ

JSON Schema is a moving target. Thankfully, the target moves slowly. But it does move. What does that mean for you? To put it bluntly: a JSON document that’s valid today may not be valid tomorrow.

Argo implements JSON Schema version 6 (codename “draft-wright-json-schema-validation-01”). The official homepage for specification that Argo follows is here. That version was released on April 21, 2017. If you’ve been working with JSON Schema for a few years, chances are good that you’ve worked with version 4. The two versions are largely the same, but there are some minor differences. Unfortunately, what counts as a “minor difference” is in the eyes of the beholder. While testing Argo I found several schemas on the web, written in the heyday of version 4—including some on the JSON Schema homepage—that no longer produced the expected results when interpreted as version 6 schemas. They had to be updated. It may very well be possible that you’ll need to update your JSON Schemas, too.

5 Shortcomings and sorely missing features🔗ℹ

Argo suffers from some known deficiencies.

5.1 Hypermedia keywords unsupported🔗ℹ

JSON Schema defines Hypermedia keywords (base, links, and media) are currently not supported. When these properties are encountered on a JSON schema, they are silently ignored. If you work with JSON schema that rely on these features, it will almost certainly not work with Argo. (Meanining: validation will produce many false negatives and maybe even some false positives.)

5.2 Error reporting🔗ℹ

Error reporting is largely (or should I say, entirely) missing. Thus, if a JSON document is not valid according to a JSON schema, you just get #f. You don’t get a description of why the document fails validation.

5.3 Only version 6 of the JSON Schema specification is supported🔗ℹ

Only verson 6 of the JSON Schema specification is supported. Schema that declare themselves to be, say, a v4 JSON Schema may not be treated correctly (that is, according to the v4 rules).

If you can, either leave out the $schema keyword or use the value http://json-schema.org/draft-06/schema# for $schema.

6 Further reading🔗ℹ

To learn more about JSON Schema, go to the source: http://json-schema.org. The specificiations that Argo aims to follow are in two documents:

• JSON Schema Core

• JSON Schema Validation

(The third part of the JSON Schema specification that is currently not implemented by Argo is JSON Hyper-Schema.)

Finally, you’re welcome to visit the Argo homepage to read about updates and other JSON Schema goodies.