Schema Validation

Overview

Schema validation is a core component of the testing-api suite, designed to ensure that the Supervised AI platform's API responses adhere to strict contract specifications. By validating the structure, data types, and required fields of JSON responses, you can catch breaking changes early in the development lifecycle.

The validation logic utilizes JSON Schema (Draft 07) to define the expected shape of the API resources.

Contract Compliance

To maintain a stable integration with the Supervised AI platform, all endpoints must be validated against their respective schema definitions. These definitions act as the "Source of Truth" for the API's public interface.

Standard Resource Schema

The following structure represents a typical resource schema (e.g., a Dataset or Model Metadata) used for validation:

{
  "type": "object",
  "required": ["id", "status", "created_at"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "name": { "type": "string" },
    "status": { 
      "type": "string", 
      "enum": ["pending", "processing", "completed", "failed"] 
    },
    "metadata": { "type": "object" },
    "created_at": { "type": "string", "format": "date-time" }
  }
}

Validating API Responses

The testing-api provides a set of utility functions to compare live API responses against the stored JSON structures.

Usage Example

To validate an API response within your test suite, import the validator and the specific schema for the endpoint you are testing.

import { validateSchema } from './utils/validator';
import datasetSchema from './schemas/dataset.schema.json';

describe('Dataset API Contract', () => {
  it('should return a valid dataset object', async () => {
    const response = await api.get('/datasets/123');
    
    // Validate the response body against the schema
    const result = validateSchema(response.data, datasetSchema);

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

    expect(result.valid).toBe(true);
  });
});

Validator Interface

The validateSchema function is the primary public interface for contract testing.

Input: | Parameter | Type | Description | | :--- | :--- | :--- | | data | Object | The JSON response body received from the API. | | schema | Object | The JSON Schema object to validate against. |

Output: | Property | Type | Description | | :--- | :--- | :--- | | valid | Boolean | Returns true if the data complies with the schema. | | errors | Array | A list of validation errors (e.g., missing fields, type mismatches). Returns null if valid. |

Strict Mode Validation

By default, validation ensures that all required fields are present. For strict contract compliance, schemas are configured to disallow additional properties (additionalProperties: false). This ensures that the API does not return undocumented data that could lead to bloat or security vulnerabilities.

| Validation Type | Description | | :--- | :--- | | Structural | Validates nesting, arrays, and object hierarchy. | | Type Checking | Ensures strings, integers, and booleans are correctly typed. | | Format | Validates specific string formats like email, uuid, and date-time. | | Enum | Restricts fields to a predefined set of constant values. |