A TypeScript-first approach to defining JSON Schemas for use with AJV.

Overview

AJV is a powerful JSON Schema validator, but creating schemas directly in JavaScript or TypeScript can be verbose and error-prone. This package, @raminy/ajv-ts-schema, bridges the gap by allowing you to define schemas using TypeScript decorators, making your schemas type-safe and reusable.

Features

• Type-Safe Validation: Leverages TypeScript for safer, cleaner schema definitions.
• Decorator-Based: Simplifies schema creation with class and property decorators.
• AJV Integration: Easily compile and validate schemas using AJV.
• Schema Reusability: Use defined schemas for validation, request processing, and more.

Installation

npm install @raminy/ajv-ts-schema

Or if you use yarn:

yarn add @raminy/ajv-ts-schema

Enable decorators in your tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

If you are a contributor and wnat to clone and run on your local

Make sure Husky will run properly by running these commands from the root of the project:

chmod +x .husky/pre-commit
chmod +x .husky/_/husky.sh

Then run:

yarn
yarn test # or 'yarn test:ui'

Quick Start

Define your schema using decorators:

import { AjvObject, AjvProperty, AjvSchema } from "@raminy/ajv-ts-schema";

@AjvObject()
class MySchema extends AjvSchema {
  @AjvProperty({ type: "number", required: true })
  foo!: number;

  @AjvProperty({ type: "string", nullable: true })
  bar?: string | null;
}

const schema = MySchema.getSchema();

Validate with AJV:

import Ajv from "ajv/dist/2020";
import addFormats from "ajv-formats";
import { AjvSchema, type AjvJsonSchema } from "@raminy/ajv-ts-schema";

const ajv = new Ajv({ useDefaults: true });
addFormats(ajv);
const validate = ajv.compile(schema); // 'schema' comes from 'MySchema.getSchema()'

const myFunction = (input: any) => {
  if (!validate(input)) {
    console.error(validate.errors);
  }

  // 'fromJson' returns and instance of 'MySchema'
  const typedSchema = AjvSchema.fromJson<MySchema>(MySchema, input);
};

// or you can do this instead

const isMySchema = (input: any): input is AjvJsonSchema<MySchema> => {
  return validate(input);
};

const myFunction = (input: any) => {
  if (!isMySchema(input)) {
    console.error(validate.errors);
  }

  // for the rest of the code 'input' is of type 'AjvJsonSchema<MySchema>'
  // which is a JSON object
};

Key Advantages

• Code Completion: Enhanced development experience with IDE suggestions.
• Error Prevention: Catch issues at compile-time rather than runtime.
• Reusability: Convert validated JSON objects into typed instances using fromJson.

Documentation

• Full documentation and examples: Documentation
• NPM Package: @raminy/ajv-ts-schema
• JSON Schema Reference: AJV Docs

Contributing

Contributions are welcome! Please submit issues or pull requests on the GitHub Repository.