Registry / web-framework / metalman-schema

metalman-schema

library4.0.2jsnpmunverified

metalman-schema is a JSON schema validation middleware specifically designed for the `metalman` module. It leverages the `ajv` library for robust JSON schema validation. The current stable version is 4.0.2, released in November 2023, indicating an active but not rapid release cadence, with previous major updates in 2021. This library differentiates itself by providing a `metalman`-compatible middleware, allowing schema definitions to be integrated directly into `metalman` commands for streamlined request validation. It acts as a factory function that returns the actual middleware, providing flexibility to configure the underlying `ajv` instance.

web-framework serialization

npm install metalman-schema

github ↗package ↗

INSTALL

IMPORT

SIG · METALMAN-SCHEMA

metalman-schema

web-frameworkjavascriptv4.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createSchemaMiddleware

✓ import createSchemaMiddleware from 'metalman-schema';

✗ import { createSchemaMiddleware } from 'metalman-schema';

The default export is a factory function that creates the validation middleware. The example in the README is slightly misleading, implying `metalman-schema` directly exports the middleware rather than a factory for it.

createSchemaMiddleware

✓ const createSchemaMiddleware = require('metalman-schema');

✗ const { factory } = require('metalman-schema');

For CommonJS, the default export is the factory function. While the source uses a named `factory` function internally, `module.exports` is set directly to this function, making it the default export.

middleware

✓ const validate = createSchemaMiddleware();

✗ const validate = require('metalman-schema'); // This gets the factory, not the middleware itself

The actual middleware function used by `metalman` is returned by calling the `createSchemaMiddleware` factory function. This allows for optional configuration of the underlying AJV instance.

This quickstart demonstrates how to set up `metalman-schema` as a middleware with `metalman` to validate incoming command data against a JSON schema, showing both valid and invalid scenarios.

import metalman from 'metalman'; import createSchemaMiddleware from 'metalman-schema'; // Create the validation middleware using the factory // You can pass ajvOptions or a custom ajv instance here: createSchemaMiddleware({ ajvOptions: { allErrors: true } }) const validate = createSchemaMiddleware(); // Define a metalman command with the validation middleware const commandFactory = metalman([validate]); const validateUser = commandFactory({ schema: { type: 'object', required: ['name', 'age'], additionalProperties: false, properties: { name: { type: 'string', minLength: 1 }, age: { type: 'number', minimum: 18 } } } }); // Valid case validateUser({ name: 'Alice', age: 30 }, (err) => { if (err) { console.error('Validation failed for Alice:', err.message); } else { console.log('Validation successful for Alice.'); } }); // Invalid case (age too low) validateUser({ name: 'Bob', age: 16 }, (err) => { if (err) { console.error('Validation failed for Bob:', err.name, '-', err.message); } else { console.log('Validation successful for Bob.'); } }); // Invalid case (missing required field) validateUser({ age: 25 }, (err) => { if (err) { console.error('Validation failed (missing name):', err.name, '-', err.message); } else { console.log('Validation successful (missing name).'); } });

Debug

Known issues

breakingVersion 4.0.0 introduced a breaking change by upgrading the underlying JSON schema validator to AJV v7. This might break existing schemas, particularly those using older draft specifications (like draft-04, which is no longer supported by AJV v7) or relying on removed keywords.

fix

Review AJV v7 release notes for schema migration guidelines, especially regarding `$id` vs `id` and format validation changes (now requiring `ajv-formats`). Update schemas to comply with JSON Schema draft-06 or later.

affects: >=4.0.0

breakingVersion 3.0.0 dropped support for `metalman@v2` and older Node.js versions, requiring an upgrade to `metalman@v3`. This version also mandates ES2015 features (e.g., `const` declarations).

fix

Ensure your project uses `metalman@v3` or newer and a Node.js version compatible with ES2015+ features. Update `require` statements to `const` for improved code style.

affects: >=3.0.0

breakingSince version 3.0.0, the middleware automatically coerces types by default. This changes validation behavior, as values might be converted (e.g., '123' to 123) instead of failing validation for incorrect types.

fix

If type coercion is undesirable, you may need to configure the AJV instance passed to `createSchemaMiddleware` to disable this behavior (e.g., `{ coerceTypes: false }`). Refer to AJV documentation for exact options.

affects: >=3.0.0

gotchaSince version 4.0.1, `ajv-formats` is automatically added by default if no custom `AJV` instance is passed to `createSchemaMiddleware`. If you were relying on a minimal AJV setup without format validation, this might introduce new validation rules for properties like `format: 'email'`.

fix

If you need to control format validation explicitly, pass a custom `AJV` instance to the `createSchemaMiddleware` factory and configure `ajv-formats` (or omit it) as per your requirements.

affects: >=4.0.1

Errors

Common errors & fixes

err.name equals 'ValidationError'

Input data to the metalman command does not conform to the defined JSON schema.

fix

Inspect `err.errors` (if available) or `err.message` for details on which part of the input failed validation. Adjust the input data or refine the JSON schema definition.

TypeError: Cannot read properties of undefined (reading 'schema')

The `metalman-schema` middleware expects the schema to be present on the `command` object (e.g., `command.schema`). This error occurs if the `schema` property is missing from the command options.

fix

Ensure that the `metalman` command function, when called, receives an options object that includes a `schema` property with a valid JSON schema definition, e.g., `commandFactory({ schema: { type: 'object', ... } })`.

Ajv is not a constructor

This usually indicates an incorrect import or version mismatch of `ajv`, especially after the v7 upgrade where `new Ajv()` syntax became mandatory and `require('ajv')` directly returns the constructor (or `require('ajv').default` for some setups).

fix

For `ajv` v7+, use `const Ajv = require('ajv').default;` for CommonJS or `import Ajv from 'ajv';` for ESM, then instantiate with `new Ajv()`. Ensure `ajv` is correctly installed.

Upgrade

Version history

4.0.2latest on npm

Audit

Dependencies

metalmanrequiredCore middleware framework this package is built for. Requires `metalman@v3` or higher since `metalman-schema@v3.0.0`.

ajvrequiredUnderlying JSON schema validator. Requires `ajv@v7` or higher since `metalman-schema@v4.0.0`.

ajv-formatsoptionalProvides format validation for `ajv` schemas. Automatically added by default if no custom `AJV` instance is passed to the factory since `metalman-schema@v4.0.1`.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/marcbachmann/metalman-schema ↗

packagehttps://www.npmjs.com/package/metalman-schema ↗