JSON Schema formats, vocabularies and validators

Python · vocab/minischema.py

"""The keywords of JSON Schema 2020-12 by vocabulary, format checked as an annotation or as an assertion, a check
that a validator supports a dialect's vocabularies, and a finder for keywords that no vocabulary defines."""

import json
import re

V = "https://json-schema.org/draft/2020-12/vocab/"
KEYWORDS = {  # the vocabularies of the 2020-12 dialect and the keywords each one defines
    V + "core": "$id $schema $ref $anchor $dynamicRef $dynamicAnchor $vocabulary $comment $defs",
    V + "applicator": "allOf anyOf oneOf not if then else dependentSchemas prefixItems items contains "
                      "properties patternProperties additionalProperties propertyNames",
    V + "unevaluated": "unevaluatedItems unevaluatedProperties",
    V + "validation": "type enum const multipleOf maximum exclusiveMaximum minimum exclusiveMinimum maxLength "
                      "minLength pattern maxItems minItems uniqueItems maxContains minContains maxProperties "
                      "minProperties required dependentRequired",
    V + "meta-data": "title description default deprecated readOnly writeOnly examples",
    V + "format-annotation": "format",
    V + "content": "contentEncoding contentMediaType contentSchema",
}
KNOWN = {k for words in KEYWORDS.values() for k in words.split()}
MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]


def date_time(text):
    """RFC 3339 section 5.6 date-time, with the day checked against its month and year."""
    m = re.fullmatch(r"([0-9]{4})-([0-9]{2})-([0-9]{2})[Tt]([0-9]{2}):([0-9]{2}):([0-9]{2})(\.[0-9]+)?"
                     r"([Zz]|[+-][0-9]{2}:[0-9]{2})", text)
    if not m:
        return False
    year, month, day, hour, minute, second = (int(g) for g in m.groups()[:6])
    leap = year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)
    days = 29 if month == 2 and leap else MONTH_DAYS[month - 1] if 1 <= month <= 12 else 0
    return 1 <= day <= days and hour <= 23 and minute <= 59 and second <= 60


OCTET = "(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])"  # 0 to 255, without leading zeros
ATEXT = "[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+"
LABEL = "[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?"
HEX = "[0-9a-fA-F]"
FORMATS = {  # each is a full match; email is RFC 5321's Mailbox without quoted local parts and address literals
    "email": lambda s: re.fullmatch(rf"{ATEXT}(\.{ATEXT})*@{LABEL}(\.{LABEL})*", s) is not None,
    "date-time": date_time,
    "ipv4": lambda s: re.fullmatch(rf"{OCTET}(\.{OCTET}){{3}}", s) is not None,
    "uuid": lambda s: re.fullmatch(rf"{HEX}{{8}}(-{HEX}{{4}}){{3}}-{HEX}{{12}}", s) is not None,
}


def kind(value):
    if value is None:
        return "null"
    if isinstance(value, bool):
        return "boolean"
    if isinstance(value, (int, float)):
        return "number"
    if isinstance(value, str):
        return "string"
    return "array" if isinstance(value, list) else "object"


def has_type(value, name):
    if name == "integer":
        return kind(value) == "number" and (isinstance(value, int) or value.is_integer())
    return kind(value) == name


def step(pointer, token):
    return pointer + "/" + str(token).replace("~", "~0").replace("/", "~1")


