A rule-based JSON validation tool for structured datasets.
npm install @douglaskadlec/json-verifyJSON 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.
---
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 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.
---
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 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.
---
`
root/
├── index.js # CLI entry point
├── engine/ # Validation engine (stable)
│ ├── loadData.js
│ ├── loadRules.js
│ ├── verify.js
│ └── report.js
└── subjects/ # User-defined validation targets
└──
├── data/
│ └── data.json
└── rules/
├── row/
│ └── *.js
└── collection/
└── *.js
---
From the project root:
`
npx @douglaskadlec/json-verify
- 0 — validation passed, no issues found
- 1 — validation failed or execution error occurred
This makes JSON Verify suitable for CI pipelines or scripted workflows.
---
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.
---
- 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.
---
MIT
---