🔍 Schema

A schema defines and validates the shape of incoming request data. Nodeblocks relies on JSON Schema Draft-07 and validates at runtime via AJV. Schemas are defined with the withSchema primitive.

There is no schema registration API — withSchema returns a SchemaComposer that transforms a ServiceDefinition. Schemas are exported from src/schemas/ and paired with routes in features via compose(schema, route).

Import schemas via the single namespace export:

import { schemas } from '@nodeblocks/backend-sdk';

---

🔍 What is a Schema?

withSchema returns a SchemaComposerWithSchema — a function (service: ServiceDefinition) => ServiceDefinition. It sets service.withNextRoute, a hook that wraps the next route's handler with validation when withRoute registers that route.

Schema lifecycle

schemas/*.ts  →  features/*.ts  →  services/*.ts  →  defService()
  (withSchema)     (compose schema + route)         (serve)

1. Define — export withSchema(...) from src/schemas/<domain>.ts
2. Pair with route — compose(schema, route) in src/features/<domain>.ts (schema must come first)
3. Bundle — combine features in a service factory
4. Serve — mount with defService

See Feature » and Route » for how schemas attach to routes.

For HTTP routes, schema validation runs inside the wrapped handler before business logic. Invalid HTTP requests throw NodeblocksError with status 400. Legacy JSON Schema composers also support WebSocket message validation, but OpenAPI composers are intended for HTTP routes.

---

📐 Schema vs Validators

Two layers run before handler logic:

Layer	Purpose	Defined via
Schema	Validates request shape (path, query, body fields)	withSchema in features
Validators	Business-logic checks (auth, existence, permissions)	validators on withRoute

Schema validation is injected via withNextRoute when the route is registered. Route validators run separately in defService before the handler chain. See Validator » for business-logic checks beyond schema validation.

---

📐 OpenAPI Mode (recommended)

Pass an OpenAPI operation object with parameters and/or requestBody. This is the primary pattern in SDK schemas:

import { primitives } from '@nodeblocks/backend-sdk';

const { withSchema } = primitives;

export const identityIdPathParameter: primitives.OpenAPIParameter = {
  in: 'path',
  name: 'identityId',
  required: true,
  schema: { type: 'string' },
};

export const getIdentitySchema = withSchema({
  parameters: [{ ...identityIdPathParameter }],
});

export const updateIdentitySchema = withSchema({
  parameters: [{ ...identityIdPathParameter }],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          type: 'object',
          additionalProperties: false,
          properties: {
            email: { type: 'string' },
            emailVerified: { type: 'boolean' },
            typeId: { type: 'string' },
          },
        },
      },
    },
    required: true,
  },
});

Reusable parameter constants (like identityIdPathParameter) are shared across schemas within a domain module.

OpenAPI validation scope

Behavior	Detail
Supported locations	path and query only — read from params.requestParams / params.requestQuery
Header/cookie params	The OpenAPIParameter type includes header and cookie, but the validator does not read headers or cookies. Do not rely on header validation via withSchema
Path params	Always treated as required
Query strictness	Undefined query keys are rejected (query parameter 'X' is not allowed)
Request body	Validated only for POST, PUT, PATCH, DELETE — not GET
Content type	Defaults to application/json; falls back to the first content entry
WebSocket routes	Use legacy JSON Schema mode for WebSocket message validation; OpenAPI mode is for HTTP routes

---

📐 Legacy JSON Schema Mode

Pass a JSON Schema object (or multiple schemas to merge) to validate request body only:

export const createItemSchema = withSchema({
  type: 'object',
  additionalProperties: false,
  properties: {
    name: { type: 'string' },
    status: { type: 'string' },
  },
  required: ['name', 'status'],
});

Pass multiple JSON Schema arguments to deep-merge them:

withSchema(baseSchema, extensionSchema);

Legacy WebSocket support

Legacy composers validate inbound WebSocket messages for protocol: 'ws' routes. The validator strips emitterId (added by defService) before checking the message against the schema. OpenAPI mode does not support WebSocket validation.

---

📋 Field Requirements

The required array determines which properties must be present:

withSchema({
  type: 'object',
  properties: {
    productId: { type: 'string' },
    rating: { type: 'number', minimum: 1, maximum: 5 },
  },
  required: ['productId', 'rating'],
});

For OpenAPI request bodies, set required: true on the requestBody object when the body itself is mandatory.

---

🔒 Default Schema Enhancements

The SDK applies applyDefaultSchemaEnhancements recursively to object schemas:

• additionalProperties: false — blocks undefined fields unless you override
• queryFilter: true — protects against MongoDB injection in nested object schemas

withSchema({
  type: 'object',
  additionalProperties: true, // explicitly allow extra fields
  properties: {
    name: { type: 'string' },
  },
});

---

⚠️ Validation Errors

When validation fails, withSchema throws NodeblocksError(400, 'Validation Error', 'withSchema', errors) before the handler runs.

OpenAPI mode — messages prefixed by location:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'email'",
      "path parameter 'identityId' is required",
      "query parameter 'page' is not allowed"
    ]
  }
}

Legacy mode — validates request body only. Error messages use raw AJV output without the request body prefix (e.g. "must have required property 'name'").

---

🔧 Reading Schema Definitions

getSchemaDefinition (legacy only)

import { primitives } from '@nodeblocks/backend-sdk';

const { getSchemaDefinition } = primitives;

const merged = getSchemaDefinition(legacySchemaComposer);

Works only on legacy JSON Schema composers that expose a .schema property. Calling it on an OpenAPI composer throws — read schemaComposer.openapi instead.

---

📦 SDK Schema Modules

Schemas are organized by domain in the SDK schemas namespace, matching src/schemas/index.ts:

Module	Description	Reference
Address	Address lookup schemas	SDK only — docs pending
Attributes	Attribute management schemas	Attribute Schemas »
Authentication	Auth and token schemas	Authentication Schemas »
Avatar	Avatar structure schemas	Avatar Schemas »
Category	Category CRUD schemas	Category Schemas »
Chat	Chat channel and message schemas	Chat Schemas »
Common	Shared schemas (pagination, etc.)	Used across domains
File Storage	File upload schemas	File Storage Schemas »
Identity	Identity lifecycle schemas	Identity Schemas »
Invitation	Invitation schemas	Invitation Schemas »
Location	Location management schemas	Location Schemas »
Notification	Notification schemas	SDK only — docs pending
OAuth	OAuth flow schemas	OAuth Schemas »
Order	Order management schemas	Order Schemas »
Organization	Organization schemas	Organization Schemas »
Product	Product management schemas	Product Schemas »
Profile	Profile schemas	Profile Schemas »

---

➡️ Next

Learn about Validator » for business-logic checks, Feature » for pairing schemas with routes, or Route » for handler chains.