def validate(schema, value, assert_formats=False, at=""):
    """(errors, annotations). format is collected as an annotation, and checked only when assert_formats is on."""
    errors, notes = [], []
    for keyword, rule in schema.items():
        if keyword == "type" and not has_type(value, rule):
            errors.append((at, f"expected {rule}, got {kind(value)}"))
        elif keyword == "format" and kind(value) == "string":
            notes.append((at, f"format {rule}"))
            known = rule in FORMATS
            if assert_formats and (not known or not FORMATS[rule](value)):
                errors.append((at, f"{json.dumps(value)} is not a valid {rule}" if known else f"unknown format {rule}"))
        elif keyword == "required" and kind(value) == "object":
            errors += [(at, f"missing required property {json.dumps(n)}") for n in rule if n not in value]
        elif keyword == "minLength" and kind(value) == "string" and len(value) < rule:
            errors.append((at, f"{json.dumps(value)} is shorter than {rule}"))
        elif keyword == "minimum" and kind(value) == "number" and value < rule:
            errors.append((at, f"{value} is below the minimum of {rule}"))
        elif keyword == "additionalProperties" and rule is False and kind(value) == "object":
            errors += [(step(at, n), f"property {json.dumps(n)} is not allowed") for n in value if n not in schema.get("properties", {})]
        elif keyword == "properties" and kind(value) == "object":
            for name, sub in rule.items():
                if name in value:
                    found = validate(sub, value[name], assert_formats, step(at, name))
                    errors, notes = errors + found[0], notes + found[1]
    return errors, notes


def can_process(vocabularies, supported):
    """None when a validator that supports these vocabularies may process the dialect, else the reason it must refuse."""
    missing = [uri for uri, required in vocabularies.items() if required and uri not in supported]
    return f"it requires {', '.join(missing)}" if missing else None


def distance(a, b):
    """Levenshtein distance: the fewest single-character edits that turn a into b."""
    row = list(range(len(b) + 1))
    for i, ca in enumerate(a, 1):
        prev, row[0] = row[0], i
        for j, cb in enumerate(b, 1):
            prev, row[j] = row[j], min(row[j] + 1, row[j - 1] + 1, prev + (ca != cb))
    return row[-1]


MAPS = ("properties", "patternProperties", "$defs", "dependentSchemas")
LISTS = ("allOf", "anyOf", "oneOf", "prefixItems")
SINGLE = ("items", "contains", "not", "if", "then", "else", "additionalProperties", "propertyNames",
          "unevaluatedItems", "unevaluatedProperties", "contentSchema")


def unknown_keywords(schema, where=""):
    """(location, the closest keyword or None) for every name in a schema that no vocabulary defines."""
    found = []
    if not isinstance(schema, dict):
        return found
    for name, value in schema.items():
        here = step(where, name)
        if name not in KNOWN and not name.startswith("x-"):
            close = min(sorted(KNOWN), key=lambda k: distance(name, k))
            found.append((here, close if distance(name, close) <= 2 else None))
        elif name in MAPS:
            for key, sub in value.items():
                found += unknown_keywords(sub, step(here, key))
        elif name in LISTS:
            for i, sub in enumerate(value):
                found += unknown_keywords(sub, step(here, i))
        elif name in SINGLE:
            found += unknown_keywords(value, here)
    return found

JavaScript · vocab/minischema.mjs

// The keywords of JSON Schema 2020-12 by vocabulary, format checked as an annotation or as an assertion, a check
// that a validator supports a dialect's vocabularies, and a finder for keywords that no vocabulary defines.

const V = 'https://json-schema.org/draft/2020-12/vocab/';
export const KEYWORDS = { // the vocabularies of the 2020-12 dialect and the keywords each one defines
  [`${V}core`]: '$id $schema $ref $anchor $dynamicRef $dynamicAnchor $vocabulary $comment $defs',
  [`${V}applicator`]: 'allOf anyOf oneOf not if then else dependentSchemas prefixItems items contains ' +
    'properties patternProperties additionalProperties propertyNames',
  [`${V}unevaluated`]: 'unevaluatedItems unevaluatedProperties',
  [`${V}validation`]: 'type enum const multipleOf maximum exclusiveMaximum minimum exclusiveMinimum maxLength ' +
    'minLength pattern maxItems minItems uniqueItems maxContains minContains maxProperties ' +
    'minProperties required dependentRequired',
  [`${V}meta-data`]: 'title description default deprecated readOnly writeOnly examples',
  [`${V}format-annotation`]: 'format',
  [`${V}content`]: 'contentEncoding contentMediaType contentSchema',
};
export const KNOWN = new Set(Object.values(KEYWORDS).flatMap((words) => words.split(' ')));
const MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];

