moonschema JSON Schema · MoonBit

Six versions, one walk

Every document,
thread by thread.

moonschema validates a JSON instance against a JSON Schema. You hand it a Json tree; it answers yes or no, and when the answer is no it says where — in the instance, and in the schema. Six versions of the specification, four output formats, and no sockets.

$ moon add moonbitstack/moonschema
Try the loom → Read the guide

In the browser, on the real engine

The loom

A schema on the left, an instance on the right. Edit either: the package compiled to JavaScript validates as you type, and prints every reason it had.

engine
warpschema.json
weftinstance.json
checking…

    6 versions draft-04 through v1, one walk over the keywords.
    4 output formats flag, basic, detailed and verbose — the same walk, read four ways.
    0 sockets A reference reaches the documents you hand over, and nothing else.
    19 format names date-time, email, ipv4, uri, uuid and the rest, each against its RFC.

    What it holds to

    What it does, and what it refuses

    The specification is large and most of it is small print. These are the parts that decide whether a validator is useful or merely present.

    $schema The document decides

    A document is read at the version it names, whatever the argument says. The argument is the fallback for a document that names nothing — never an override of one that does.

    Fault Two places, not one

    A fault names the place in the instance and the keyword that refused it, so a message can point at both. at is a JSON Pointer; so is schema_at.

    remotes No sockets

    A validator should not fetch. A $ref reaches a map of documents you fill in; what is not handed over does not resolve, and that is a fault, not a pass.

    unevaluated* Annotations carry

    What an applicator evaluated is passed to its neighbours, so unevaluatedProperties sees the branches of an allOf — which is the only way to close a composed object.

    pattern ECMA-262, not POSIX

    \d, \w, \s and \p{Letter} work as the specification writes them, read by moonregex's ECMA-262 dialect with the u flag; scripts and binary properties too, from Unicode 17.0.

    Refused Refuse, don't guess

    A $schema naming a version this does not know is refused when the schema is read — not read at a version of someone else's choosing.

    format Nineteen names, each an RFC

    date-time and its leap second, email down to a quoted local part, idn-hostname through the tables of RFC 5892, uri by component. An assertion when you ask for one, and by default from v1.

    report Four formats, one walk

    flag, basic, detailed, verbose. Each unit carries the evaluation path that went through $ref and the schema location that did not.

    Keyword Your own vocabulary

    A pub(open) trait for a keyword and one for a vocabulary: a document that names yours in $vocabulary gets it, and the library is not changed to allow it.

    The six

    Versions, and why each is here

    Six versions are in use, so six are here. The value on the left is the enum; the URI is what a document writes in $schema.

    Draft$schemaWhat it is
    Draft4 json-schema.org/draft-04/schema# What OpenAPI 3.0 profiles, and what much Java and Python tooling still emits.
    Draft6 json-schema.org/draft-06/schema# $id replaces id; exclusiveMinimum becomes a number.
    Draft7 json-schema.org/draft-07/schema# The most widely deployed version.
    Draft2019 json-schema.org/draft/2019-09/schema Vocabularies, $defs, $recursiveRef, unevaluatedProperties.
    Draft2020 json-schema.org/draft/2020-12/schema $dynamicRef, prefixItems — and what OpenAPI 3.1 is.
    V1 json-schema.org/v1 format asserts, propertyDependencies arrives.

    Both http and https spellings are accepted, with or without the trailing #.

    Where the cloth ends

    What it will not do

    Four decisions, each with a reason, so that nobody has to discover them by finding the hole.

    no Fetch a remote $ref

    A validator that opens sockets is a validator that blocks, retries and fails. The seam is remotes: a map from URI to document, filled by the caller.

    no Validate a schema against its metaschema

    A schema is read for what it says, not checked for whether it should have said it. $schema picks the version; the rest is the schema author's business.

    no Hyper-schema

    Links and media types are a different specification. This one is validation.

    no Compile schemas to code

    Interpretation first. If it measures slow, that is the time to argue about it — not before there is a number.

    Runnable

    Programs to read

    Each is a small program with its real output, and runs with moon run src/examples/….

    01tour a schema, three instances, the faults they earn 02versions one document read at each of the six 03references $defs, $id, $anchor, and a document handed in 04composition allOf, oneOf, if/then/else, unevaluated 05formats one failure in all four output formats 06vocabularies a keyword from outside, put in force by a metaschema 07web the engine this page runs