Schema System Overview

Learn about Feathers schema system for type-safe data validation and transformation with JSON Schema and TypeBox

The Feathers schema system provides a powerful, type-safe approach to data validation and transformation. It uses JSON Schema for validation and offers seamless integration with TypeBox for TypeScript type inference.

Key Concepts

The schema system consists of three main components:

1. Schema Definition

   Define your data structure using JSON Schema or TypeBox. Schemas provide type safety and validation.

2. Validation

   Automatically validate incoming data against your schema using AJV validators.

3. Resolvers

   Transform and resolve data properties, including virtual properties and secure data handling.

Installation

Install the required packages:

npm

npm install @feathersjs/schema @feathersjs/typebox

yarn add @feathersjs/schema @feathersjs/typebox

pnpm add @feathersjs/schema @feathersjs/typebox

Basic Schema Definition

Using JSON Schema

Define schemas using standard JSON Schema format:

import { schema, FromSchema } from '@feathersjs/schema'

const userSchema = schema({
  $id: 'User',
  type: 'object',
  additionalProperties: false,
  required: ['email'],
  properties: {
    email: { type: 'string' },
    password: { type: 'string' }
  }
} as const)

// Infer TypeScript type from schema
type User = FromSchema<typeof userSchema>

Using TypeBox

TypeBox provides a more TypeScript-friendly API:

import { Type } from '@feathersjs/typebox'
import { getValidator } from '@feathersjs/typebox'
import { Ajv } from '@feathersjs/schema'

const userSchema = Type.Object({
  email: Type.String(),
  password: Type.String(),
  age: Type.Optional(Type.Number())
})

const validator = getValidator(userSchema, new Ajv())

Schema Validation

Schemas can automatically validate and coerce data:

Basic Validation

const messageSchema = schema({
  $id: 'message',
  type: 'object',
  required: ['text', 'read'],
  additionalProperties: false,
  properties: {
    text: { type: 'string' },
    read: { type: 'boolean' },
    upvotes: { type: 'number' }
  }
} as const)

// Validates and coerces types
const message = await messageSchema.validate({
  text: 'hello',
  read: 0,        // Coerced to false
  upvotes: '10'   // Coerced to 10
})
// Result: { text: 'hello', read: false, upvotes: 10 }

Validation Errors

try {
  await messageSchema.validate({ text: 'failing' })
} catch (error) {
  // BadRequest error with detailed validation errors
  console.error(error.data)
  // [{
  //   instancePath: '',
  //   keyword: 'required',
  //   message: "must have required property 'read'",
  //   params: { missingProperty: 'read' },
  //   schemaPath: '#/required'
  // }]
}

Custom AJV

import Ajv from 'ajv'
import addFormats from 'ajv-formats'

const customAjv = new Ajv({
  coerceTypes: true,
  addUsedSchema: false
})
addFormats(customAjv)

const userSchema = schema({
  $id: 'User',
  type: 'object',
  properties: {
    email: { type: 'string', format: 'email' },
    createdAt: { type: 'string', format: 'date-time' }
  }
} as const, customAjv)

Query Syntax

Create schemas for Feathers query syntax with operators like $gt, $lt, $in:

import { querySyntax } from '@feathersjs/typebox'
import { Type, Static } from '@feathersjs/typebox'

const messageSchema = Type.Object({
  text: Type.String(),
  userId: Type.Number()
})

const messageQuerySchema = querySyntax(messageSchema)

type MessageQuery = Static<typeof messageQuerySchema>

// Valid queries
const query: MessageQuery = {
  userId: { $gt: 10, $in: [20, 30] },
  text: 'hello',
  $select: ['text', 'userId'],
  $sort: { userId: 1 },
  $limit: 10,
  $skip: 0
}

Type Inference

The schema system provides full TypeScript type inference:

import { Infer, schema } from '@feathersjs/schema'
import { Type, Static } from '@feathersjs/typebox'

// With JSON Schema
const jsonSchema = schema({
  $id: 'Example',
  type: 'object',
  properties: {
    name: { type: 'string' }
  }
} as const)

type JsonType = Infer<typeof jsonSchema>

// With TypeBox
const typeboxSchema = Type.Object({
  name: Type.String()
})

type TypeBoxType = Static<typeof typeboxSchema>

Schema Extension

Extend existing schemas to create new ones:

const userDataSchema = schema({
  $id: 'UserData',
  type: 'object',
  required: ['email'],
  properties: {
    email: { type: 'string' },
    password: { type: 'string' }
  }
} as const)

// Extend with additional properties
const userSchema = schema({
  $id: 'User',
  type: 'object',
  required: ['id', ...userDataSchema.definition.required],
  properties: {
    ...userDataSchema.definition.properties,
    id: { type: 'number' },
    createdAt: { type: 'string' }
  }
} as const)

Next Steps

Data Validation

Learn how to validate data in hooks and services

Schema Resolvers

Transform data with resolvers and virtual properties