// RFC 3339 section 5.6 date-time, with the day checked against its month and year.
function dateTime(text) {
  const m = /^([0-9]{4})-([0-9]{2})-([0-9]{2})[Tt]([0-9]{2}):([0-9]{2}):([0-9]{2})(\.[0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$/.exec(text);
  if (!m) return false;
  const [year, month, day, hour, minute, second] = m.slice(1, 7).map(Number);
  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
  const days = month === 2 && leap ? 29 : month >= 1 && month <= 12 ? MONTH_DAYS[month - 1] : 0;
  return day >= 1 && day <= days && hour <= 23 && minute <= 59 && second <= 60;
}

const OCTET = '(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])'; // 0 to 255, without leading zeros
const ATEXT = "[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+";
const LABEL = '[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?';
const HEX = '[0-9a-fA-F]';
const full = (pattern) => (s) => new RegExp(`^(?:${pattern})$`).test(s);
export const FORMATS = { // each is a full match; email is RFC 5321's Mailbox without quoted local parts and address literals
  email: full(`${ATEXT}(\\.${ATEXT})*@${LABEL}(\\.${LABEL})*`),
  'date-time': dateTime,
  ipv4: full(`${OCTET}(\\.${OCTET}){3}`),
  uuid: full(`${HEX}{8}(-${HEX}{4}){3}-${HEX}{12}`),
};

export function kind(value) {
  if (value === null) return 'null';
  if (Array.isArray(value)) return 'array';
  return typeof value === 'object' ? 'object' : typeof value;
}

const hasType = (value, name) => (name === 'integer' ? kind(value) === 'number' && Number.isInteger(value) : kind(value) === name);
export const step = (pointer, token) => `${pointer}/${String(token).replaceAll('~', '~0').replaceAll('/', '~1')}`;

// [errors, annotations]. format is collected as an annotation, and checked only when assertFormats is on.
export function validate(schema, value, assertFormats = false, at = '') {
  let errors = [];
  let notes = [];
  for (const [keyword, rule] of Object.entries(schema)) {
    if (keyword === 'type' && !hasType(value, rule)) {
      errors.push([at, `expected ${rule}, got ${kind(value)}`]);
    } else if (keyword === 'format' && kind(value) === 'string') {
      notes.push([at, `format ${rule}`]);
      const known = Object.hasOwn(FORMATS, rule);
      if (assertFormats && (!known || !FORMATS[rule](value))) errors.push([at, known ? `${JSON.stringify(value)} is not a valid ${rule}` : `unknown format ${rule}`]);
    } else if (keyword === 'required' && kind(value) === 'object') {
      errors.push(...rule.filter((n) => !Object.hasOwn(value, n)).map((n) => [at, `missing required property ${JSON.stringify(n)}`]));
    } else if (keyword === 'minLength' && kind(value) === 'string' && [...value].length < rule) {
      errors.push([at, `${JSON.stringify(value)} is shorter than ${rule}`]);
    } else if (keyword === 'minimum' && kind(value) === 'number' && value < rule) {
      errors.push([at, `${value} is below the minimum of ${rule}`]);
    } else if (keyword === 'additionalProperties' && rule === false && kind(value) === 'object') {
      const named = schema.properties ?? {};
      errors.push(...Object.keys(value).filter((n) => !Object.hasOwn(named, n)).map((n) => [step(at, n), `property ${JSON.stringify(n)} is not allowed`]));
    } else if (keyword === 'properties' && kind(value) === 'object') {
      for (const [name, sub] of Object.entries(rule)) {
        if (Object.hasOwn(value, name)) {
          const [e, n] = validate(sub, value[name], assertFormats, step(at, name));
          errors = [...errors, ...e];
          notes = [...notes, ...n];
        }
      }
    }
  }
  return [errors, notes];
}

// null when a validator that supports these vocabularies may process the dialect, else the reason it must refuse.
export function canProcess(vocabularies, supported) {
  const missing = Object.entries(vocabularies).filter(([uri, required]) => required && !supported.has(uri)).map(([uri]) => uri);
  return missing.length ? `it requires ${missing.join(', ')}` : null;
}

// Levenshtein distance: the fewest single-character edits that turn a into b.
export function distance(a, b) {
  const row = Array.from({ length: b.length + 1 }, (_, j) => j);
  for (let i = 1; i <= a.length; i++) {
    let prev = row[0];
    row[0] = i;
    for (let j = 1; j <= b.length; j++) {
      const old = row[j];
      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] !== b[j - 1] ? 1 : 0));
      prev = old;
    }
  }
  return row[b.length];
}

