Skip to main content
Version: 0.7.0 (Previous)

📤 Response Schemas

Response schemas provide JSON Schema definitions for standardized API response structures and error handling across Nodeblocks applications. These schemas ensure consistent response formatting and error reporting.

🎯 Overview​

Response schemas are designed to:

  • Standardize API responses across all endpoints
  • Validate error response structures for consistent error handling
  • Ensure success response consistency with proper data formatting
  • Support audit logging for entity changes and user actions
  • Enable composition with entity-specific response schemas

📋 Response Schema Types​

Error Response Schemas​

Schemas for standardized error response structures.

Success Response Schemas​

Schemas for standardized success response structures.

Audit Schemas​

Schemas for audit logging and tracking entity changes.

🔧 Available Response Schemas​

errorSchema​

Error response schema for standardized API error responses.

Purpose: Validates error response structure across API endpoints

Schema Details:

  • Type: object
  • Required Fields: code, message
  • Additional Properties: false (strict validation)
  • Properties:
    • code: string - Error code identifier
    • message: string - Human-readable error message
    • details?: object - Additional error details (optional)

Usage:

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

const { errorSchema } = schemas;
const validate = ajv.compile(errorSchema.schemas as SchemaDefinition);
const isValid = validate({
  code: 'VALIDATION_ERROR',
  message: 'Invalid input data',
  details: { field: 'email', issue: 'Invalid format' }
});

successSchema​

Success response schema for standardized API success responses.

Purpose: Validates success response structure across API endpoints

Schema Details:

  • Type: object
  • Required Fields: message
  • Additional Properties: false (strict validation)
  • Properties:
    • message: string - Success message
    • data?: object - Response data (optional)

Usage:

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

const { successSchema } = schemas;
const validate = ajv.compile(successSchema.schemas as SchemaDefinition);
const isValid = validate({
  message: 'User created successfully',
  data: { identityId: '123', email: 'user@example.com' }
});

auditSchema​

Audit logging schema for tracking entity changes and user actions.

Purpose: Validates audit trail records for system changes

Schema Details:

  • Type: object
  • Required Fields: id, entity_type, entity_id, action, user_id, created_at
  • Additional Properties: false (strict validation)
  • Properties:
    • id: string - Audit record ID (UUID format)
    • entity_type: string - Type of entity being audited
    • entity_id: string - ID of the entity being audited (UUID format)
    • action: "create" | "update" | "delete" - Action performed
    • user_id: string - ID of user performing the action (UUID format)
    • created_at: string - Timestamp of the action (date-time format)
    • changes?: object - Object containing the changes made (optional)

Usage:

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

const { auditSchema } = schemas;
const validate = ajv.compile(auditSchema.schemas as SchemaDefinition);
const isValid = validate({
  id: '550e8400-e29b-41d4-a716-446655440000',
  entity_type: 'user',
  entity_id: '550e8400-e29b-41d4-a716-446655440001',
  action: 'update',
  user_id: '550e8400-e29b-41d4-a716-446655440002',
  created_at: '2023-01-01T00:00:00Z',
  changes: { name: { from: 'John', to: 'Jane' } }
});