JSON schema validator

This is a JSON schema validating solution for browser and Node.js environments. It uses jsonschema Rust package wrapped into a WASM module and exposing functionality in SchemaValidator object.

Usage

SchemaValidator must be initialized first, by passing the deployed WASM file URL to SchemaValidator.init.

The SchemaValidator.validate is asynchronous and returns a Promise<void>. If error happens then an object is rejected, which contains field name - error pairs, or an object with an error variable.

type SchemaValidationError = {
    error: string | object
} | {
    // Key is field name, value is the validation error related to that field
    [key: string]: string
}

Browser

Copy the following file into your output directory: @lsolova/json-schema-validator/dist/assets/schema_validator.wasm.

Then a simple validate call can be used, by passing the content or the URL of the schema file (http:// and https:// protocols are supported) and the data to be validated. If an HTTP(S) schema is downloaded once, then it is cached until the SchemaValidator object exists.

Download is part of the normal network traffic via browser's fetch. This allows caching schemas by PWA, if implemented.

import { SchemaValidator } from "@lsolova/json-schema-validator";

async function initValidation {
    // Set the wasmURL to the URL of the exposed WASM file (see more details below)
    await SchemaValidator.init(wasmURL);
    // If there would be any schema to be registered, then it can be done after the
    // initialization, but before the first usage of that schema
    await SchemaValidator.registerSchema(uri, schema);
};

// The schema parameter could be a schema URI (either HTTP(S) or (ID)) or a schema definition
async function validate(schema, data) {
    await SchemaValidator.validate(schema, data);
};

This validator supports HTTP(S) references within the schema files (for example: https://example.com/schemas/my.json or see $ref in the schema example).

Schema example

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "email": {"$ref": "http://example.com/schemas/email.schema.json"}
    },
    "required": ["name", "email"]
}

Security

Though it does not use eval, there is a special Content Security Policy setting required by high security environments.

If any script-src is set in the Content-Security-Policy header, then a 'wasm-unsafe-eval' entry must be added into the script-src section of this header. (Details on MDN).

Content-Security-Policy: ...;script-src your entries 'wasm-unsafe-eval'; ...

Node.js

Thanks to WASM support of Node.js, this module can be used in Node.js environment too.

This is an ESM module. Therefore it can be imported only using import, require is not supported.

It should be initialized by loading the WASM module first, before any validation.

import { readFile } from "node:fs/promises";
import { SchemaValidator } from "@lsolova/json-schema-validator";

async function sample() {
    const wasmBuffer = await readFile(
        "./node_modules/@lsolova/json-schema-validator/dist/assets/schema_validator.wasm"
    );
    await SchemaValidator.init(wasmBuffer);

    const schemaContent = await readFile("./schemas/my.schema.json", { encoding: "utf8" });
    await SchemaValidator.validate(schemaContent, myContentToValidate);
}

How to add WASM file to your deployment?

Browser: Using esbuild

TBD

Browser: Using Vite

Please, use the explicit URL import feature of Vite passing WASM URL to the SchemaValidator.init function. Everything else will be managed by Vite build.

import { SchemaValidator } from "@lsolova/json-schema-validator";
import wasmURL from "@lsolova/json-schema-validator/dist/assets/schema_validator.wasm?url";

async function initValidation() {
    await SchemaValidator.init(wasmURL);
}

Node.js: Using Node functions

The SchemaValidator.init supports passing a module instead of a path. Therefore WASM can be read from file and passed to the init function.

import { readFile } from "node:fs/promises";
import { SchemaValidator } from "@lsolova/json-schema-validator";

async function sample() {
    const wasmBuffer = await fs.readFile(
        "./node_modules/@lsolova/json-schema-validator/dist/assets/schema_validator.wasm"
    );
    await SchemaValidator.init(wasmBuffer);
}

Development

1. Run npm i
2. Run npm run build

Local testing

To start the web application on localhost, run npm run serve.

To check the Node.js run on localhost, run npx tsx node-example.ts.