ajv vs json-schema-to-ts: Runtime Safety vs Compile-Time Types

Both ajv and json-schema-to-ts help developers work with JSON Schema in TypeScript projects, but they operate at completely different stages of the development lifecycle and solve different problems. Confusing them is common — one validates data while your app runs, the other generates types while you write code. Let’s clarify when and how to use each.

🔍 Core Purpose: What Problem Does Each Solve?

ajv is a runtime validator. It takes a JSON Schema and an actual JavaScript object, then checks whether the object matches the schema. If not, it tells you why — useful for handling real-world data that might not match expectations.

import Ajv from 'ajv';

const ajv = new Ajv();
const schema = {
  type: 'object',
  properties: { name: { type: 'string' }, age: { type: 'number' } },
  required: ['name']
};

const validate = ajv.compile(schema);
const valid = validate({ name: 'Alice', age: 30 });
console.log(valid); // true

const invalid = validate({ age: 'thirty' });
console.log(invalid); // false
console.log(validate.errors); // detailed error info

json-schema-to-ts is a type generator. It reads a JSON Schema (usually as a const assertion in TypeScript) and produces a corresponding TypeScript type. No validation happens at runtime — it’s purely for static analysis during development.

import { FromSchema } from 'json-schema-to-ts';

const userSchema = {
  type: 'object',
  properties: { name: { type: 'string' }, age: { type: 'number' } },
  required: ['name']
} as const;

type User = FromSchema<typeof userSchema>;
// User is now equivalent to: { name: string; age?: number }

// This gives a TypeScript error at compile time:
const badUser: User = { age: 'thirty' }; // ❌ Property 'name' is missing

⚙️ When to Use Which? Real Engineering Scenarios

Scenario 1: Validating API Responses from a Third-Party Service

You’re calling an external REST API that returns user data. You don’t control the response format, and it might change unexpectedly.

• ✅ Use ajv: Because you need to verify the shape of incoming data at runtime before using it in your app. TypeScript types alone won’t protect you if the server sends malformed JSON.

// Runtime check with ajv
if (!validate(response)) {
  throw new Error(`Invalid API response: ${ajv.errorsText(validate.errors)}`);
}
// Safe to use response.name, etc.

• ❌ Don’t rely only on json-schema-to-ts: Even if you generate a User type, the actual response might not match it. You’d get no runtime protection.

Scenario 2: Building an Internal Microservice with Schema-First Design

Your team defines all data contracts using JSON Schema files. Frontend and backend share these schemas, and you want TypeScript interfaces auto-generated from them.

• ✅ Use json-schema-to-ts: To avoid manually writing and maintaining duplicate TypeScript interfaces. Changes to the schema automatically update your types.

// Shared schema → auto-generated type
const apiResponseSchema = { /* ... */ } as const;
type ApiResponse = FromSchema<typeof apiResponseSchema>;

• ✅ Also consider ajv: If you still want to validate data at service boundaries (e.g., validating requests entering your backend), use both tools together.

🔄 Can They Be Used Together?

Yes — and often should be. A common pattern in professional apps:

1. Use json-schema-to-ts to generate TypeScript types from your canonical JSON Schemas.
2. Use ajv to validate actual runtime data against those same schemas.

This gives you both compile-time type safety and runtime validation.

import Ajv from 'ajv';
import { FromSchema } from 'json-schema-to-ts';

const userSchema = {
  type: 'object',
  properties: { id: { type: 'number' }, email: { type: 'string', format: 'email' } },
  required: ['id', 'email']
} as const;

type User = FromSchema<typeof userSchema>;

// Compile-time: TypeScript enforces correct structure
const newUser: User = { id: 1, email: 'test@example.com' };

// Runtime: ajv validates actual data (e.g., from fetch)
const ajv = new Ajv({ strict: false });
const validate = ajv.compile(userSchema);

fetch('/api/user')
  .then(res => res.json())
  .then(data => {
    if (!validate(data)) {
      console.error('Invalid user data:', validate.errors);
      return;
    }
    // Now safe to treat `data` as User
    processUser(data);
  });

🧪 Error Handling and Developer Experience

ajv provides detailed, customizable error messages. You can even add your own keywords or formats (like format: 'uuid'). This is critical for debugging production issues or giving users meaningful form feedback.

// Custom format support in ajv
ajv.addFormat('uuid', /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);

json-schema-to-ts has no runtime behavior, so there’s nothing to “handle” at runtime. Its DX benefit is catching mismatches before you run the code. For example, if you forget a required field, TypeScript fails the build.

📦 Bundle Impact and Performance

• ajv adds to your bundle size because it includes a full validation engine. However, it supports tree-shaking and standalone code generation to minimize this.
• json-schema-to-ts adds zero runtime cost. The entire package is dev-only; its output is pure TypeScript types that vanish after compilation.

If you’re building a lightweight frontend where every KB counts and you fully trust your data sources, json-schema-to-ts alone may suffice. But if you handle untrusted input (user forms, third-party APIs), skipping runtime validation is risky.

🛑 Maintenance Status

As of the latest official documentation:

• ajv is actively maintained, with stable support for JSON Schema Draft 7, 2019-09, and 2020-12 via plugins.
• json-schema-to-ts is also actively maintained and compatible with modern TypeScript versions. It correctly handles complex schema constructs like oneOf, anyOf, and recursive references.

Neither package is deprecated.

💡 Final Guidance

• Need to check real data while your app runs? → ajv
• Want TypeScript types that match your schema without manual upkeep? → json-schema-to-ts
• Working on a serious application with external data sources? → Use both

Don’t treat them as competitors — they’re complementary tools in a mature frontend architecture. One guards your runtime, the other sharpens your development experience.