api-response-validator

Structural validation for API responses. Define a schema (or infer one from a sample response), validate real data against it, and get back every mismatch with an exact JSONPath — not just the first one.

What this is

• A small schema DSL:
  • primitives: 'string' | 'number' | 'boolean' | 'null' | 'any'
  • unions: 'string|number', nullable: 'string|null'
  • nested objects: plain { field: SchemaNode }
  • optional fields: key suffixed with ?, e.g. 'nickname?': 'string'
  • arrays: { type: 'array', items: SchemaNode }
  • enums: { type: 'enum', values: [...] }
• validate(data, schema, options) — returns { valid, errors[] } where each error has { path, expected, actual } (path like $.items[2].qty).
• strict vs passthrough mode — strict flags keys present in the data but not declared in the schema.
• fromExample(sample) — infers a schema from a real response, including nested objects and arrays.
• ResponseValidator — a thin class wrapper with .validate() and .assert() (throws one Error listing all mismatches).

What this is NOT

• Not a JSON Schema implementation (different, smaller DSL).
• Not a coercion/transform library — it validates, it doesn't reshape data.
• Not a request-body middleware — bring your own HTTP integration.

Quickstart

npm install
npm run build
node dist/examples/demo.js

API

import { validate, fromExample, ResponseValidator } from 'api-response-validator';

const schema = {
  id: 'number',
  role: { type: 'enum', values: ['admin', 'user'] },
  'nickname?': 'string',
  note: 'string|null',
  items: { type: 'array', items: { sku: 'string', qty: 'number' } },
};

const result = validate(responseBody, schema);
// { valid: false, errors: [{ path: '$.items[1].qty', expected: 'number', actual: 'undefined' }] }

const inferred = fromExample(sampleResponse); // schema from a real payload

const validator = new ResponseValidator(schema, { mode: 'strict' });
validator.assert(responseBody); // throws with every mismatch listed

Demo: catching a breaking API change

examples/demo.ts infers a schema from a known-good response, then validates a "broken deploy" version where a field's type flipped and another field was dropped:

$ node dist/examples/demo.js
valid: false
$.id: expected number, got string
$.address.zip: expected string, got undefined

License

MIT

Sponsored by Ferrow

Part of the ferrow-toolkit collection · Sponsored by Ferrow