cli

jsonstat-validate

Command-line semantic validator for JSON-stat 2.0 — the CLI surface of the jsonstat-validator family. It runs the @jsonstat-validator/ts engine under the hood: the official JSON Schema 2020-12 structural pass plus the cross-field cube invariants JSON Schema cannot express.

This CLI is one of four interchangeable surfaces (TS, Rust, Wasm, CLI) that all share one rules-manifest.json and one corpus/cases.json, so they produce identical findings on identical input. See the monorepo README for the full architecture and DESIGN.md for the design rationale.

---

Why

JSON Schema can validate shape (required properties, oneOfs, enums, the IANA link regex) but cannot express relationships like "value array length must equal the product of size". jsonstat-validate runs exactly those checks (the S/D/C catalogue) with a stable, versioned error-code vocabulary, and reports them in a CI-friendly text or JSON format.

---

Usage

No install needed — run it once with npx:

# validate a file
npx jsonstat-validate my-cube.json

# validate JSON on stdin (note the `-`)
echo '{"version":"2.0","class":"dataset","id":["x"],"size":[2],"dimension":{"x":{"category":{"index":["a","b"]}}},"value":[1]}' \
  | npx jsonstat-validate -

# machine-readable output for CI
npx jsonstat-validate my-cube.json --format json

$ npx jsonstat-validate my-cube.json
valid: false
summary: 1 errors, 0 warnings, 0 infos, 0 structural
  [error] VALUE_LEN_MISMATCH  /value  — Dense 'value' length 1 must equal product(size) = 2.

Exit code is 0 when valid, 1 when invalid — drop it straight into a pipeline or pre-commit hook:

npx jsonstat-validate data/*.json || exit 1

Or install globally

npm install -g jsonstat-validate
jsonstat-validate my-cube.json

---

Options

jsonstat-validate <file|-> [options]
  --mode full|structural|semantic   validation phases to run (default: full)
  --format json|text                output format (default: text)
  --min-severity error|warning|info only show findings at/above this severity (default: info)
  --structural-only                 alias for --mode structural
  --semantic-only                   alias for --mode semantic
  -h, --help                        show usage

Flag	Values	Default	Notes
<file|->	path or -	—	A path to a JSON file, or - to read JSON from stdin
--mode	full | structural | semantic	full	Which passes to run
--format	json | text	text	json emits the full ValidationResult for scripting
--min-severity	error | warning | info	info	Filters printed findings (does not affect the exit code)
--structural-only	—	—	Shorthand for --mode structural
--semantic-only	—	—	Shorthand for --mode semantic

--min-severity only affects which findings are displayed; it never changes the exit code, which is 0 iff the document has zero error-severity findings.

JSON output

npx jsonstat-validate my-cube.json --format json

{
  "valid": false,
  "findings": [
    {
      "code": "VALUE_LEN_MISMATCH",
      "ruleId": "S3",
      "severity": "error",
      "path": "/value",
      "message": "Dense 'value' length 1 must equal product(size) = 2.",
      "expected": 2,
      "actual": 1,
      "specRef": "wiki/format-specification.md"
    }
  ],
  "summary": { "errors": 1, "warnings": 0, "infos": 0, "structuralErrors": 0, "byCode": { "VALUE_LEN_MISMATCH": 1 } },
  "meta": { "engineVersion": "1.0.0", "ruleSetVersion": "1.0.0", "schemaVersion": "1.05", "durationMs": 3 }
}

Structural (JSON Schema) violations are normalized into the same shape with code: "STRUCTURAL_VIOLATION" and the offending keyword kept in meta — so tooling only ever handles one finding shape.

---

Error codes

See rules-manifest.json for the authoritative, append-only catalogue. Codes include VALUE_LEN_MISMATCH, SPARSE_KEY_OUT_OF_RANGE, STATUS_LEN_MISMATCH, DIM_KEY_ID_MISMATCH, ID_SIZE_LEN_MISMATCH, ROLE_ID_UNKNOWN, INDEX_COUNT_MISMATCH, INDEX_POSITIONS_INVALID, LABEL_KEY_UNKNOWN, LABEL_KEY_INCOMPLETE, UNIT_KEY_UNKNOWN, COORD_KEY_UNKNOWN, NOTE_KEY_UNKNOWN, CHILD_ID_UNKNOWN, CHILD_CYCLE, METRIC_UNIT_MISSING (warning), BUNDLE_DEPRECATED (info), RECURSION_LIMIT (info), CUBE_SIZE_OVERFLOW, BUDGET_EXCEEDED (warning), PARSE_ERROR, and STRUCTURAL_VIOLATION. The vocabulary is versioned independently (meta.ruleSetVersion) from the package SemVer.

---

Building from source

# from the monorepo root
npm install                 # runs the `prepare` hook, which builds the CLI too
npx jsonstat-validate --help

# or, just this workspace
cd cli
npm run build               # sync-license → esbuild bundle of src/cli.ts → dist/cli.js
npm run dev                 # run directly from TypeScript: node --experimental-strip-types src/cli.ts

The CLI is a thin wrapper around @jsonstat-validator/ts; see src/cli.ts for the argument parsing and output formatting.

---

Related surfaces

• TypeScript / Node — @jsonstat-validator/ts
• Rust — jsonstat-validator (cargo add jsonstat-validator)
• Wasm — 🚧 in progress (see the monorepo Roadmap)

---

License

Apache-2.0.