JSON Schema Validation Skill

Validate data at all boundaries using JSON Schema definitions with AJV runtime validation.

When to Use

• Creating API endpoints that accept user input

• Validating form submissions server-side

• Ensuring data integrity before database writes

• Defining contracts between services

• Generating TypeScript types from schemas

Schema File Location

Schemas live in /schemas/ directory with this structure:

schemas/ common/ # Shared/reusable schemas uuid.schema.json error-response.schema.json pagination.schema.json entities/ # Domain entity schemas user.schema.json # Full entity user.create.schema.json # Create input (no id/timestamps) user.update.schema.json # Partial update (all optional) api/ # API-specific request schemas login.schema.json register.schema.json

Schema Naming Convention

Pattern Example Purpose

{entity}.schema.json

user.schema.json

Full entity with all fields

{entity}.create.schema.json

user.create.schema.json

Create input (no id, no timestamps)

{entity}.update.schema.json

user.update.schema.json

Partial update (all fields optional)

{context}.schema.json

login.schema.json

Context-specific schemas

Schema Authoring

Basic Schema Template

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "entities/user.create", "title": "Create User", "description": "Schema for creating a new user", "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "User's email address" }, "password": { "type": "string", "minLength": 8, "maxLength": 128, "description": "User's password (8-128 characters)" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "User's display name" } }, "additionalProperties": false }

Key Attributes

Attribute Purpose

$id

Unique identifier for referencing (e.g., "entities/user.create")

required

Array of mandatory field names

additionalProperties: false

Reject unknown fields (security)

minProperties: 1

For update schemas - require at least one field

Common Validation Keywords

String Validation:

{ "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-z0-9-]+$", "format": "email" }

Number Validation:

{ "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }

Enum Validation:

{ "type": "string", "enum": ["draft", "active", "archived"], "default": "draft" }

Nullable Fields:

{ "type": ["string", "null"], "maxLength": 2000 }

Available Formats

AJV with ajv-formats supports:

• email

• Email address

• uri

• Full URI

• uuid

• UUID v4

• date

• ISO date (YYYY-MM-DD)

• date-time

• ISO datetime

• time

• ISO time

• ipv4 , ipv6

• IP addresses

• hostname

• Hostname

Custom formats (defined in validator.js):

• phone

• E.164 phone format (+1234567890)

• slug

• URL-safe identifier (lowercase, hyphens)

Using Validation Middleware

Import and Apply

import { validateBody, validateQuery, validateParams } from './middleware/validate.js';

// Validate request body app.post('/api/users', validateBody('entities/user.create'), createUser );

// Validate query parameters app.get('/api/items', validateQuery('api/list-items'), listItems );

// Validate path parameters app.get('/api/users/:id', validateParams('common/uuid-param'), getUser );

// Combined validation app.patch('/api/users/:id', validateParams('common/uuid-param'), validateBody('entities/user.update'), updateUser );

Error Response Format

Validation failures return:

{ "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": [ { "path": "/email", "message": "Invalid email format", "keyword": "format" }, { "path": "/password", "message": "Must be at least 8 characters", "keyword": "minLength" } ] } }

Status codes:

• 422

• Body validation failed

• 400

• Query or params validation failed

Validating in Services

For validation outside middleware (e.g., before database writes):

import { validate } from '../api/middleware/validate.js';

async function createUser(data) { // Validate before database insert (defense in depth) validate(data, 'entities/user.create');

// Proceed with insert... const result = await query(userQueries.create, [data.email, data.name]); return result.rows[0]; }

Query Parameter Coercion

Query strings are always strings. The middleware automatically coerces:

Schema Type Input Result

integer

"20"

20

boolean

"true"

true

array

"a,b,c"

["a", "b", "c"]

Example query schema:

{ "$id": "api/list-items", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "offset": { "type": "integer", "minimum": 0, "default": 0 }, "status": { "type": "string", "enum": ["draft", "active", "archived"] } }, "additionalProperties": false }

