Skip to content

Choose the right JSON schema to apply to your routes based on your constraints


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



22 Commits

Repository files navigation


Build Status npm JavaScript Style Guide

Choose the right JSON schema to apply to your routes based on your constraints. With this plugin, you will be able to set multiple schemas per route and, programmatically, choose which one applies.

Ex: you can choose which JSON schema to apply, based on the req.headers values.


npm install fastify-schema-constraint


Plugin version Fastify version
^1.0.0 ^2.0.0
^2.0.0 ^3.0.0
^3.0.0 ^4.0.0


This plugin will act on preHandler hook and will verify if the payload of the body, querystring, params or headers fulfil the constraint condition.

// Define the set of your JSON Schema. They MUST be in an array assigned to `oneOf` property
const routeSchema = {
  oneOf: [
    { $id: '#schema1', type: 'object', properties: { mul5: { type: 'number', multipleOf: 5 } } },
    { $id: '#schema2', type: 'object', properties: { mul3: { type: 'number', multipleOf: 3 } } },
    { $id: '#schema3', type: 'object', properties: { mul2: { type: 'number', multipleOf: 2 } } }

// Define your constraint logic
const constraint = {
  body: {
    constraint: function (request) {
        case 1: return '#schema1'
        case 2: return '#schema3'
        case 3: return '#schema2'
        default: return null // it means "don't apply any constraint"
    statusCode: 412, // Optionally define a custom status code in case of errors
    errorMessage: 'This constraint return only #schema1' // Optionally define a custom error message
  querystring: { ... },
  params: { ... },
  headers: { ... }

const fastify = Fastify()
fastify.register(require('fastify-schema-constraint'), constraint)
  url: '/:mul5',
  method: 'POST',
  handler: (_, reply) => { reply.send('hi') },
  schema: {
    body: routeSchema,
    querystring: routeSchema,
    params: routeSchema,
    headers: routeSchema


The options accept a json in this format:

const constraint = {
  body: { ... }, // constraint to apply on body
  querystring: { ... }, // constraint to apply on query string
  params: { ... }, // constraint to apply on path parameters
  headers: { ... } // constraint to apply on headers

All the fields are optional, but you must provide almost one of these settings. If you provide a constraint for body, but the route doesn't have any schema configured the plugin will skip the constraint.

Each constraint field accepts a json in this format:

  constraint: function (request) {
    // This field is mandatory and must be set with a function.
    // The input paramenter is the Fastify request.
    // This function must be sync and must return a string with the JSON Schema $id to constraint
    return '#idToApply'
  statusCode: 412, // Optionally: set a custom status code in case of errors, default 400
  errorMessage: 'This constraint return only #idToApply' // Optionally: set a custom error message


  • if the constraint function returns something different than a string, the validation will be skipped!
  • if the constraint function throws an error, an error will be thrown
  • if the returned $id isn't present in the oneOf array an error will be thrown
  • if the payload verified doesn't match with the returned $id, an error will be thrown


Copyright Manuel Spigolon, Licensed under MIT.


Choose the right JSON schema to apply to your routes based on your constraints




Code of conduct




Sponsor this project



No packages published