Ajv × JTD: Get Typedefs and its Validator at the Same Time

This article has been translated from the original article by the author himself using DeepL translator. Thanks, www.deepl.com !

TL; DR

1. Introduce Ajv JSON Validator
2. and adopt JSON Typed Definition
3. Cross-platform typed definitions and validators at your fingertips!

Note: This article you reading has been written with reference to this page.

Introduction

It is adopted as a common standard for both the front-end and the back-end, and is universally understandable and writable by many people ―――

In programming, data structures can take many forms, depending on their use; e.g. CSV / XML / YAML / TOML. While there are many examples of these, none are as widespread or as easily understood by everyone as JSON. It is often used for human reading and writing, as well as for client-server interaction.

On the other hand, its flexibility also makes it difficult to handle safely: When communicating with an arbitrary API server and receiving data, it's common to give up defining type of the response and treat it as any type. In this way, the data can be received, but the subsequent handling will be difficult.

This is when you want a validator, a device that verifies and guarantees the correctness of your data. Validators can be used to detect and successfully handle property excess or deficiency and invalid values.

Of course, it's possible to code it yourself from scratch, for the sake of experience, but we'd rather use a framework that already exists ! In this article, introducing Ajv as a JSON validator library for JavaScript / TypeScript. I would also show you how to define a innovative schema, called JSON Typed Definition.

Note: JSON Typed Definition is proposed in RFC8927 and its current status is Experimental.

What is Ajv ?

Before you start with Ajv ...

On JTD, the schema is defined using eight different forms e.g. Properties / Elements / Values etc.. If you would like to know more about these first, please see this article.

• Learn JSON Typedef in 5 Minutes | JSON Typedef Docs

Getting started with Ajv on JTD

So let's get started with Ajv!

First of all, we need to install the npm package:

npm install ajv
# or
yarn add ajv

Before you can actually validate in Ajv, you need to go through the following steps:

1. define your schema on JSON Typed Definition
2. get the type definition from the schema object by using "utility types"
3. initialize the Ajv() constructor (and do some configurations)
4. get a validator (+ $\alpha$ ) from the type definition

Let's look at them in turn!

1. Define your schema on JSON Typed Definition

First, here is an example of a schema definition on JSON Typed Deifinition.

const schema = {
  properties: {
    foo: { type: "int32" },
  },
  optionalProperties: {
    bar: { type: "string" },
  },
} as const;

Some of you may have noticed as const at the end of the code. This feature is called const assertion, implemented since TypeScript 3.4.

// Type '"hello"'
let x = "hello" as const;
// Type '{ readonly text: "hello" }'
let z = { text: "hello" } as const;
// Type 'readonly [10, 20]'
let y = [10, 20] as const;

Thanks to this feature, the schema is cast as follows:

const schema: {
  readonly properties: {
    readonly foo: {
      readonly type: "int32";
    };
  };
  readonly optionalProperties: {
    readonly bar: {
      readonly type: "string";
    };
  };
};

All properties are now readonly, and each type property is now defined as a literal ("int32", "string") instead of string; !

2. Get the type definition from the schema object by using "utility types"

Now, we have the variable schema, which is type-asserted via as const. What if we further apply the typeof operator to this variable? It is also used in type guards, which are often used to determine undefined; that is, the typeof operator is used to get the type of a variable schema.

type MyData = JTDDataType<typeof schema>;

Next, typeof schema is passed as an argument to JTDataType<T>, which is provided by the Ajv as utility types .

Utility types are types that derive another type from a type; if functions are functions in the runtime world, then utility types are functions in the type world.
cf. book.yyts.org

That is, JTDataType<T> convert from the argument typeof schema to MyData. At this point, this type definition has been cast as follows:

type MyData = {
  foo: number;
} & {
  bar?: string | undefined;
};

🤔?🤔?🤔?🤔?🤔?🤔?🤔?🤔?🤔?🤔?🤔?🤔?

＿人人人人人人人人人人人人人人人人人人＿
＞ When we defined the schema in JTD, ＜
￣Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y￣

＿人人人人人人人人人人人人人人人人人人人人＿
＞ we also finished defining the TS typedefs! ＜
￣Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y^Y￣

3. Initialize the Ajv() constructor (and do some configurations)

Let's calm down for a moment and think about the following ...

// import Ajv from "ajv"; // <----- not for JTD
import Ajv from "ajv/dist/jtd";
const ajv = new Ajv();

Here, we import the necessary modules and initialize the constructor. Note that the source of this import is ajv/dist/jtd, since JTD is used. If you want to add more settings, you can pass Option as an argument to the constructor.

/*
* For example, to report all validation errors (rather than failing on the first errors)
* you should pass allErrors option to constructor:
*/
const ajv = new Ajv({allErrors: true})

4. Get validator and + $\alpha$ from the type definition

The compile constructor method can be used to convert a schema definition into a validator function.

// type inference is not supported for JTDDataType yet
const validate = ajv.compile<MyData>(schema);

What a surprise! 🤣 Just by defining the schema on JTD, we got a TypeScript typedef and a validator that uses it.

const validData = {
  foo: 1,
  bar: "abc",
};

if (validate(validData)) {
  // data is MyData here
  console.log(validData.foo); // 1
} else {
  console.log(validate.errors);
}

This is the beauty of Ajv on JTD. The amount of writing is much less, just like the goal of Write less code.

And there's more good news! Ajv also provide compileParser and compileSerializer to meet the demand for a "more type-safe" parser and serializer. In other words, we can now do JSON.parse() / JSON.stringfy() in a more type-safe way.

const parse = ajv.compileParser<MyData>(schema);
const serialize = ajv.compileSerializer<MyData>(schema);

const data = {
  foo: 1,
  bar: "abc",
};

const invalidData = {
  unknown: "abc",
};

console.log(serialize(data));
console.log(serialize(invalidData)); // type error

const json = '{"foo": 1, "bar": "abc"}';
const invalidJson = '{"unknown": "abc"}';

console.log(parseAndLogFoo(json)); // logs property
console.log(parseAndLogFoo(invalidJson)); // logs error and position

function parseAndLogFoo(json: string): void {
  const data = parse(json); // MyData | undefined
  if (data === undefined) {
    console.log(parse.message); // error message from the last parse call
    console.log(parse.position); // error position in string
  } else {
    // data is MyData here
    console.log(data.foo);
  }
}

Excellent!

JSON Typed Definition Validator

"OK, I'll give JTD a go!", this thought occurred to me at the end of last month. However, at the time, I had no idea how to define scheme on JSON Typed Definition. I even tried to translate the official explanations into my native language to get a better understanding, but it didn't feel quite right. Or, to start with, it was bad for me because I didn't know if the schema definition was correct or not until I actually ran the code.

🤮

I couldn't just give up here, so I decided to build my own webApp using Next.js, which I've been working on a lot lately.

Please try it! And I would love it if you gave me a star or something! 🥳

Conclusion

So far, we have actually done the following two things:

1. Schema definition based on JSON Typed Definition
2. Initial configuration of Ajv

Here's what we got out of these:

1. typedefs in TypeScript derived from JTD
2. type-safe Validator based on 1.
3. type-safe Parser based on 1.
4. type-safe Serializer based on 1.

Haha! After all the hard work and effort in the past, we can now get """everything""" just by defining the schema on JTD. 🥲

I hope you enjoy the best schema-driven development tomorrow with JSON Typed Definition and Ajv JSON Validator! 👍