const MAPS = ['properties', 'patternProperties', '$defs', 'dependentSchemas'];
const LISTS = ['allOf', 'anyOf', 'oneOf', 'prefixItems'];
const SINGLE = ['items', 'contains', 'not', 'if', 'then', 'else', 'additionalProperties', 'propertyNames',
  'unevaluatedItems', 'unevaluatedProperties', 'contentSchema'];
const SORTED = [...KNOWN].sort();

// [location, the closest keyword or null] for every name in a schema that no vocabulary defines.
export function unknownKeywords(schema, where = '') {
  const found = [];
  if (kind(schema) !== 'object') return found;
  for (const [name, value] of Object.entries(schema)) {
    const here = step(where, name);
    if (!KNOWN.has(name) && !name.startsWith('x-')) {
      let close = SORTED[0];
      for (const k of SORTED) if (distance(name, k) < distance(name, close)) close = k;
      found.push([here, distance(name, close) <= 2 ? close : null]);
    } else if (MAPS.includes(name)) {
      for (const [key, sub] of Object.entries(value)) found.push(...unknownKeywords(sub, step(here, key)));
    } else if (LISTS.includes(name)) {
      value.forEach((sub, i) => found.push(...unknownKeywords(sub, step(here, i))));
    } else if (SINGLE.includes(name)) {
      found.push(...unknownKeywords(value, here));
    }
  }
  return found;
}

Python · vocab/formats.py

"""Four formats checked on their own, then one schema with format as an annotation and with formats asserted."""

import json

from minischema import FORMATS, validate

SAMPLES = {
    "email": ["asha@example.com", "not-an-email"],
    "date-time": ["2025-03-14T10:30:00+05:30", "2025-03-14 10:30", "2025-02-29T10:30:00Z"],
    "ipv4": ["192.168.1.30", "192.168.1.300"],
    "uuid": ["a3bb189e-8bf9-3888-9912-ace4e6543002", "a3bb189e8bf938889912ace4e6543002"],
}
for name, values in SAMPLES.items():
    for value in values:
        print(f"{name} {json.dumps(value)}: {'fits' if FORMATS[name](value) else 'does not fit'}")

SCHEMA = json.loads("""{"type": "object", "required": ["email"], "properties": {
  "email": {"type": "string", "format": "email"},
  "placed": {"type": "string", "format": "date-time"},
  "phone": {"type": "string", "format": "phone"}}}""")
order = {"email": "not-an-email", "placed": "2025-03-14 10:30", "phone": "98450 12345"}
print()
for asserted in (False, True):
    errors, notes = validate(SCHEMA, order, assert_formats=asserted)
    print(f"formats {'asserted' if asserted else 'as annotations'}: {'valid' if not errors else f'{len(errors)} errors'}")
    for at, message in errors:
        print(f"  error at {at}: {message}")
    if not asserted:
        for at, message in notes:
            print(f"  annotation at {at}: {message}")

email "asha@example.com": fits
email "not-an-email": does not fit
date-time "2025-03-14T10:30:00+05:30": fits
date-time "2025-03-14 10:30": does not fit
date-time "2025-02-29T10:30:00Z": does not fit
ipv4 "192.168.1.30": fits
ipv4 "192.168.1.300": does not fit
uuid "a3bb189e-8bf9-3888-9912-ace4e6543002": fits
uuid "a3bb189e8bf938889912ace4e6543002": does not fit

