Skip to main content

​
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:
FromToExample
"30"30String to number
"true"trueString 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

  1. Start with lenient mode during development
  2. Switch to strict mode in production (prevents data leakage)
  3. Mark critical fields as required
  4. Use enums for status fields
  5. 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