api-response-validator

npm install @ferrow/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';constschema={id: 'number',role: {type: 'enum',values: ['admin','user']},'nickname?': 'string',note: 'string|null',items: {type: 'array',items: {sku: 'string',qty: 'number'}},};constresult=validate(responseBody,schema);// { valid: false, errors: [{ path: '$.items[1].qty', expected: 'number', actual: 'undefined' }] }constinferred=fromExample(sampleResponse);// schema from a real payloadconstvalidator=newResponseValidator(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