JSON Verify

JSON Verify is a rule-based JSON validation tool built for clarity, extensibility, and predictable behavior.

It is designed to validate structured JSON datasets against a set of explicit rules, producing a list of human-readable issues. The engine is intentionally minimal: it loads data, loads rules, runs validation, and reports results. All domain-specific logic lives in the rules themselves.

This project is written in vanilla Node.js (ESM) and favors simplicity and explicit control over abstraction or configuration-heavy frameworks.

Core Concepts

Subjects

A subject is a self-contained validation target. Each subject defines:

• A single JSON data file (data.json)
• Zero or more row rules
• Zero or more collection rules

The included "example" subject is provided only as a reference and is not part of the validation engine.

Rules

Rules are plain JavaScript modules that export a default object with the following shape:

{
  name: string,
  check: function
}

There are two kinds of rules:

Row Rules

• Run once per record
• Receive (index, record)
• Used for validating individual rows

Collection Rules

• Run once per dataset
• Receive (allRecords)
• Used for cross-record validation (e.g. uniqueness)

Rules may be synchronous or asynchronous.

Rule Return Contract

A rule's check function must return:

• Array — one or more issues
• null — no issues

Any other return value is considered an error and will stop execution.

Each rule is responsible for:

• Catching its own errors (if desired)
• Returning issues, logging warnings, or throwing
• Deciding how strict or permissive it should be

The engine does not interfere with rule logic.

Issues

Issues are plain objects. The engine does not enforce a schema, but a typical issue looks like:

{
  rule: 'validDuration',
  message: 'Invalid format (expected MM:SS)',
  row: 3,
  id: '010'
}

Issues are collected and displayed at the end of execution.

Project Structure

root/
├── index.js                 # CLI entry point
├── engine/                  # Validation engine (stable)
│   ├── loadData.js
│   ├── loadRules.js
│   ├── verify.js
│   └── report.js
└── subjects/                # User-defined validation targets
    └── <subject>/
        ├── data/
        │   └── data.json
        └── rules/
            ├── row/
            │   └── *.js
            └── collection/
                └── *.js

Running the Tool

From the project root:

npx @douglaskadlec/json-verify <subject>

Exit Codes

• 0 — validation passed, no issues found
• 1 — validation failed or execution error occurred

This makes JSON Verify suitable for CI pipelines or scripted workflows.

Error Handling Philosophy

JSON Verify follows a strict and predictable error model:

• Engine code throws descriptive errors when it cannot proceed
• Malformed or invalid rules stop execution
• Rules control their own behavior
• The CLI is the single failure boundary

All errors ultimately bubble to index.js, where they are logged and cause a non-zero exit.

This keeps responsibility clear and avoids silent failures.

Design Goals

• Explicit behavior over configuration
• Clear ownership of logic
• Minimal abstraction
• Predictable execution
• Easy rule authoring

This tool is not meant to be a general-purpose validation framework. It is meant to be understood quickly, extended safely, and trusted in real workflows.

License

MIT