npm install desyCreating a simple string schema
import {d} from 'desy';
// creating a schema for strings
const mySchema = d.string();
// validating
mySchema.validate('tuna'); // => ""
mySchema.validate(12); // => "Value must be string"- be
simple - be as
fastas point 1 allows
- Stop validating on the first error. Desy stops validating on the first error and returns it.
- A string is an indicator. Desy returns an empty string in a valid case. In case of an error, Desy returns a string with a description of the error.
- No throwing errors. Desy only returns an empty or non-empty string.
Deep schema
const schema = d.array(
d.object({
type: d.string().oneOf(['person']),
hair: d.string().oneOf(['blue', 'brown']),
active: d.boolean(),
name: d.string(),
age: d.number().int(),
hobbies: d.array(d.string()),
address: d.object({
street: d.string(),
zip: d.string(),
country: d.string(),
}),
}),
);
schema.validate(people);Get schema's types
import {d, InferDesy} from 'desy';
const userSchema = d.object({
username: d.string(),
});
const error = userSchema.validate({username: 'Ludwig'}); // error is ""
// extract the inferred type
type User = InferDesy<typeof user>; // { username: string }validate(value: any)
const schema = d.mixed();
schema.validate('a'); // valid
schema.validate(''); // valid
schema.validate(null); // valid.test(func: (value: sting) => string)
const schema = d.mixed().test((value) => {
if (value === 'world') {
return ''; // valid case
}
return 'MUST BE WORLD'; // error message
});
schema.validate('hello'); // error
schema.validate('world'); // valid.description(text: string)
Describes the schema for a reader. Ignored by validate, used by
createJsonSchema.
const schema = d.string().description('Full name as in the passport');
schema.validate('John'); // valid.message(message: string | (({path}) => string))
Replaces the error of any rule in the chain. A message written on a parent replaces whatever came from below, including which field failed.
const schema = d.string().min(3).message('Name is too short');
schema.validate('a'); // 'Name is too short'
schema.validate(42); // 'Name is too short'
const withPath = d.object({
name: d.string().message(({path}) => `${path} is wrong`),
});
withPath.validate({name: ''}); // 'Value.name is wrong'mixed()
const schema = d.mixed();
schema.validate('a'); // valid
schema.validate(''); // valid
schema.validate(null); // valid.string()
const schema = d.string();
schema.validate('a'); // valid
schema.validate(''); // error
schema.validate(null); // error.length(chars)
const schema = d.string().length(1);
schema.validate('aa'); // error
schema.validate('a'); // valid.optional()
const schema = d.string().optional();
schema.validate(''); // valid
schema.validate('a'); // valid.oneOf(variants: string[])
const schema = d.string().oneOf(['hello', 'world']);
schema.validate('hello'); // valid
schema.validate('world'); // valid
schema.validate('foo'); // error.regexp(regexp: Regexp)
const schema = d.string().regexp(/hello/i);
schema.validate('123hello'); // valid
schema.validate('hell'); // error.min(min_chars: number)
const schema = d.string().min(1);
schema.validate(''); // error
schema.validate('a'); // valid.max(max_chars: number)
const schema = d.string().max(1);
schema.validate('aa'); // error
schema.validate('a'); // valid.number()
const schema = d.number();
schema.validate(42); // valid
schema.validate('42'); // error.oneOf(variants: number[])
const schema = d.number().oneOf([1, 2, 3]);
schema.validate(2); // valid
schema.validate(4); // error.int()
const schema = d.number().int();
schema.validate(42); // valid
schema.validate(42.2); // error.float()
const schema = d.number().float();
schema.validate(42); // error
schema.validate(42.2); // valid.min(num: number)
const schema = d.number().min(1);
schema.validate(0); // error
schema.validate(1); // valid.max(num: number)
const schema = d.number().max(1);
schema.validate(1); // valid
schema.validate(2); // error.boolean()
const schema = d.boolean();
schema.validate(true); // valid
schema.validate(false); // valid
schema.validate(1); // error.true()
const schema = d.boolean().true();
schema.validate(true); // valid
schema.validate(false); // error.false()
const schema = d.boolean().false();
schema.validate(true); // error
schema.validate(false); // valid.date()
const schema = d.date();
schema.validate(0); // valid
schema.validate('2024-03-15T23:21:48.605Z'); // valid
schema.validate(new Date()); // valid
schema.validate(undefined); // error.min(date: DateValue)
const now = Date.now();
const schema = d.date().min(now);
schema.validate(now); // valid
schema.validate(now - 1); // error.max(date: DateValue)
const now = Date.now();
const schema = d.date().max(now);
schema.validate(now); // valid
schema.validate(now + 1); // error.null()
const schema = d.null();
schema.validate(null); // valid
schema.validate(undefined); // error.object(objschema: Record<string, Schema>)
const schema = d.object({
name: d.sting(),
});
schema.validate({name: 'alex'}); // valid
schema.validate({name: 'alex', age: 42}); // error
schema.validate({name: 42}); // errorAn object is strict by default: an unknown key is an error. Use .loose()
where a wider value is expected.
.loose()
const schema = d
.object({
name: d.sting(),
})
.loose();
schema.validate({name: 'alex'}); // valid
schema.validate({name: 'alex', age: 42}); // valid
schema.validate({name: 42}); // errorA field is optional when its own schema says so — .optional(),
.undefinable() or .nullable(), see schema. The object reads
optionality off the field, there is no separate list of optional keys.
const schema = d.object({
name: d.sting(),
nick: d.sting().optional(),
});
schema.validate({name: 'alex', nick: 'al'}); // valid
schema.validate({name: 'alex'}); // valid
schema.validate({nick: 'al'}); // error
schema.validate({name: 'alex', nick: 42}); // error.array(schemas: Schema[])
const schema = d.arrar(d.sting());
schema.validate(['hello', 'world']); // valid
schema.validate(['hello', 42]); // error.length(length: number)
const schema = d.arrar(d.sting()).length(2);
schema.validate(['hello', 'world']); // valid
schema.validate(['world']); // error.min(min_length: number)
const schema = d.arrar(d.sting()).min(2);
schema.validate(['hello', 'world']); // valid
schema.validate(['world']); // error.max(max_length: number)
const schema = d.arrar(d.sting()).max(2);
schema.validate(['hello', 'world']); // valid
schema.validate(['hello', 'world', 'foo']); // errorcreateJsonSchema(schema) turns a desy schema into a JSON Schema
(draft 2020-12). Useful when the data you are about to validate comes from an
LLM: the same schema constrains the generation and checks the answer.
import {d, createJsonSchema} from 'desy';
const schema = d
.object({
sentiment: d.string().oneOf(['positive', 'negative']),
score: d.number().int().min(1).max(5).description('From 1 to 5'),
reply: d.string().undefinable(),
})
.description('Review breakdown');
createJsonSchema(schema);{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"additionalProperties": false,
"properties": {
"sentiment": {
"type": "string",
"minLength": 1,
"enum": ["positive", "negative"]
},
"score": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "From 1 to 5"
},
"reply": {"type": "string", "minLength": 1}
},
"required": ["sentiment", "score"],
"description": "Review breakdown"
}Worth knowing:
d.string()becomesminLength: 1— an empty string is not valid in desy.additionalPropertiesis alwaysfalse,.loose()included. Strict structured outputs require it, and a schema stricter than the validator never rejects what desy accepts.- A field is in
requiredunless its schema isundefinable()— JSON has noundefined, absence is expressed byrequiredalone. nullable()becomes"type": ["string", "null"], and where the schema enumerates values,nulljoins them:oneOfgivesenum: ["a", "b", null], aconstturns intoenum: [value, null]. String and number keywords stay as they are — they do not apply tonull.oneOfbecomesenum, for strings and numbers alike..message()never reaches the schema: an error message is for a person, adescriptionis for the model.- Repeated constraints narrow instead of overwriting:
.min(2).min(5)givesminLength: 5, twooneOfintersect. A secondregexpon the same string cannot be narrowed and throws.
Five rules do not convert and throw instead of being dropped: .test(),
number().float(), date().min(), date().max() and mixed().notVoid().
Describe such a limit with .description() so the model still learns about it.
| Simple string result | Complex object result | |
|---|---|---|
| desy | x | x |
| zod | 10x | 8x |
| yup | 43x | 31x |
smaller is better