Validation Rules

Validation Overview

To ensure the integrity of the Supervised AI platform, the Testing API enforces strict validation rules on all incoming test data and model responses. Every payload is subjected to a two-tier validation process: Schema Compliance and Data Integrity Sanity Checks.

All requests must be sent as application/json. Failure to meet the following criteria will result in a 422 Unprocessable Entity response.

Schema Compliance

Each request must adhere to the core data structure. The API validates the presence and data type of the following primary fields:

Prediction Object Structure

Within the predictions array, each object must follow this format:

input_id (String): Must match an existing ID in the target dataset.
output (String/Object): The raw prediction result.
confidence (Float): Must be a value between 0.0 and 1.0.
latency (Float): Response time in milliseconds (must be positive).

Field-Level Constraints

The following logic is applied to specific fields during the automated validation phase:

1. Confidence Scores

Numerical values for model confidence must strictly reside within the [0, 1] range.

Valid: 0.85, 1.0, 0.0
Invalid: 85, -0.1, 1.1

2. Array Length Limits

To prevent memory overflows and ensure performance:

The predictions array must contain at least 1 entry.
The maximum batch size per request is 5,000 entries. For larger datasets, use partitioned requests.

3. String Sanitization

All string inputs (especially within metadata and output) are stripped of executable scripts or HTML tags to prevent injection attacks.

Automated Sanity Checks

Beyond basic type checking, the API performs logical validation to ensure the data is actionable for Supervised AI analytics:

ID Uniqueness: The API checks for duplicate input_id entries within a single payload. If duplicates are found, the request is rejected to prevent skewed accuracy metrics.
Dataset Mapping: The dataset_id provided must be active and accessible to the API key used for the request.
Format Consistency: If the test run is configured for "Classification," the output field must match one of the predefined labels in the dataset schema.

Example Valid Payload

{
  "test_run_id": "550e8400-e29b-41d4-a716-446655440000",
  "dataset_id": "ds_alpha_v2",
  "predictions": [
    {
      "input_id": "img_001",
      "output": "label_cat",
      "confidence": 0.982,
      "latency": 145.2
    },
    {
      "input_id": "img_002",
      "output": "label_dog",
      "confidence": 0.875,
      "latency": 132.0
    }
  ],
  "metadata": {
    "model_version": "v1.4.2",
    "environment": "staging"
  }
}

Error Response Handling

When a validation rule is triggered, the API returns a structured error object to help developers debug the payload:

{
  "error": "ValidationFailed",
  "message": "The payload contains 1 validation error.",
  "details": [
    {
      "field": "predictions[1].confidence",
      "issue": "Value must be between 0 and 1",
      "received": 1.5
    }
  ]
}