Generating TypeScript Types

Generate .d.ts files from schemas for JSDoc type checking:

npm run generate:types

How It Works

The script uses json-schema-to-typescript to convert JSON Schema files into TypeScript declaration files:

• Reads all .schema.json files from /schemas/

• Generates corresponding .d.ts files in src/types/generated/

• Types can be imported in JSDoc comments for type checking

Generated Structure

src/types/generated/ common/ uuid.d.ts error-response.d.ts pagination.d.ts entities/ user.d.ts user.create.d.ts user.update.d.ts api/ login.d.ts register.d.ts

Using Generated Types

Import types in JSDoc comments:

/**

• @typedef {import('./types/generated/entities/user.create').UserCreate} CreateUserInput
• @typedef {import('./types/generated/entities/user').User} User */

/**

• Create a new user
• @param {CreateUserInput} data - User creation data
• @returns {Promise<User>} Created user */ async function createUser(data) { validate(data, 'entities/user.create'); // data has full type information from schema const result = await db.query(userQueries.create, [data.email, data.password, data.name]); return result.rows[0]; }

Regenerating Types

Run npm run generate:types whenever schemas are updated to keep types in sync.

Aligning with Database Constraints

Schema validations should mirror database constraints:

Database Constraint JSON Schema Equivalent

NOT NULL

Include in required array

UNIQUE

Validate in service layer (not schema)

CHECK (status IN ('a', 'b'))

"enum": ["a", "b"]

VARCHAR(255)

"maxLength": 255

CHECK (amount > 0)

"minimum": 1 (exclusive: "exclusiveMinimum": 0 )

OpenAPI Integration

Reference schemas from OpenAPI spec:

openapi.yaml

paths: /users: post: requestBody: required: true content: application/json: schema: $ref: './schemas/entities/user.create.schema.json' responses: '201': content: application/json: schema: $ref: './schemas/entities/user.schema.json' '422': $ref: '#/components/responses/ValidationError'

Type Checking with tsc

The project uses tsc --checkJs for type checking JavaScript files with JSDoc annotations.

Running Type Check

npm run typecheck

Requirements

Type checking requires:

• npm install to install @types packages

• Files must have JSDoc type annotations

jsconfig.json Configuration

{ "compilerOptions": { "checkJs": true, "strict": true, "skipLibCheck": true, "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext" }, "include": ["src//*.js", "test//*.js"], "exclude": ["node_modules"] }

Template Syntax Handling

Files containing template syntax ({{VARIABLE}} ) are processed at project creation time and should be excluded from type checking until the project is generated.

In starter templates:

• Files like config/index.js contain {{PROJECT_NAME}} placeholders

• These are valid JavaScript after template processing

• Type checking runs correctly after npm install in a generated project

Common Type Patterns

// Import Express types /**

• @typedef {import('express').Request} Request
• @typedef {import('express').Response} Response
• @typedef {import('express').NextFunction} NextFunction */

// Type middleware parameters /**

• @param {Request} req
• @param {Response} res
• @param {NextFunction} next */ export function myMiddleware(req, res, next) { // ... }

// Import schema types (after npm run generate:types) /**

• @typedef {import('./types/generated/entities/user.create').UserCreate} CreateUserInput */

Best Practices

• Single source of truth - Schema defines validation, types, and docs

• Strict by default - Always use additionalProperties: false

• Descriptive error messages - Use description on every property

• Defense in depth - Validate at API boundary AND before database writes

• Align with database - Schema constraints should match CHECK constraints

• Generate, don't duplicate - Use npm run generate:types for TypeScript

• Add JSDoc types - All exported functions should have parameter and return types

Related Skills

• rest-api

• API endpoint patterns and HTTP status codes

• error-handling

• Custom error classes including ValidationError

• forms

• Client-side HTML5 validation (UX layer)

• security

• Input sanitization and output encoding

• typescript-author

• TypeScript patterns and Zod alternative