formats as annotations: valid
  annotation at /email: format email
  annotation at /placed: format date-time
  annotation at /phone: format phone
formats asserted: 3 errors
  error at /email: "not-an-email" is not a valid email
  error at /placed: "2025-03-14 10:30" is not a valid date-time
  error at /phone: unknown format phone

JavaScript · vocab/formats.mjs

// Four formats checked on their own, then one schema with format as an annotation and with formats asserted.
import { FORMATS, validate } from './minischema.mjs';

const SAMPLES = {
  email: ['asha@example.com', 'not-an-email'],
  'date-time': ['2025-03-14T10:30:00+05:30', '2025-03-14 10:30', '2025-02-29T10:30:00Z'],
  ipv4: ['192.168.1.30', '192.168.1.300'],
  uuid: ['a3bb189e-8bf9-3888-9912-ace4e6543002', 'a3bb189e8bf938889912ace4e6543002'],
};
for (const [name, values] of Object.entries(SAMPLES)) {
  for (const value of values) console.log(`${name} ${JSON.stringify(value)}: ${FORMATS[name](value) ? 'fits' : 'does not fit'}`);
}

const SCHEMA = JSON.parse(`{"type": "object", "required": ["email"], "properties": {
  "email": {"type": "string", "format": "email"},
  "placed": {"type": "string", "format": "date-time"},
  "phone": {"type": "string", "format": "phone"}}}`);
const order = { email: 'not-an-email', placed: '2025-03-14 10:30', phone: '98450 12345' };
console.log();
for (const asserted of [false, true]) {
  const [errors, notes] = validate(SCHEMA, order, asserted);
  console.log(`formats ${asserted ? 'asserted' : 'as annotations'}: ${errors.length ? `${errors.length} errors` : 'valid'}`);
  for (const [at, message] of errors) console.log(`  error at ${at}: ${message}`);
  if (!asserted) for (const [at, message] of notes) console.log(`  annotation at ${at}: ${message}`);
}

email "asha@example.com": fits
email "not-an-email": does not fit
date-time "2025-03-14T10:30:00+05:30": fits
date-time "2025-03-14 10:30": does not fit
date-time "2025-02-29T10:30:00Z": does not fit
ipv4 "192.168.1.30": fits
ipv4 "192.168.1.300": does not fit
uuid "a3bb189e-8bf9-3888-9912-ace4e6543002": fits
uuid "a3bb189e8bf938889912ace4e6543002": does not fit

formats as annotations: valid
  annotation at /email: format email
  annotation at /placed: format date-time
  annotation at /phone: format phone
formats asserted: 3 errors
  error at /email: "not-an-email" is not a valid email
  error at /placed: "2025-03-14 10:30" is not a valid date-time
  error at /phone: unknown format phone

Python · vocab/vocab.py

"""The vocabularies of the 2020-12 dialect, and whether a validator may process a dialect that needs another one."""

from minischema import KEYWORDS, V, can_process

# The $vocabulary of the 2020-12 meta-schema, https://json-schema.org/draft/2020-12/schema
META = {V + name: True for name in ["core", "applicator", "unevaluated", "validation", "meta-data",
                                    "format-annotation", "content"]}
for uri, required in META.items():
    count = len(KEYWORDS[uri].split())
    print(f"{uri.removeprefix(V):<18} {'required' if required else 'optional'}, {count} keyword{'s' * (count > 1)}")
print("in all:", sum(len(KEYWORDS[uri].split()) for uri in META), "keywords")

SUPPORTED = set(META)  # a validator that supports exactly the standard dialect
BOOKSHOP = {V + name: True for name in ["core", "applicator", "validation", "meta-data", "format-assertion"]}
print()
for label, vocabularies, supported in [
    ("the 2020-12 dialect", META, SUPPORTED),
    ("the bookshop's dialect", BOOKSHOP, SUPPORTED),
    ("the bookshop's dialect, format-assertion supported", BOOKSHOP, SUPPORTED | {V + "format-assertion"}),
]:
    refusal = can_process(vocabularies, supported)
    print(f"{label}: {'processed' if refusal is None else 'refused, because ' + refusal}")

