@demokit-ai/schema

OpenAPI schema parsing with relationship detection for DemoKit.

Installation

npm install @demokit-ai/schema

Features

• OpenAPI Parsing - Parse OpenAPI 3.x specifications
• Relationship Detection - Automatically detect model relationships
• Schema Normalization - Convert to DemoKit's internal schema format
• Type Inference - Infer property types and constraints
• Validation - Validate schemas against OpenAPI spec
• Full TypeScript support

Usage

Parse OpenAPI Spec

import { parseOpenAPI } from '@demokit-ai/schema'

const schema = await parseOpenAPI('./openapi.yaml')

console.log(schema.models)
// {
//   User: {
//     properties: {
//       id: { type: 'string', format: 'uuid' },
//       name: { type: 'string' },
//       email: { type: 'string', format: 'email' },
//     },
//     required: ['id', 'name', 'email'],
//   },
//   Order: { ... },
// }

console.log(schema.relationships)
// [
//   { from: { model: 'Order', field: 'userId' }, to: { model: 'User', field: 'id' }, type: 'many-to-one' },
// ]

Parse from URL

import { parseOpenAPI } from '@demokit-ai/schema'

const schema = await parseOpenAPI('https://api.example.com/openapi.json')

Parse from Object

import { parseOpenAPIObject } from '@demokit-ai/schema'

const spec = {
  openapi: '3.0.0',
  paths: { ... },
  components: {
    schemas: {
      User: { ... },
    },
  },
}

const schema = parseOpenAPIObject(spec)

Detect Relationships

import { detectRelationships } from '@demokit-ai/schema'

const models = {
  User: {
    properties: {
      id: { type: 'string' },
    },
  },
  Order: {
    properties: {
      id: { type: 'string' },
      userId: { type: 'string' },
    },
  },
}

const relationships = detectRelationships(models)
// [
//   {
//     from: { model: 'Order', field: 'userId' },
//     to: { model: 'User', field: 'id' },
//     type: 'many-to-one',
//   },
// ]

Define Schema Manually

import { defineSchema } from '@demokit-ai/schema'

const schema = defineSchema({
  models: {
    User: {
      properties: {
        id: { type: 'string', format: 'uuid' },
        name: { type: 'string', minLength: 1 },
        email: { type: 'string', format: 'email' },
        role: { type: 'string', enum: ['admin', 'user', 'guest'] },
        createdAt: { type: 'string', format: 'date-time' },
      },
      required: ['id', 'name', 'email'],
    },
    Order: {
      properties: {
        id: { type: 'string', format: 'uuid' },
        userId: {
          type: 'string',
          relationshipTo: { model: 'User', field: 'id' },
        },
        total: { type: 'number', minimum: 0 },
        status: { type: 'string', enum: ['pending', 'completed', 'cancelled'] },
      },
      required: ['id', 'userId', 'total', 'status'],
    },
  },
})

Validate Schema

import { validateSchema } from '@demokit-ai/schema'

const result = validateSchema(schema)

if (!result.valid) {
  console.error('Schema errors:', result.errors)
}

API Reference

parseOpenAPI(pathOrUrl)

Parse an OpenAPI spec from a file path or URL.

Returns: Promise<DemokitSchema>

parseOpenAPIObject(spec)

Parse an OpenAPI spec from a JavaScript object.

Returns: DemokitSchema

detectRelationships(models)

Detect relationships between models based on field naming conventions.

Returns: Relationship[]

defineSchema(options)

Define a schema manually with full type inference.

Options:

• models - Model definitions
• relationships - Explicit relationship definitions (optional)

Returns: DemokitSchema

validateSchema(schema)

Validate a schema for correctness.

Returns:

• valid - Whether schema is valid
• errors - Array of validation errors
• warnings - Array of warnings

Types

DemokitSchema

interface DemokitSchema {
  version: string
  models: Record<string, DataModel>
  relationships: Relationship[]
}

DataModel

interface DataModel {
  properties: Record<string, PropertyDef>
  required?: string[]
}

PropertyDef

interface PropertyDef {
  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object'
  name?: string
  format?: string
  enum?: unknown[]
  minimum?: number
  maximum?: number
  minLength?: number
  maxLength?: number
  pattern?: string
  nullable?: boolean
  default?: unknown
  example?: unknown
  relationshipTo?: { model: string; field: string }
  items?: PropertyDef | DataModel
}

Relationship

interface Relationship {
  from: { model: string; field: string }
  to: { model: string; field: string }
  type: 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many'
}

License

MIT