Linting JSON Schema

vacuum can lint JSON Schema documents directly, without wrapping them in an OpenAPI description.

When no custom ruleset is supplied, vacuum uses the built-in json-schema-recommended ruleset. The rules focus on JSON Schema itself: schema validity, references, type and constraint compatibility, enum and const values, required fields, regular expressions, examples, defaults and a small set of quality checks.

Supported dialects

vacuum supports the common modern JSON Schema dialects.

If a schema does not declare a $schema, vacuum treats it as Draft 2020-12.

Linting folders

Point vacuum schema at a folder and it will recursively lint .json, .yaml and .yml files.

Use --include and --exclude when you need a narrower selection or non-standard file names.

If you pass shell globs to --include, quote them so the shell does not expand them before vacuum sees them.

Exploded schema packs

JSON Schema references are resolved from the document that contains the $ref. This matters for exploded schema packs.

Imagine a root schema that references a reusable file:

{
  "type": "object",
  "properties": {
    "gift": {
      "$ref": "_defs/GiftBag.schema.json"
    }
  }
}

Inside _defs/GiftBag.schema.json, the schema might refer to other extracted definitions using root $defs pointers.

{
  "type": "object",
  "properties": {
    "hat": {
      "$ref": "#/$defs/Hat"
    },
    "shirt": {
      "$ref": "#/$defs/Shirt"
    }
  }
}

As a standalone file, #/$defs/Hat means “look for $defs.Hat inside GiftBag.schema.json”. If that file does not contain $defs.Hat, plain linting will correctly report a broken reference.

For this kind of generated pack, use --bundle when linting the root schema.

Bundling moves external schemas into the root document’s $defs, rewrites external $ref values, and keeps local $defs lookups pointing at the bundled root.

when using --bundle, bundling occurs in memory - it’s not saved to disk.

Custom rules

JSON Schema linting supports the same ruleset model as OpenAPI linting. You can extend the built-in JSON Schema ruleset and add custom rules using core functions.

extends: [[vacuum:json-schema, recommended]]
rules:
  gift-title:
    description: Gift schemas should use a title
    severity: warn
    formats: [json-schema]
    given: $
    then:
      field: title
      function: truthy

Run it with the normal --ruleset flag.

Related commands

See the schema command for command flags, bundling examples and stdin/stdout usage.