core               required, 9 keywords
applicator         required, 15 keywords
unevaluated        required, 2 keywords
validation         required, 20 keywords
meta-data          required, 7 keywords
format-annotation  required, 1 keyword
content            required, 3 keywords
in all: 57 keywords

the 2020-12 dialect: processed
the bookshop's dialect: refused, because it requires https://json-schema.org/draft/2020-12/vocab/format-assertion
the bookshop's dialect, format-assertion supported: processed

JavaScript · vocab/vocab.mjs

// The vocabularies of the 2020-12 dialect, and whether a validator may process a dialect that needs another one.
import { KEYWORDS, canProcess } from './minischema.mjs';

const V = 'https://json-schema.org/draft/2020-12/vocab/';
// The $vocabulary of the 2020-12 meta-schema, https://json-schema.org/draft/2020-12/schema
const META = Object.fromEntries(['core', 'applicator', 'unevaluated', 'validation', 'meta-data', 'format-annotation', 'content'].map((n) => [V + n, true]));
for (const [uri, required] of Object.entries(META)) {
  const count = KEYWORDS[uri].split(' ').length;
  console.log(`${uri.slice(V.length).padEnd(18)} ${required ? 'required' : 'optional'}, ${count} keyword${count > 1 ? 's' : ''}`);
}
console.log('in all:', Object.keys(META).reduce((n, uri) => n + KEYWORDS[uri].split(' ').length, 0), 'keywords');

const SUPPORTED = new Set(Object.keys(META)); // a validator that supports exactly the standard dialect
const BOOKSHOP = Object.fromEntries(['core', 'applicator', 'validation', 'meta-data', 'format-assertion'].map((n) => [V + n, true]));
console.log();
for (const [label, vocabularies, supported] of [
  ['the 2020-12 dialect', META, SUPPORTED],
  ["the bookshop's dialect", BOOKSHOP, SUPPORTED],
  ["the bookshop's dialect, format-assertion supported", BOOKSHOP, new Set([...SUPPORTED, `${V}format-assertion`])],
]) {
  const refusal = canProcess(vocabularies, supported);
  console.log(`${label}: ${refusal === null ? 'processed' : `refused, because ${refusal}`}`);
}

core               required, 9 keywords
applicator         required, 15 keywords
unevaluated        required, 2 keywords
validation         required, 20 keywords
meta-data          required, 7 keywords
format-annotation  required, 1 keyword
content            required, 3 keywords
in all: 57 keywords

the 2020-12 dialect: processed
the bookshop's dialect: refused, because it requires https://json-schema.org/draft/2020-12/vocab/format-assertion
the bookshop's dialect, format-assertion supported: processed

Python · vocab/typos.py

"""Three misspelt keywords: what the validator does with them, what a keyword check finds, and the fixed schema."""

import json

from minischema import unknown_keywords, validate

SCHEMA = json.loads("""
{
  "type": "object",
  "properties": {
    "id": {"type": "string", "minLength": 1},
    "qty": {"type": "integer", "minimun": 1},
    "colour": {"type": "string"}
  },
  "requird": ["id"],
  "additionalProperites": false,
  "x-owner": "catalogue team"
}
""")
DOCUMENTS = ['{}', '{"id": "BK-101", "qty": 0}', '{"id": "BK-101", "qty": 2, "giftwrap": true}']
for text in DOCUMENTS:
    errors = validate(SCHEMA, json.loads(text))[0]
    print(f"{text}: {'valid' if not errors else f'{len(errors)} errors'}")

print()
found = unknown_keywords(SCHEMA)
for where, close in found:
    print(f"unknown keyword {where}: " + (f'did you mean "{close}"?' if close else "no keyword is close"))

fixed = json.loads(json.dumps(SCHEMA).replace('"minimun"', '"minimum"').replace('"requird"', '"required"')
                   .replace('"additionalProperites"', '"additionalProperties"'))
