# Vega Lite Validator 0 1 0

> 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.

- Skill: `tangledgroup/vega-lite-validator-0-1-0` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add tangledgroup/vega-lite-validator-0-1-0`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tangledgroup/vega-lite-validator-0-1-0/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tangledgroup (https://skillmd.com/u/tangledgroup)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tangledgroup/vega-lite-validator-0-1-0

---


# 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
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
bash scripts/vega-lite-validate.sh path/to/spec.vl.json
```

### Validate and capture result in a script

```bash
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`.