npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@kitmi/jsonv

v1.3.0

Published

JSON Validation Syntax

Downloads

191

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: Invoking Jsv.match(value, null) will always return true. It means the jsv is null, nothing to validate. To explicitly match null, 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 to true, throws an error when validation fails.
  • abortEarly: If set to true, stops validation on the first failure.
  • plainError: If set to true, returns a plain error message instead of an error object.
  • asPredicate: If set to true, 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