print()
print("after the three fixes:", "no unknown keywords" if not unknown_keywords(fixed) else unknown_keywords(fixed))
for text in DOCUMENTS:
    for at, message in validate(fixed, json.loads(text))[0]:
        place = at if at else '""'
        print(f"{text}: error at {place}: {message}")

{}: valid
{"id": "BK-101", "qty": 0}: valid
{"id": "BK-101", "qty": 2, "giftwrap": true}: valid

unknown keyword /properties/qty/minimun: did you mean "minimum"?
unknown keyword /requird: did you mean "required"?
unknown keyword /additionalProperites: did you mean "additionalProperties"?

after the three fixes: no unknown keywords
{}: error at "": missing required property "id"
{"id": "BK-101", "qty": 0}: error at /qty: 0 is below the minimum of 1
{"id": "BK-101", "qty": 2, "giftwrap": true}: error at /giftwrap: property "giftwrap" is not allowed

JavaScript · vocab/typos.mjs

// Three misspelt keywords: what the validator does with them, what a keyword check finds, and the fixed schema.
import { unknownKeywords, validate } from './minischema.mjs';

const SCHEMA = JSON.parse(`
{
  "type": "object",
  "properties": {
    "id": {"type": "string", "minLength": 1},
    "qty": {"type": "integer", "minimun": 1},
    "colour": {"type": "string"}
  },
  "requird": ["id"],
  "additionalProperites": false,
  "x-owner": "catalogue team"
}
`);
const DOCUMENTS = ['{}', '{"id": "BK-101", "qty": 0}', '{"id": "BK-101", "qty": 2, "giftwrap": true}'];
for (const text of DOCUMENTS) {
  const errors = validate(SCHEMA, JSON.parse(text))[0];
  console.log(`${text}: ${errors.length ? `${errors.length} errors` : 'valid'}`);
}

console.log();
for (const [where, close] of unknownKeywords(SCHEMA)) {
  console.log(`unknown keyword ${where}: ${close ? `did you mean "${close}"?` : 'no keyword is close'}`);
}

const fixed = JSON.parse(JSON.stringify(SCHEMA).replace('"minimun"', '"minimum"').replace('"requird"', '"required"')
  .replace('"additionalProperites"', '"additionalProperties"'));
console.log();
console.log('after the three fixes:', unknownKeywords(fixed).length ? unknownKeywords(fixed) : 'no unknown keywords');
for (const text of DOCUMENTS) {
  for (const [at, message] of validate(fixed, JSON.parse(text))[0]) console.log(`${text}: error at ${at || '""'}: ${message}`);
}

{}: valid
{"id": "BK-101", "qty": 0}: valid
{"id": "BK-101", "qty": 2, "giftwrap": true}: valid

unknown keyword /properties/qty/minimun: did you mean "minimum"?
unknown keyword /requird: did you mean "required"?
unknown keyword /additionalProperites: did you mean "additionalProperties"?

after the three fixes: no unknown keywords
{}: error at "": missing required property "id"
{"id": "BK-101", "qty": 0}: error at /qty: 0 is below the minimum of 1
{"id": "BK-101", "qty": 2, "giftwrap": true}: error at /giftwrap: property "giftwrap" is not allowed

Python · vocab/suite.py

"""Cases in the JSON-Schema-Test-Suite's file format, run against the lesson's validator, with and without formats."""

from minischema import validate

REQUIRED = [
    {"description": "integer and a zero fraction", "schema": {"type": "integer"},
     "tests": [{"description": "1.0 is an integer", "data": 1.0, "valid": True},
               {"description": "1.5 is not", "data": 1.5, "valid": False}]},
    {"description": "minLength counts characters", "schema": {"minLength": 2},
     "tests": [{"description": "one emoji is one character", "data": "📚", "valid": False},
               {"description": "two letters", "data": "ab", "valid": True}]},
    {"description": "required", "schema": {"required": ["id"]},
     "tests": [{"description": "a missing member", "data": {}, "valid": False},
               {"description": "a value that is not an object", "data": "id", "valid": True}]},
]
OPTIONAL_FORMAT = [
    {"description": "email", "schema": {"format": "email"},
     "tests": [{"description": "an ordinary address", "data": "asha@example.com", "valid": True},
               {"description": "no @ at all", "data": "not-an-email", "valid": False}]},
    {"description": "date-time", "schema": {"format": "date-time"},
     "tests": [{"description": "with an offset", "data": "2025-03-14T10:30:00+05:30", "valid": True},
               {"description": "a leap day in a common year", "data": "2025-02-29T10:30:00Z", "valid": False}]},
]


