@kitmi/jsonv
v1.3.0
Published
JSON Validation Syntax
Downloads
191
Maintainers
Readme
@kitmi/jsonv
JSON Validation (JSV) Syntax
The JSON Validation Syntax is a specification for validating JSON-like data structures. It allows users to define validation rules using a JSON-like syntax and provides mechanisms to validate data against these rules. This document outlines the syntax rules used for validation within the JSV framework.
Installation
To install @kitmi/jsonv
, run the following command:
bun install @kitmi/jsonv
Or if you're using npm:
npm install @kitmi/jsonv
Syntax Rules
Basic Validation
- Equality (
$eq
or$equal
): Checks if the value is equal to the specified value. - Inequality (
$ne
or$neq
or$notEqual
): Checks if the value is not equal to the specified value. - Greater Than (
$gt
or$greaterThan
): Checks if the value is greater than the specified value. - Greater Than or Equal (
$gte
or$greaterThanOrEqual
or$min
): Checks if the value is greater than or equal to the specified value. - Less Than (
$lt
or$lessThan
): Checks if the value is less than the specified value. - Less Than or Equal (
$lte
or$lessThanOrEqual
or$max
): Checks if the value is less than or equal to the specified value. - Exists (
$exists
): Checks if the value exists (is not null or undefined). - Required (
$required
): Checks if the value is present and not null or undefined.
Advanced Validation
- Match (
$match
): Validates the value against all specified validation rules. - Match Any (
$any
or$or
or$either
): Validates the value against any of the specified validation rules. - All Match (
$allMatch
or|>$all
or|>$match
): Checks if all elements in an array satisfy the specified validation rule. - Any One Match (
$anyOneMatch
or|*$any
or|*$match
or|*$either
): Checks if at least one element in an array satisfies the specified validation rule. - Type (
$typeOf
): Checks if the value is of the specified type. - Has Keys (
$hasKey
or$hasKeys
): Checks if the object has all the specified keys. - Start With (
$startWith
or$startsWith
): Checks if the string value starts with the specified substring. - End With (
$endWith
or$endsWith
): Checks if the string value ends with the specified substring. - Match Pattern (
$pattern
or$matchPattern
or$matchRegex
): Checks if the string value matches the specified regular expression pattern. - Contains (
$contain
or$contains
): Checks if the string value contains the specified substring. - Same As (
$sameAs
): Checks if the value is the same as the value of the specified field in the parent object.
Use Expression as Operand
Use { $expr: } to wrap the value as a JSX expression
{
"$if": [
{ "$expr": ["$parent.type", { "$match": { "$eq": "array" } }] }, // use an expression as condition
[
// then
{ "$required": true },
[{ "type": { "$in": ["text", "integer"] } }]
]
// else
]
}
Special Cases
- Validation with
null
: InvokingJsv.match(value, null)
will always returntrue
. It means the jsv is null, nothing to validate. To explicitly matchnull
, use{ $exist: false }
. - Validation with Array: Using
Jsv.match(value, [ ... ])
will validate the value against all JSV objects in the array. To check for equality with an array, use{ $eq: [ ... ] }
. To check whether the value matches one of the element in the array, use{ $in: [ ... ] }
.
Context Variables
$root
: Represents the root value being validated.$this
: Represents the current value being validated.$parent
: Represents the parent object of the current value being validated.$key
: Represents the current key being validated.
Validation Options
throwError
: If set totrue
, throws an error when validation fails.abortEarly
: If set totrue
, stops validation on the first failure.plainError
: If set totrue
, returns a plain error message instead of an error object.asPredicate
: If set totrue
, returns a boolean result instead of throwing an error or returning an error message.
Usage Examples
import Jsv from '@kitmi/jsonv/bundle'; // bundled with multi-lang messages
// Validate that 'key1' is greater than 1000
Jsv.match(obj, { key1: { $gt: 1000 } });
// Validate that 'key4' does not exist
Jsv.match(obj, { key4: { $exists: false } });
// Validate that 'key8' has all specified keys: 'name', 'type'
Jsv.match(obj, { key8: { $hasKeys: ['name', 'type'] } });
Specific locale only
import Jsv from '@kitmi/jsonv';
import En from '@kitmi/jsonv/locale/en';
Jsv.config.loadMessages('en-US', En).setLocale('en-US');
Jsv.match(...);
Note that the JSV framework is designed to be extensible and can be customized with additional validation rules and operators as needed. The syntax rules outlined in this document represent the core set of validation capabilities provided by the JSV framework.
License
- MIT
- Copyright (c) 2023 KITMI PTY LTD