vega-lite-validator-0-1-0

name	vega-lite-validator-0-1-0
description	Validates Vega-Lite 6.4.3 JSON specifications against the official JSON Schema using check-jsonschema. Catches structural errors, invalid field types, and missing required properties before rendering. Use when validating Vega-Lite specs generated by applications, pipelines, or agents, or debugging schema violations in visualization definitions.

Vega-Lite Validate (v6.4.3)

Overview

Validates Vega-Lite 6.4.3 specification files against the official JSON Schema using check-jsonschema (a Python CLI built on the jsonschema library). The Vega-Lite schema (~1.8 MB, JSON Schema Draft-07) is shipped with this skill in assets/vega-lite-schema.json, so validation works offline without network access.

When to Use

• Validating a Vega-Lite spec before passing it to a renderer (Vega, vega-lite npm package, Altair, etc.)
• Debugging schema violations in programmatically generated visualization definitions
• CI/CD checks on JSON specs stored in repositories
• Verifying specs received from external applications or APIs

Usage

Run the validation script with a path to the Vega-Lite spec file:

bash scripts/vega-lite-validate.sh instance.json

The script resolves assets/vega-lite-schema.json relative to its own location, so it works correctly regardless of the current working directory.

Exit Codes

Code	Meaning
0	Spec is valid under the Vega-Lite schema
1	Validation failed — schema errors found
2	Usage error (missing argument, missing files)

Output on Success

ok -- validation done

Output on Failure

Detailed per-path error list showing best match and best deep match for each violation. Example:

Schema validation errors were encountered.
  instance.json::$: {...} is not valid under any of the given schemas
  Best Match:
    $: 'data' is a required property
  Best Deep Match:
    $.encoding.x.type: 'invalid_type' is not one of ['quantitative', 'ordinal', 'temporal', 'nominal']
  27 other errors were produced. Use '--verbose' to see all errors.

Usage Examples

Validate a spec file

bash scripts/vega-lite-validate.sh path/to/spec.vl.json

Validate and capture result in a script

if bash scripts/vega-lite-validate.sh spec.json; then
    echo "Spec is valid"
else
    echo "Spec has errors — fix before rendering"
fi

Interpret validation errors

When validation fails, focus on the Best Match (top-level structural issue) and Best Deep Match (most specific field-level issue). Common error patterns:

• 'data' is a required property — spec missing the data block
• 'invalid_type' is not one of [...] — encoding field uses wrong data type
• is not valid under any of the given schemas — structural mismatch in the top-level spec shape

Core Concepts

Schema Source

The schema file (assets/vega-lite-schema.json) is downloaded from the official Vega-Lite repository at tag v6.4.3: https://raw.githubusercontent.com/vega/vega-lite/v6.4.3/build/vega-lite-schema.json

It is a JSON Schema Draft-07 document referencing #/definitions/TopLevelSpec.

Validation Tool

check-jsonschema is invoked via uvx (preferred) or pipx (fallback), both of which provide ephemeral execution without persistent installation. The script auto-detects whichever runtime is available.

uvx check-jsonschema --schemafile <schema> <instance>
pipx run check-jsonschema --schemafile <schema> <instance>

No additional packages or format-checking libraries are required — the default format checks (date, date-time, email, ipv4, ipv6, regex, uuid) suffice for Vega-Lite validation.

Vega-Lite Spec Structure

A valid Vega-Lite spec must include at minimum:

• data — data source (url, values, or name)
• mark — mark type (bar, line, point, area, text, etc.)
• encoding — field-to-channel mappings with valid types (quantitative, ordinal, temporal, nominal)

Optional top-level properties include $schema, description, width, height, transform, params, config, layer, facet, concat, hconcat, vconcat, repeat, and resolve.