def run(cases, asserted):
    """(tests passed, tests run, descriptions of the tests that failed)."""
    passed, failed, total = 0, [], 0
    for case in cases:
        for test in case["tests"]:
            total += 1
            valid = not validate(case["schema"], test["data"], assert_formats=asserted)[0]
            if valid == test["valid"]:
                passed += 1
            else:
                failed.append(f"{case['description']}: {test['description']}")
    return passed, total, failed


for label, cases, asserted in [("required tests", REQUIRED, False),
                               ("optional format tests, formats as annotations", OPTIONAL_FORMAT, False),
                               ("optional format tests, formats asserted", OPTIONAL_FORMAT, True)]:
    passed, total, failed = run(cases, asserted)
    print(f"{label}: {passed} of {total} pass")
    for name in failed:
        print(f"  failed: {name}")

required tests: 6 of 6 pass
optional format tests, formats as annotations: 2 of 4 pass
  failed: email: no @ at all
  failed: date-time: a leap day in a common year
optional format tests, formats asserted: 4 of 4 pass

JavaScript · vocab/suite.mjs

// Cases in the JSON-Schema-Test-Suite's file format, run against the lesson's validator, with and without formats.
import { validate } from './minischema.mjs';

const REQUIRED = [
  { description: 'integer and a zero fraction', schema: { type: 'integer' },
    tests: [{ description: '1.0 is an integer', data: 1.0, valid: true }, { description: '1.5 is not', data: 1.5, valid: false }] },
  { description: 'minLength counts characters', schema: { minLength: 2 },
    tests: [{ description: 'one emoji is one character', data: '📚', valid: false }, { description: 'two letters', data: 'ab', valid: true }] },
  { description: 'required', schema: { required: ['id'] },
    tests: [{ description: 'a missing member', data: {}, valid: false }, { description: 'a value that is not an object', data: 'id', valid: true }] },
];
const OPTIONAL_FORMAT = [
  { description: 'email', schema: { format: 'email' },
    tests: [{ description: 'an ordinary address', data: 'asha@example.com', valid: true }, { description: 'no @ at all', data: 'not-an-email', valid: false }] },
  { description: 'date-time', schema: { format: 'date-time' },
    tests: [{ description: 'with an offset', data: '2025-03-14T10:30:00+05:30', valid: true },
      { description: 'a leap day in a common year', data: '2025-02-29T10:30:00Z', valid: false }] },
];

// [tests passed, tests run, descriptions of the tests that failed].
function run(cases, asserted) {
  let passed = 0;
  let total = 0;
  const failed = [];
  for (const c of cases) {
    for (const t of c.tests) {
      total += 1;
      const valid = !validate(c.schema, t.data, asserted)[0].length;
      if (valid === t.valid) passed += 1;
      else failed.push(`${c.description}: ${t.description}`);
    }
  }
  return [passed, total, failed];
}

for (const [label, cases, asserted] of [
  ['required tests', REQUIRED, false],
  ['optional format tests, formats as annotations', OPTIONAL_FORMAT, false],
  ['optional format tests, formats asserted', OPTIONAL_FORMAT, true],
]) {
  const [passed, total, failed] = run(cases, asserted);
  console.log(`${label}: ${passed} of ${total} pass`);
  for (const name of failed) console.log(`  failed: ${name}`);
}

required tests: 6 of 6 pass
optional format tests, formats as annotations: 2 of 4 pass
  failed: email: no @ at all
  failed: date-time: a leap day in a common year
optional format tests, formats asserted: 4 of 4 pass