cloudflare/cabidela

cloudflare/cabidela

Description: Cabidela is a small, fast, eval-less, Cloudflare Workers compatible, dynamic JSON Schema validator.

Language: TypeScript

License: NOASSERTION

Stars: 28

Forks: 2

Open issues: 5

Created: 2025-02-05T17:39:19Z

Pushed: 2026-04-23T20:49:51Z

Default branch: main

Fork: no

Archived: no

README:

Small, fast, eval-less, Cloudflare Workers compatible, dynamic JSON Schema validator.

What is

Cabidela is a small, fast, eval-less, Cloudflare Workers compatible, dynamic JSON Schema validator. It implements a large subset of that should cover most use-cases. But not all. See limitations below.

How to use

Install the package:

npm install @cloudflare/cabidela --save

Import it:

import { Cabidela } from "@cloudflare/cabidela";

Use it:

let schema: any = {
type: "object",
properties: {
prompt: {
type: "string",
minLength: 1,
maxLength: 131072,
description: "The input text prompt for the model to generate a response.",
},
num_steps: {
type: "number",
minimum: 0,
maximum: 20,
description: "Increases the likelihood of the model introducing new topics.",
},
},
required: ["prompt"],
};

const cabidela = new Cabidela(schema);

cabidela.validate({
prompt: "Tell me a joke",
num_steps: 5,
});

Cabidela implements a Exception-Driven Validation approach. If any condition in the schema is not met, we throw an error.

API

New instance

const cabidela = new Cabidela(schema: any, options?: CabidelaOptions)

Cabidela takes a JSON-Schema and optional configuration flags:

• applyDefaults: boolean - If true, the validator will apply default values to the input object. Default is false.
• errorMessages: boolean - If true, the validator will use custom errorMessage messages from the schema. Default is false.
• fullErrors: boolean - If true, the validator will be more verbose when throwing errors for complex schemas (example: anyOf, oneOf's), set to false for shorter exceptions. Default is true.
• useMerge: boolean - Set to true if you want to use the $merge keyword. Default is false. See below for more information.
• subSchemas: any[] - An optional array of sub-schemas that can be used with $id and $ref. See below for more information.

Returns a validation object.

You can change the schema at any time by calling cabidela.setSchema(schema: any).

You can change the options at any time by calling cabidela.setOptions(options: CabidelaOptions).

Validate payload

Call cabidela.validate(payload: any) to validate your payload.

Returns truth if the payload is valid, throws an error otherwise.

const payload = {
messages: [
{ role: "system", content: "You're a helpful assistant" },
{ role: "user", content: "What is Cloudflare?" },
],
};

try {
cabidela.validate(payload);
console.log("Payload is valid");
} catch (e) {
console.error(e);
}

Modifying the payload

Some options, like applyDefaults, will modify the input object.

const schema = {
type: "object",
properties: {
prompt: {
type: "string",
},
num_steps: {
type: "number",
default: 10,
},
},
};

const cabidela = new Cabidela(schema, { applyDefaults: true });

const payload = {
prompt: "Tell me a joke",
});

cabidela.validate(payload);

console.log(payload);

// {
// prompt: 'Tell me a joke',
// num_steps: 10
// }

oneOf defaults

Using applyDefaults with oneOf will one apply the default value of the sub-schema that matches the condition. For example, using this schema:

{
type: "object",
oneOf: [
{
type: "object",
properties: {
sun: {
type: "number",
default: 9000,
},
moon: {
type: "number",
default: 9000,
},
},
required: ["sun"],
},
{
type: "object",
properties: {
sun: {
type: "number",
default: 9000,
},
moon: {
type: "number",
default: 9000,
},
},
required: ["moon"],
},
],
};

• The payload { sun: 10} will be modified to { sun: 10, moon: 9000 }.
• The payload { moon: 10} will be modified to { sun: 9000, moon: 10 }.
• The payload { saturn: 10} will throw an error because no condition is met.

$id, $ref, $defs

The keywords $id, $ref and $defs can be used to build and maintain complex schemas where the reusable parts are defined in separate schemas.

The following is the main schema and a customer sub-schema that defines the contacts and address properties.

import { Cabidela } from "@cloudflare/cabidela";

const schema = {
$id: "http://example.com/schemas/main",
type: "object",
properties: {
name: { type: "string" },
contacts: { $ref: "customer#/contacts" },
address: { $ref: "customer#/address" },
balance: { $ref: "$defs#/balance" },
},
required: ["name", "contacts", "address"],
"$defs": {
"balance": {
type: "object",
prope properties: {
currency: { type: "string" },
amount: { type: "number" },
},
}
}
};

const contactSchema = {
$id: "http://example.com/schemas/customer",
contacts: {
type: "object",
properties: {
email: { type: "string" },
phone: { type: "string" },
},
required: ["email", "phone"],
},
address: {
type: "object",
properties: {
street: { type: "string" },
city: { type: "string" },
zip: { type: "string" },
country: { type: "string" },
},
required: ["street", "city", "zip", "country"],
},
};

const cabidela = new Cabidela(schema, { subSchemas: [contactSchema] });

cabidela.validate({
name: "John",
contacts: {
email: "john@example.com",
phone: "+123456789",
},
address: {
street: "123 Main St",
city: "San Francisco",
zip: "94105",
country: "USA",
},
});

Combined schemas and $merge

The standard way of combining and extending schemas is by using the `allOf` (AND), `anyOf` (OR), `oneOf` (XOR) and `not` keywords, all supported by this library.

Cabidela supports an additional keyword $merge (inspired by Ajv) that allows you to merge two objects. This is useful when you want to…