Docs / Configuration / Validation

Validation

CloudNexus automatically validates all API requests and infrastructure configurations to ensure data integrity, security, and operational reliability. This guide covers validation rules, error responses, and best practices for schema compliance.

Overview

Before any resource is provisioned or modified, CloudNexus validates payloads against our internal JSON Schema definitions. Validation occurs at the edge layer, ensuring invalid requests are rejected before they reach the infrastructure orchestration engine.

💡 Best Practice
Always validate payloads locally using our open-source SDKs before sending requests to reduce latency and avoid unnecessary API calls.

Validation Rules

The following rules are enforced across all API endpoints. Custom validation can be added via webhook hooks or Terraform provider constraints.

Rule Description Example
required Field must be present in the payload {"name": "prod-01"}
type Strict type checking (string, integer, boolean, array, object) "cpu": 4 (not "4")
minLength / maxLength String length constraints "region": "us-east-1"
pattern Regex validation for identifiers and formats ^[a-z0-9-]+$
enum Value must match one of the allowed options "plan": "professional"
min / max Numeric bounds for resources (CPU, RAM, storage) "ram": 32 (max 128)

Request Validation

When sending a POST or PATCH request, CloudNexus parses the JSON body and validates it against the endpoint-specific schema. If validation fails, the request returns a 400 Bad Request with detailed error mapping.

{
  "instance": {
    "name": "web-server-01",
    "plan": "professional",
    "region": "eu-west-1",
    "cpu": 8,
    "ram": 32,
    "storage": {
      "size_gb": 320,
      "type": "nvme"
    },
    "firewall": {
      "allow_ports": [22, 443],
      "deny_all_other": true
    }
  }
}

Nested Object Validation

Validation rules apply recursively. If a nested object contains invalid fields, the error response will include the full path to the problematic field.

Error Response Format

Validation errors follow a consistent structure to simplify parsing in applications and infrastructure-as-code tools.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request payload contains 2 validation errors.",
    "details": [
      {
        "field": "instance.ram",
        "rule": "max",
        "message": "Value 256 exceeds maximum allowed (128 GB)"
      },
      {
        "field": "instance.firewall.allow_ports",
        "rule": "type",
        "message": "Expected array of integers"
      }
    ],
    "request_id": "req_8f3k29d1x0"
  }
}
⚠️ Note
Always log the request_id when reporting validation issues to our support team. It allows us to trace the exact schema version and edge node that processed the request.

SDK Validation Helpers

Our SDKs include built-in validation methods that mirror the API's behavior. Use them to catch errors before network transmission.

import { validateInstance, ValidationError } from '@cloudnexus/sdk';

const config = {
  name: 'api-gateway',
  region: 'ap-southeast-1',
  plan: 'enterprise',
  cpu: 32,
  ram: 256 // ⚠️ Will trigger validation error
};

try {
  validateInstance(config);
  console.log('✅ Payload is valid');
} catch (err) {
  if (err instanceof ValidationError) {
    err.details.forEach(d => {
      console.error(`${d.field}: ${d.message}`);
    });
  }
}

Custom Validation via Webhooks

For advanced use cases, CloudNexus supports pre-provisioning validation webhooks. When enabled, the API sends a VALIDATION_PENDING event to your configured endpoint before resource allocation.

FAQ

Why is my valid payload returning a 400 error?

Check for trailing commas, incorrect number types (strings vs integers), or deprecated field names. Use the dry_run: true parameter to test validation without creating resources.

Can I bypass validation for legacy migrations?

No. Validation is enforced at the infrastructure level to prevent misconfigurations. Use the Data Migration API which accepts relaxed schemas and handles normalization automatically.

← Environments