fastify-ata

Fastify plugin for ata-validator - JSON Schema validation powered by simdjson.

Drop-in replacement for Fastify's default ajv validator. Standard Schema V1 compatible.

npm install fastify-ata

const fastify = require('fastify')()
const fastifyAta = require('fastify-ata')

fastify.register(fastifyAta)

fastify.post('/user', {
  schema: {
    body: {
      type: 'object',
      properties: {
        name: { type: 'string', minLength: 1 },
        age: { type: 'integer', minimum: 0 },
        role: { type: 'string', default: 'user' }
      },
      required: ['name']
    }
  }
}, (req, reply) => {
  // req.body.role === 'user' (default applied)
  reply.send({ ok: true, name: req.body.name })
})

fastify.listen({ port: 3000 })

All your existing JSON Schema route definitions work as-is.

Write plain JSON Schema and get typed route handlers, no builder DSL. Add the AtaTypeProvider and author schemas with defineSchema:

import Fastify from 'fastify'
import fastifyAta from 'fastify-ata'
import { defineSchema } from 'ata-validator'

const app = Fastify().withTypeProvider<fastifyAta.AtaTypeProvider>()
await app.register(fastifyAta)

app.post('/user', {
  schema: {
    body: defineSchema({
      type: 'object',
      properties: { name: { type: 'string' }, age: { type: 'integer' } },
      required: ['name'],
    }),
  },
}, (req, reply) => {
  req.body.name // string
  req.body.age  // number | undefined
  reply.send({ ok: true })
})

defineSchema preserves the schema's literal types, so request.body, request.query, request.params, and request.headers are inferred from the schema. Same idea as @fastify/type-provider-typebox, from plain JSON Schema.

ata-validator falls back to a pure-JS engine where the native addon is not available (Cloudflare Workers, browsers, Bun), so fastify-ata runs in those environments too.

If you prefer a chainable builder over JSON Schema literals, ata-validator/t emits the same plain JSON Schema under the hood, so route schemas, the type provider, and the AOT path all keep working without an adapter. The migration from TypeBox is one import rename:

import Fastify from 'fastify'
import fastifyAta from 'fastify-ata'
import { t } from 'ata-validator/t'

const app = Fastify().withTypeProvider<fastifyAta.AtaTypeProvider>()
await app.register(fastifyAta)

const Body = t.object({
  name: t.string({ minLength: 1 }),
  age: t.integer({ minimum: 0 }),
  email: t.optional(t.string({ format: 'email' })),
  role: t.union([t.literal('admin'), t.literal('user')]),
})

app.post('/users', { schema: { body: Body } }, (req, reply) => {
  req.body.name    // string
  req.body.email   // string | undefined
  req.body.role    // 'admin' | 'user'
  reply.send({ ok: true })
})

Defaults mirror Fastify's stock validator: coerceTypes: 'array' (path params and querystring values arrive as strings and coerce to the schema types, single-element arrays collapse for querystrings) and removeAdditional: true (properties outside the schema are stripped, not rejected). Override either to opt out:

fastify.register(fastifyAta, {
  coerceTypes: false,       // reject "42" for integer fields instead of coercing
  removeAdditional: false,  // 400 on properties outside the schema
  abortEarly: true,         // skip detailed error collection (faster invalid path)
  prettyErrors: true,       // 400 message carries the ATA code + a did-you-mean
})

With prettyErrors, a failed request returns a compiler-style message instead of the plain ajv text:

body must have required property 'name' [ATA7001] (did you mean `name` instead of `nme`?)

Off by default to keep the ajv-compatible message shape.

abortEarly replaces the error list with a shared stub. Good for public endpoints where only the accept/reject decision reaches the caller. On a 10-property schema the invalid path drops from roughly 15 ns/op to 3.7 ns/op.

fastify.register(fastifyAta) sets the validator compiler in the context it is registered into. Register it on the root instance and it applies everywhere; register it inside a plugin and only that subtree uses ata, while the rest of the app keeps the default validator. Use this when you want ata for some routes and the default for others, or when you are adding ata to an existing app without touching the server construction.

If you want ata to be the validator for the whole server, pass the compiler factory at construction time instead. This is the same schemaController.compilersFactory.buildValidator hook that @fastify/ajv-compiler and joi-compiler use, so the default ajv validator is never built.

const Fastify = require('fastify')
const AtaCompiler = require('fastify-ata/compiler')

const app = Fastify({
  schemaController: { compilersFactory: { buildValidator: AtaCompiler() } },
})

app.post('/user', {
  schema: {
    body: {
      type: 'object',
      properties: { name: { type: 'string' }, age: { type: 'integer' } },
      required: ['name'],
    },
  },
}, (req, reply) => reply.send({ ok: true }))

The factory mirrors @fastify/ajv-compiler: it defaults to Fastify's own ajv behavior (coerceTypes: 'array', removeAdditional: true, first error only) and reads addSchema registrations for cross-schema $ref. Override through customOptions:

