adapt-schemas

A standalone JSON Schema library for the Adapt framework stack. Load schemas from plugin folders via glob patterns and validate JSON data with automatic defaults application via AJV.

Installation

npm install adapt-schemas

Quick Start

import Schemas from 'adapt-schemas'

// Create and initialize the library
const library = new Schemas()
library.init()

// Load schemas from plugin directories
library.loadSchemas('**/schema/*.schema.json', {
  cwd: './plugins',
  ignore: ['**/node_modules/**']
})

// Validate data against a schema (defaults are applied automatically)
const validatedData = library.validate('course', {
  title: 'My Course'
})

API Reference

Schemas

Constructor Options

const library = new Schemas({
  enableCache: true,              // Enable schema build caching (default: true)
  xssWhitelist: {},               // Custom XSS whitelist tags/attributes
  xssWhitelistOverride: false,    // Replace defaults instead of extending
  formatOverrides: {}             // Custom string format RegExp patterns
})

Methods

init()

Initializes the library and loads the base schema.

library.init()

loadSchemas(patterns, options)

Loads schemas from directories matching glob patterns.

library.loadSchemas('**/schema/*.schema.json', {
  cwd: './plugins',           // Base directory for patterns
  ignore: ['**/excluded/**']  // Patterns to exclude
})

// Multiple patterns
library.loadSchemas([
  'core/**/schema/*.schema.json',
  'plugins/**/schema/*.schema.json'
], { ignore: ['**/node_modules/**'] })

registerSchema(filePath, options)

Registers a single schema file.

library.registerSchema('/path/to/schema.json', {
  replace: false  // Replace existing schema with same name
})

getSchema(schemaName, options)

Retrieves and builds a schema by name.

const schema = library.getSchema('course', {
  useCache: true,        // Use cached build if available
  compile: true,         // Compile the schema
  applyExtensions: true  // Apply $patch extensions
})

getBuiltSchema(schemaName)

Returns the built schema object.

const schemaObj = library.getBuiltSchema('course')
console.log(schemaObj.properties)

validate(schemaName, data, options)

Validates data against a named schema.

const validated = library.validate('course', inputData, {
  useDefaults: true,     // Apply schema defaults (default: true)
  ignoreRequired: false  // Ignore required field errors
})

getSchemaNames()

Returns list of all registered schema names.

const names = library.getSchemaNames()
// ['base', 'course', 'content', 'component', ...]

getSchemaInfo()

Returns information about all registered schemas.

const info = library.getSchemaInfo()
// { course: { filePath: '...', extensions: [...], isPatch: false } }

extendSchema(baseSchemaName, extSchemaName)

Manually extends a schema with another.

library.extendSchema('course', 'my-course-extension')

addKeyword(definition, options)

Adds a custom AJV keyword.

library.addKeyword({
  keyword: 'isPositive',
  type: 'number',
  validate: (schema, data) => data > 0
})

// Override an existing keyword
library.addKeyword({
  keyword: 'isPositive',
  type: 'number',
  validate: (schema, data) => data >= 0
}, { override: true })

deregisterSchema(name)

Removes a schema from the registry.

library.deregisterSchema('my-schema')

addStringFormats(formats)

Adds custom string format validators.

library.addStringFormats({
  'phone': /^\+?[\d\s-]+$/
})

Events

The library extends EventEmitter and emits the following events:

library.on('initialized', () => { })
library.on('reset', () => { })
library.on('schemasLoaded', (schemaNames) => { })
library.on('schemaRegistered', (name, filePath) => { })
library.on('schemaDeregistered', (name) => { })
library.on('schemaExtended', (baseName, extName) => { })
library.on('warning', (message) => { })

Schema Format

Basic Schema with Inheritance

Schemas use $merge to inherit from a parent schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$anchor": "content",
  "$merge": {
    "source": { "$ref": "base" },
    "with": {
      "properties": {
        "title": {
          "type": "string",
          "default": ""
        },
        "body": {
          "type": "string",
          "default": ""
        }
      },
      "required": ["title"]
    }
  }
}

Patch Schema (Extensions)

Use $patch to extend an existing schema without creating a new one:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$anchor": "course-trickle-extension",
  "$patch": {
    "source": { "$ref": "course" },
    "with": {
      "properties": {
        "_globals": {
          "type": "object",
          "properties": {
            "_trickle": {
              "type": "object",
              "properties": {
                "incompleteContent": {
                  "type": "string",
                  "default": "There is incomplete content above"
                }
              }
            }
          }
        }
      }
    }
  }
}

Custom Keywords

The library includes these custom AJV keywords:

Keyword	Description	Example
isBytes	Parses byte strings	"1MB" → 1048576
isDate	Parses date strings	"2024-01-01" → Date
isTimeMs	Parses duration strings	"7d" → 604800000
isObjectId	Marks ObjectId fields	No transformation

Error Handling

The library throws SchemaError with the following codes:

Code	Description
INVALID_PARAMS	Invalid method parameters
SCHEMA_EXISTS	Schema with same name already registered
SCHEMA_LOAD_FAILED	Failed to read/parse schema file
INVALID_SCHEMA	Schema fails JSON Schema validation
MISSING_SCHEMA	Requested schema not found
VALIDATION_FAILED	Data fails schema validation
KEYWORD_EXISTS	Keyword already defined
MODIFY_PROTECTED_ATTR	Attempt to modify internal/read-only field

import { SchemaError } from 'adapt-schemas'

try {
  library.validate('course', data)
} catch (e) {
  if (e instanceof SchemaError) {
    console.log(e.code)    // 'VALIDATION_FAILED'
    console.log(e.data)    // { schemaName, errors, data }
  }
}

License

MIT