Data Schema Validation Issues

What This Means

Schema validation ensures that data exchanged between systems conforms to expected structures, types, and constraints. Schema validation failures occur when:

• API requests/responses don't match expected schemas
• Data types are incorrect or missing required fields
• Invalid data causes integration failures
• Version mismatches between API schema versions
• Malformed JSON, XML, or other data formats
• Constraint violations (length, range, format)

These issues are common in API integrations, data pipelines, form submissions, and third-party service connections.

How to Diagnose

API Response Validation

// Check for validation errors in API responses
fetch('https://api.example.com/v1/resource', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(data)
})
  .then(response => {
    if (response.status === 400) {
      return response.json().then(error => {
        console.error('Schema validation failed:', error.message);
        console.error('Validation errors:', error.errors);
      });
    }
    return response.json();
  });

Common Error Responses

• 400 Bad Request - Schema validation failure
• Error messages like "Missing required field", "Invalid type", "Format error"

Validation Tools

# Validate JSON against JSON Schema
npm install ajv

import Ajv from 'ajv';

const ajv = new Ajv();
const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    email: { type: 'string', format: 'email' },
    age: { type: 'number', minimum: 0 }
  },
  required: ['name', 'email']
};

const validate = ajv.compile(schema);
const valid = validate(data);

if (!valid) {
  console.error('Validation errors:', validate.errors);
}

Check API Documentation

• Review API schema documentation
• Check required vs optional fields
• Verify data types and formats
• Look for version-specific schema changes

General Fixes

1. Implement client-side validation - Validate before sending to API

   import Ajv from 'ajv';
   import addFormats from 'ajv-formats';
   
   const ajv = new Ajv();
   addFormats(ajv);
   
   const schema = {
     type: 'object',
     properties: {
       email: { type: 'string', format: 'email' },
       age: { type: 'integer', minimum: 18, maximum: 120 },
       website: { type: 'string', format: 'uri' }
     },
     required: ['email']
   };
   
   function validateData(data) {
     const validate = ajv.compile(schema);
     const valid = validate(data);
   
     if (!valid) {
       throw new Error(JSON.stringify(validate.errors, null, 2));
     }
   
     return true;
   }
   

2. Use TypeScript for type safety - Catch schema issues at compile time

   interface User {
     name: string;
     email: string;
     age: number;
     role?: 'admin' | 'user';
   }
   
   function createUser(data: User) {
     // TypeScript ensures data matches User interface
     return fetch('/api/users', {
       method: 'POST',
       body: JSON.stringify(data)
     });
   }
   

3. Generate types from schemas - Use tools to auto-generate types

   # Generate TypeScript types from JSON Schema
   npm install json-schema-to-typescript
   json2ts -i schema.json -o types.ts
   

4. Version your schemas - Track schema changes and handle multiple versions

   const schemas = {
     'v1': schemaV1,
     'v2': schemaV2
   };
   
   function validateWithVersion(data, version = 'v2') {
     const schema = schemas[version];
     const validate = ajv.compile(schema);
     return validate(data);
   }
   

5. Sanitize and transform data - Clean data before validation

   function sanitizeUserData(data) {
     return {
       name: String(data.name || '').trim(),
       email: String(data.email || '').toLowerCase().trim(),
       age: parseInt(data.age, 10) || 0
     };
   }
   

6. Provide detailed error messages - Help users fix validation errors

   function formatValidationErrors(errors) {
     return errors.map(error => ({
       field: error.instancePath.replace('/', ''),
       message: error.message,
       value: error.data
     }));
   }
   

7. Use schema registries - Centralize schema management

   // Schema registry for multiple resources
   const schemaRegistry = {
     user: userSchema,
     product: productSchema,
     order: orderSchema
   };
   
   function validate(resourceType, data) {
     const schema = schemaRegistry[resourceType];
     const validate = ajv.compile(schema);
     return validate(data);
   }
   

8. Test with invalid data - Verify validation catches errors

   // Unit test schema validation
   describe('User Schema Validation', () => {
     it('should reject invalid email', () => {
       const invalidUser = { email: 'not-an-email' };
       expect(() => validateUser(invalidUser)).toThrow();
     });
   
     it('should reject missing required fields', () => {
       const invalidUser = { age: 25 };
       expect(() => validateUser(invalidUser)).toThrow();
     });
   });
   

9. Handle backward compatibility - Support old schema versions gracefully

   function migrateSchema(data, fromVersion, toVersion) {
     if (fromVersion === 'v1' && toVersion === 'v2') {
       return {
         ...data,
         newField: data.oldField, // Migrate old field to new
       };
     }
     return data;
   }
   

Platform-Specific Guides

Further Reading

• JSON Schema Guide
• AJV: The Fastest JSON Schema Validator
• Understanding JSON Schema
• OpenAPI Schema Validation
• Schema Validation Best Practices
• TypeScript and JSON Schema