buildValidator: AtaCompiler() // defaults match Fastify's ajv
// per-instance overrides are read from ajv.customOptions, e.g.:
const app = Fastify({
  ajv: { customOptions: { coerceTypes: false, allErrors: true } },
  schemaController: { compilersFactory: { buildValidator: AtaCompiler() } },
})

Note on memory: this replaces the ajv validator, so it is never instantiated. The ajv module itself can still be pulled into the process by Fastify's serializer (fast-json-stringify uses it to check serialization schemas), independent of which validator you choose. Replacing the validator removes ajv from the request validation path, not necessarily from the module graph.

Drop-in replacement for @fastify/ajv-compiler/standalone. Same API.

const StandaloneValidator = require('fastify-ata/standalone')

// Build phase (once) - compile schemas to JS files
const app = fastify({
  schemaController: { compilersFactory: {
    buildValidator: StandaloneValidator({
      readMode: false,
      storeFunction(routeOpts, code) {
        fs.writeFileSync(generateFileName(routeOpts), code)
      }
    })
  }}
})

// Read phase (every startup) - load pre-compiled, near-zero compile time
const app = fastify({
  schemaController: { compilersFactory: {
    buildValidator: StandaloneValidator({
      readMode: true,
      restoreFunction(routeOpts) {
        return require(generateFileName(routeOpts))
      }
    })
  }}
})

ata-validator natively implements Standard Schema V1 - the emerging standard for TypeScript-first schema libraries.

const { Validator } = require('ata-validator')
const v = new Validator(schema)

// Standard Schema V1 interface
const result = v['~standard'].validate(data)
// { value: data } on success
// { issues: [{ message, path }] } on failure

Works with Fastify v5's Standard Schema support, tRPC, TanStack Form, Drizzle ORM.

• Registers a custom validatorCompiler using ata-validator
• Applies default values, coerceTypes, removeAdditional during validation
• Caches compiled schemas (WeakMap) for reuse across routes
• Returns Fastify-compatible validation errors on invalid requests (400)
• Works with Fastify v4 and v5

All numbers below are reproducible on M4 Pro / Node 25 with the benchmarks in this repo and in ata-validator/benchmark. Run-to-run noise is roughly +/- 5% at these scales.

bench-realtime.js reports about 15% more requests per second than ajv on a 50-route app whose handlers do nothing. That number is reproducible and it is also misleading, so here is the whole picture. Sweeping the route count, echo handlers, 50 connections:

The gap is not a property of the validator, it is a dispatch effect that appears once there are enough distinct compiled validators to spoil V8's call-site caching and disappears again once there are many. Give the handler real work and it goes away entirely, one route, 50 to 200 connections:

profile-fastify.mjs explains why: in one request JSON.parse is 92% of the cost and validation 7%. If your handler touches a database, the validator is not what decides your throughput. Switch for the boot numbers below, or for the errors, types and portability. Do not switch for requests per second.

Schema compilation at boot, from bench-startup.js. Each figure is the median of nine process-isolated runs with a no-route Fastify baseline subtracted, so what is left is the cost of compiling the route schemas and nothing else.

Total boot time, baseline included, is 83.6 ms against 583.9 ms at 1000 routes. Below about 20 routes the difference is under measurement noise and not worth quoting.

Fastify's documented route to the fastest startup is @fastify/ajv-compiler in standalone mode: compile every route schema to a file at build time, load the files at boot. The table is process start to app.ready(), five schema types reused across routes, median of three runs.

Past about 200 routes, installing ata and doing nothing else boots faster than ajv with the build step in place: 59 ms against 81 ms at 500 routes. Precompiling with fastify-ata/standalone takes another 20% off, but it is an optimization rather than the thing that makes the difference. Under 100 routes the four are close enough that boot time should not decide anything.

Boot cost is the scenario that matters for Vercel, Fly.io and similar platforms, where a process starts far more often than a long-running box does. On a box that stays up, the gap is paid once.

For browser / edge deployments, ata ships an ata compile CLI that turns a JSON Schema into a self-contained .mjs plus TypeScript declarations.

npx ata compile schemas/user.json -o src/user.validator.mjs --name User

A 10-field schema produces:

Generated file has zero runtime dependency on ata-validator. isValid is emitted as a TypeScript type predicate, so consumers get narrowing out of the box.

• RE2 regex - linear-time guaranteed, immune to catastrophic backtracking
• simdjson - SIMD-accelerated JSON parsing for buffer-input paths
• Multi-core - countValid(ndjsonBuf) validates many messages in one native call
• Standard Schema V1 - native support, works with Fastify v5, tRPC, TanStack Form, Drizzle
• Draft 2020-12 and Draft 7 - every applicable draft 2020-12 case in the official JSON Schema Test Suite passes with the native engine installed (1190/1190); 99.8% pure JS
• Fastify's own suite - 178 of 184 tests pass with ata as the default validator; the remaining six test the default validator's private extension API rather than validation behaviour. See compat/COMPATIBILITY.md

MIT