JavaScript JSON schema validation with TypeScript type inference.
npm install yrel
JavaScript JSON schema validation with TypeScript type inference.
For any ESM and CommonJS JavaScript environment. If TypeScript is used, version 4.5+ is required.
``bash`
npm i yrel
For UMD version:
`ts`
import { y, validateYrel } from 'yrel/build/umd/yrel.umd.cjs'
`html`
`html`
`ts
import { y, validateYrel } from 'yrel'
const schema = y.object({
name: y.string().min(2),
age: y.number().gte(18)
})
const data = {
name: 'yrel',
age: 21
}
const validation = validateYrel(schema, data)
console.log(validation.isValid) // true
console.log(validation.data) // { name: 'yrel', age: 21 }
console.log(validation.issues) // []
`
`ts
import { y, type InferYrel } from 'yrel'
const schema = y.object({
name: y.string().min(2).max(100),
age: y.number().gte(18).lte(150).optional(),
pets: y.array(y.string()).min(2).max(10)
})
type Schema = InferYrel
/*
{
name: string;
age?: number | undefined;
pets: string[]
}
*/
const data = {
name: 'yrel',
age: 21,
pets: ['dog', 'cat']
} satisfies Schema
`
All schemas can be optional and/or nullable.
`ts`
const schema = y.string().optional()
type Schema = InferYrel
`ts`
const schema = y.number().nullable()
type Schema = InferYrel
`ts`
const schema = y.object({
name: y.string().optional(),
age: y.number().nullable(),
is_married: y.boolean().optional().nullable()
})
type Schema = InferYrel
/*
{
name?: string | undefined
age: number | null
is_married?: boolean | undefined | null
}
*/
The methods should be called at the end of schema definition.
All schemas can be pre-processed before validation. After checking a value is
not optional nor nullable, a schema can be pre-processed to change its value
or anything required.
`ts`
const schema = y.string().preprocess((data) => String(data))
validateYrel(schema, 100) // { isValid: true, data: '100' }
All schemas can have a default value if the received data is undefined.
`ts`
const schema = y.string().defaultsTo('cat')
validateYrel(schema, undefined) // { isValid: true, data: 'cat' }
validateYrel(schema, 'dog') // { isValid: true, data: 'dog' }
It can not be used with optional schemas since it will mark it as valid and
ignore the default value.
After checking a value is not optional nor nullable, and running all defined pre-processors,
some schemas can be coerced to their data types.
`ts`
const schema = y.string().coerce()
validateYrel(schema, 100) // { isValid: true, data: '100' }
_See API for more details._
All schemas data can be transformed. When a schema is valid, the schema data can
be transformed to a new value of the same type.
`ts`
const schema = y.string().transform((data) => data.toLowerCase())
validateYrel(schema, 'ABC') // { isValid: true, data: 'abc' }
The transformed data may not be valid since validations were ran before transformation.
e.g. A schema validator for a number greater than 10 is configured and the transformation
sets the data to 5, then the data type may be still valid but it is actually invalid and
reported as valid.
`ts`
const schema = y
.number()
.gt(10)
.transform(() => 5)
validateYrel(schema, 20) // { isValid: true, data: 5 }
// It should be invalid since 5 is not greater than 10, as configured.
Yrel provides a set of validators with predefined error codes for the error report.
`ts
const schema = y.object({
name: y.string().min(2),
age: y.number().gte(18)
})
const validation = validateYrel(schema, {
name: true,
age: 12
})
console.log(validation.isValid) // false
console.log(validation.data) // undefined
console.log(validation.issues)
/*
[
{
"key": "name",
"errors": [
["err_string"]
]
},
{
"key": "age",
"errors": [
["err_number_gte", { "gte": 18 }]
]
}
]
*/
`
The report error key is a string with the path to the schema which reported
the error joined by dots. For arrays and tuples, the item index is used.
`ts
const schema = y.object({
users: y.array(
y.object({
name: y.string(),
pets: y.array(y.string())
})
)
})
const validation = validateYrel(schema, {
users: [
{ name: 'a', pets: [] },
{ name: 'b', pets: ['cat', 100, 'dog', true] }
]
})
console.log(validation.issues)
/*
[
{
"key": "users.1.pets.1",
"errors": [
["err_string"]
]
},
{
"key": "users.1.pets.3",
"errors": [
["err_string"]
]
}
]
*/
`
If the error is in the root schema, the key is an empty string.
`ts
const schema = y.string()
const validation = validateYrel(schema, 100)
console.log(validation.issues)
/*
[
{
"key": "",
"errors": [
["err_string"]
]
}
]
*/
`
A custom root key can be configured too with validateYrel(schema, data, { rootKey: 'root' }).
All schemas support the .validate(data => YrelValidation) method to add customtrue
validators. They must return either or a list of errors. Every error is tuple
with the predefined error code and the according parameters if applicable.
Validators libraries such as validator can
be used for more custom validations.
`ts
import { y, validateYrel, type YrelValidation } from 'yrel'
import isEmail from 'validator/lib/isEmail'
const validateEmail = (value: string): YrelValidation =>
isEmail(String(value)) || [['err_string_email']]
const schema = y.object({
name: y.string().min(2),
age: y.number().gte(18),
email: y.string().validate(validateEmail)
})
const validation = validateYrel(schema, {
name: 'yrel',
age: 18,
email: 'yrel@example'
})
console.log(validation.isValid) // false
console.log(validation.issues)
/*
[
{
"key": "email",
"errors": [
["err_string_email"]
]
}
]
*/
`
Yrel comes with a predefined list of error codes with possible extra parameters for
the error report. The following is a list of them. If the type to the right is undefined
it says that it does not require parameters. Otherwise, it defines the parameters types.
- err_unknown: undefined
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
One error with parameters can be the err_number_gte which requires the parametergte: number, so the report may be ['err_number_gte', { gte: 18 }].
Validators can return custom error reports. They need to be expressed as a tuple
['err_custom', string, object?].
`ts
import { y, validateYrel, type YrelValidation } from 'yrel'
// Check that the string has the format "xxx-xxx".
const validateUserId = (value: string): YrelValidation =>
/^\w{3,3}-\w{3,3}$/.test(value) || [['err_custom', 'my_custom_error_invalid_user_id']]
const schema = y.object({
id: y.string().validate(validateUserId),
name: y.string().min(2),
age: y.number().gte(18),
pets: y.array(
y.union([y.literal('dog'), y.literal('cat'), y.literal('parrot')], {
errors: [['err_custom', 'my_custom_error_invalid_pet']]
})
)
})
const validation = validateYrel(schema, {
id: 'abc-d',
name: 'yrel',
age: 18,
pets: ['cat', 'monkey', 'dog', 'fish']
})
console.log(validation.isValid) // false
console.log(validation.issues)
/*
[
{
"key": "id",
"errors": [
["err_custom", "my_custom_error_invalid_user_id"]
]
},
{
"key": "pets.1",
"errors": [
["err_custom", "my_custom_error_invalid_pet"]
]
},
{
"key": "pets.3",
"errors": [
["err_custom", "my_custom_error_invalid_pet"]
]
}
]
*/
`
If custom errors need to be reported for children elements, such as properties
of an object, the utility reportYrel can be used.
`ts
import { y, validateYrel, reportYrel } from 'yrel'
const schema = y
.object({
name: y.string(),
password: y.string(),
passwordConfirmation: y.string()
})
.validate(
(value) =>
value.password === value.passwordConfirmation ||
reportYrel({
children: [
{ key: 'password', errors: [['err_custom', 'passwords_dont_match']] },
{ key: 'passwordConfirmation', errors: [['err_custom', 'passwords_dont_match']] }
]
})
)
const validation = validateYrel(schema, {
name: 'a',
password: 'x',
passwordConfirmation: 'y'
})
console.log(validation.isValid) // false
console.log(validation.issues)
/*
[
{
"key": "password",
"errors": [
["err_custom", "passwords_dont_match"]
]
},
{
"key": "passwordConfirmation",
"errors": [
["err_custom", "passwords_dont_match"]
]
}
]
*/
`
reportYrel can also accept errors as first parameter property for the same
schema error report.
Yrel reports the validation issues with only the error codes with their
respective parameters.
A example validation use case can be:
`ts
import { y, validateYrel } from 'yrel'
const schema = y.object({
name: y.string().min(2).max(10),
age: y.number().gte(0).lte(100),
married: y.boolean().optional(),
sex: y
.union(
[y.literal('female'), y.literal('male')],
{ errors: [['err_custom', 'err_custom_sex']] } // Custom error report.
)
.optional(),
pets: y.array(y.string().nonempty().max(10)).max(3).nullable()
})
const data = {
name: 'y',
age: -1,
married: 10,
sex: 'unicorn',
pets: [true, 'unknown species']
}
const validation = validateYrel(schema, data)
`
Since the data is invalid, the following issues are reported:
`json`
[
{
"key": "name",
"errors": [["err_string_min", { "min": 2 }]]
},
{
"key": "age",
"errors": [["err_number_gte", { "gte": 0 }]]
},
{
"key": "married",
"errors": [["err_boolean"]]
},
{
"key": "sex",
"errors": [["err_custom", "err_custom_sex"]]
},
{
"key": "pets.0",
"errors": [["err_string"]]
},
{
"key": "pets.1",
"errors": [["err_string_max", { "max": 10 }]]
}
]
If they need to be presented to the end user, a tool like
Ukti can be used to translate them.
Then each issue can be mapped to their respective translation:
`ts
import { type YrelErrorTranslations } from 'yrel'
import { createUktiTranslator, type UktiTranslations } from 'ukti'
// For custom error reports.
type ErrorCustomTranslations = {
err_custom_sex: undefined
}
const translations: UktiTranslations
en: {
err_boolean: 'This field should be a boolean.',
err_number: 'A valid number is required.',
err_number_gt: 'This number should be greater than {{gt}}.',
err_number_gte: 'This number should be at least {{gte}}.',
err_number_lt: 'This number should be less than {{lt}}.',
err_number_lte: 'This number should be at most {{lte}}.',
err_string: 'This text field is required.',
err_string_min: 'The field should have at least {{min}} character{{min === 1 ? "" : "s"}}.',
err_string_max: 'The field should have at most {{max}} character{{max === 1 ? "" : "s"}}.',
// ...
err_custom_sex: 'Invalid sex.'
}
}
const translator = createUktiTranslator
translations
})
const translate = translator('en')
// Using the previous Yrel schema validation result:
if (!validation.isValid) {
validation.issues.forEach((issue) => {
issue.errors.forEach((err) => {
// Type-safety is not enforced here but should be enforced when creating
// the translation definition, since this snippet is mostly going to be used
// by libraries or app utilities once.
const errorMessage =
err[0] === 'err_custom'
? (translate[err[1] as keyof ErrorCustomTranslations] as any)(err[2])
: (translate[err[0]] as any)(err[1])
console.log(${issue.key}:, errorMessage)
})
})
}
// Logs:
// 'name: The field should have at least 2 characters.'
// 'age: This number should be at least 0.'
// 'married: This field should be a boolean.'
// 'sex: Invalid sex.'
// 'pets.0: This text field is required.'
// 'pets.1: The field should have at most 10 characters.'
`
See Ukti for more details on translations.
Schemas with custom data types can be created with the general schema .any.
`ts
const schema = y
.any<'cat' | 'dog'>()
.validate((data) => data === 'cat' || data === 'dog' || [['err_custom', 'not_a_pet']])
type Schema = InferYrel
validateYrel(schema, 'cat') // { isValid: true }
validateYrel(schema, 'dolphin') // { isValid: false }
`
`ts
import { y, isYrel } from 'yrel'
const fakeSchema = {}
const validSchema = y.string()
console.log(isYrel(fakeSchema)) // false
console.log(isYrel(validSchema)) // true
`
Any kind of value.
`ts`
const schema = y.any() // any
Boolean values.
`ts`
const schema = y.boolean() // boolean
#### .coerce()
Force the data input value to Boolean(input) before validation.
`ts`
const schema = y.boolean().coerce()
validateYrel(schema, 0) // { isValid: true, data: false }
validateYrel(schema, '') // { isValid: true, data: false }
validateYrel(schema, 100) // { isValid: true, data: true }
validateYrel(schema, 'abc') // { isValid: true, data: true }
validateYrel(schema, {}) // { isValid: true, data: true }
#### .truthy()
Only true values.
Numeric and finite numbers.
`ts`
const schema = y.number() // number
#### .coerce()
Force the data input value to Number(input) before validation. Date objects.getTime()
are coerced with .
`ts`
const schema = y.number().coerce()
validateYrel(schema, true) // { isValid: true, data: 1 }
validateYrel(schema, '100') // { isValid: true, data: 100 }
validateYrel(schema, new Date()) // { isValid: true, data: 1695336434720 }
#### .gt(value: number)
A number greater than the defined value.
#### .gte(value: number)
A number greater than or equal to the defined value.
#### .lt(value: number)
A number less than the defined value.
#### .lte(value: number)
A number less than or equal to the defined value.
#### .integer()
A safe integer number.
A string value.
`ts`
const schema = y.string() // string
To validate an optional non-empty string validation, it can be done like this:
`ts`
const schema = y.union([y.string().date(), y.literal('')])
validateYrel(schema, '2000-10-10') // valid
validateYrel(schema, '') // valid
#### .coerce()
Force the data input value to String(input) before validation. Date objects.toISOString()
are coerced with .
`ts`
const schema = y.string().coerce()
validateYrel(schema, true) // { isValid: true, data: 'true' }
validateYrel(schema, 100) // { isValid: true, data: '100' }
validateYrel(schema, new Date()) // { isValid: true, data: '2023-09-21T22:46:09.059Z' }
#### .nonempty()
Non empty string.
#### .trim()
A string without spaces at the beginning or end.
#### .length(value: number)
A string with specified length.
#### .min(value: number)
A string with at least the specified length.
#### .max(value: number)
A string with at most the specified length.
#### .datetime(value: number)
A valid datetime string in ISO 8601 format. e.g.:
`ts`
'2050-10-25T14:45:30Z'
'2050-10-25T14:45:30.3Z'
'2050-10-25T14:45:30.37Z'
'2050-10-25T14:45:30.370Z'
#### .date(value: number)
A valid date string fragment of the ISO 8601 format. e.g. 2050-10-25.
#### .time(value: number)
A valid time string fragment of the ISO 8601 format. e.g.:
`ts`
'14:45:30'
'14:45:30.3'
'14:45:30.37'
'14:45:30.370'
#### .lowercase()
A string in lowercase.
#### .uppercase()
A string in uppercase.
#### .capitalcase(conf?: { lower?: boolean })
A string in capital case. By default, it allows any uppercase characters such as Abc Def
or . If .capitalcase({ lower: true }) is defined, it will only accept lowercaseAbc Def
chactaters for non-first word letters such as .
A literal primitive value.
`ts`
const schema = y.literal('cat') // 'cat'
An array of the specified schema.
`ts`
const schema = y.array(y.string()) // string[]
#### .nonempty()
Non empty arrays.
#### .length(value: number)
An array of the specified length.
#### .min(value: number)
An array of at least the specified length.
#### .max(value: number)
An array of at most the specified length.
A value that matches one of the specified schemas.
`ts`
const schema = y.union([y.number(), y.literal('cat'), y.literal('dog'), y.literal('parrot')])
// number | 'cat' | 'dog' | 'parrot'
For dynamically created union of literals, the dynamic types can be set like:
`ts
import { type YrelSchemaLiteral } from 'yrel'
type Languages = 'en' | 'es' | 'fr' | 'hi' | 'zh'
const languages: Languages[] = ['en', 'es', 'fr', 'hi', 'zh']
const schema = y.union<[YrelSchemaLiteral
languages.map((lang) => y.literal(lang)) as [
YrelSchemaLiteral
YrelSchemaLiteral
]
)
type Schema = InferYrel
`
Or using a custom type with y.any.
An array with fixed number of elements and each of them with a specific data schema.
`ts`
const schema = y.tuple([y.number(), y.string(), y.boolean().optional()])
// [number, string, boolean | undefined]
A plain object and each property with the specified data schema.
`ts`
const schema = y.object({
name: y.string(),
age: y.number()
})
// { name: string; age: number; }
#### .shape
The object shape structure.
#### .passthrough()
By default the object data schema will report an error if the validated object contains
unexpected properties which are not defined in the schema shape. This will allow such
properties.
A plain object with a not specified number of properties. All object keys have to be
string with y.string().
`ts`
const schema = y.record(y.string(), y.number())
// { [key: string]: number }
To validate the record key:
`ts
const schema = y.record(y.string().date(), y.boolean())
// { [name: string]: boolean }
validateYrel(schema, { '2000': true, '2001': false }) // invalid
validateYrel(schema, { '2000-10-10': true, '2000-10-11': false }) // valid
``
The Yrel logo is an illustration
of the character Yrel in the game
World of Warcraft from the awesome illustrator
@KuridelBlack. Check out her work at
linktr.ee/kuridelblack.