Schema Validation

Provide a JSON Schema and Shim will validate and coerce types during repair.

Why Use Schemas

Without a schema, Shim only fixes syntax (brackets, commas, markdown fences). With a schema, Shim also:

Coerces types ("30" → 30)
Detects missing required fields
Removes extra fields (strict mode)
Validates nested objects

Basic Schema

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  },
  required: ['name', 'age']
};

const result = await shim.repair({
  raw_output: '{"name": "John", "age": "30"}',
  schema
});

// result.repaired: { name: "John", age: 30 }
// Shim coerced "30" to 30

Type Coercion

Shim coerces types when safe:

From	To	Example
`"30"`	`30`	String to number
`"true"`	`true`	String to boolean
`30`	`"30"`	Number to string
`true`	`"true"`	Boolean to string

Unsafe coercions are rejected:

"abc" → number (not a valid number)
"maybe" → boolean (not "true" or "false")

Required Fields

Mark fields as required:

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    email: { type: 'string' }
  },
  required: ['name', 'email']
};

const result = await shim.repair({
  raw_output: '{"name": "John"}',
  schema
});

// result.success: false
// result.metadata.errors: [{ code: 'MISSING_REQUIRED_FIELD', field: 'email' }]

Strict vs Lenient Mode

Strict Mode (default)

Removes extra fields not in schema:

const result = await shim.repair({
  raw_output: '{"name": "John", "age": 30, "email": "[email protected]"}',
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      age: { type: 'number' }
    }
  },
  mode: 'strict'  // Default
});

// result.repaired: { name: "John", age: 30 }
// email was removed

Lenient Mode

Keeps extra fields:

const result = await shim.repair({
  raw_output: '{"name": "John", "age": 30, "email": "[email protected]"}',
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      age: { type: 'number' }
    }
  },
  mode: 'lenient'
});

// result.repaired: { name: "John", age: 30, email: "[email protected]" }
// email was kept

Nested Objects

Validate nested structures:

const schema = {
  type: 'object',
  properties: {
    user: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        age: { type: 'number' }
      },
      required: ['name']
    }
  }
};

const result = await shim.repair({
  raw_output: '{"user": {"name": "John", "age": "30"}}',
  schema
});

// result.repaired: { user: { name: "John", age: 30 } }

Arrays

Validate array items:

const schema = {
  type: 'object',
  properties: {
    tags: {
      type: 'array',
      items: { type: 'string' }
    }
  }
};

const result = await shim.repair({
  raw_output: '{"tags": ["ai", "llm", 123]}',
  schema
});

// result.repaired: { tags: ["ai", "llm", "123"] }
// 123 was coerced to "123"

Enums

Restrict values to specific options:

const schema = {
  type: 'object',
  properties: {
    status: {
      type: 'string',
      enum: ['active', 'inactive', 'pending']
    }
  }
};

const result = await shim.repair({
  raw_output: '{"status": "active"}',
  schema
});

// result.success: true

const invalid = await shim.repair({
  raw_output: '{"status": "unknown"}',
  schema
});

// invalid.success: false
// invalid.metadata.errors: [{ code: 'ENUM_MISMATCH', field: 'status' }]

Default Values

Shim does NOT add default values. If a field is missing and not required, it stays missing. Use your application logic to add defaults after repair.

Schema Repairs in Metadata

All schema repairs are logged:

const result = await shim.repair({
  raw_output: '{"name": "John", "age": "30"}',
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      age: { type: 'number' }
    }
  }
});

console.log(result.metadata.schema_repairs);
// [
//   {
//     type: 'type_coercion',
//     confidence: 'high',
//     safe: true,
//     field: 'age',
//     original_value: '30',
//     repaired_value: 30
//   }
// ]

Best Practices

Start with lenient mode during development
Switch to strict mode in production (prevents data leakage)
Mark critical fields as required
Use enums for status fields
Review metadata.schema_repairs if confidence is "medium" or "low"

Next Steps

Batch Endpoint

API reference for batch repair

Response Object

Full response schema

Error Handling

Handle validation failures

TypeScript SDK

Use the official SDK

Getting Started

Guides

Concepts

API Reference

SDKs

Migration

Schema Validation

Schema Validation

Why Use Schemas

Basic Schema

Type Coercion

Required Fields

Strict vs Lenient Mode

Strict Mode (default)

Lenient Mode

Nested Objects

Arrays

Enums

Default Values

Schema Repairs in Metadata

Best Practices

Next Steps

Batch Endpoint

Response Object

Error Handling

TypeScript SDK

​Schema Validation

​Why Use Schemas

​Basic Schema

​Type Coercion

​Required Fields

​Strict vs Lenient Mode

​Strict Mode (default)

​Lenient Mode

​Nested Objects

​Arrays

​Enums

​Default Values

​Schema Repairs in Metadata

​Best Practices

​Next Steps

Batch Endpoint

Response Object

Error Handling

TypeScript SDK

Schema Validation

Why Use Schemas

Basic Schema

Type Coercion

Required Fields

Strict vs Lenient Mode

Strict Mode (default)

Lenient Mode

Nested Objects

Arrays

Enums

Default Values

Schema Repairs in Metadata

Best Practices

Next Steps