Schema Validation

Schema validation ensures submissions match your expected format. Define field types and requirements, then Atlas validates every submission.

How It Works

Atlas has two validation modes:

Sandbox Mode

In sandbox mode, Atlas observes incoming submissions and learns your form's structure.

What Happens

Viewing Observations

Go to Form Settings → Security → Schema Validation to see:

Inferred Types

Going Live

Once you're confident in your schema, lock it down:

What Changes

Important: Going live will block localhost submissions entirely. Make sure you have production domains configured in allowed_origins.

Validation Errors

In live mode, invalid submissions return:

{
  "error": "Validation failed",
  "details": [
    {
      "field": "email",
      "error": "Expected email, got string",
      "value": "not-an-email"
    },
    {
      "field": "age",
      "error": "Expected number, got string",
      "value": "twenty-five"
    }
  ]
}

Unknown Field Behavior

Configure how Atlas handles fields not in your schema:

Strip (default)

Unknown fields are silently removed.

// Submitted
{ "name": "John", "email": "john@example.com", "spam_field": "buy now!" }

// Stored
{ "name": "John", "email": "john@example.com" }

Reject

Submissions with unknown fields are rejected.

{
  "error": "Validation failed",
  "details": [
    {
      "field": "spam_field",
      "error": "Unknown field"
    }
  ]
}

Unlocking Schema

Need to add new fields or change types?

Warning: Unlocking affects validation immediately. Plan for a brief transition period.

Schema API

Get Form Schema

curl "https://atlasforms.app/api/user/forms/{form_id}/schema" \
  -H "Authorization: Bearer fep_your_api_key"

{
  "validation_mode": "live",
  "unknown_field_behavior": "strip",
  "schema": {
    "version": 1,
    "fields": {
      "name": { "type": "string" },
      "email": { "type": "email" },
      "message": { "type": "string" },
      "subscribe": { "type": "boolean" }
    }
  },
  "schema_locked_at": "2024-01-15T10:30:00Z",
  "observations": [],
  "submission_count": 1500
}

Update Schema Settings

curl -X PATCH "https://atlasforms.app/api/user/forms/{form_id}/schema" \
  -H "Authorization: Bearer fep_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"unknown_field_behavior": "reject"}'

Best Practices

1. Collect Data First

Run in sandbox mode until you have representative submissions. 50-100 submissions usually provides enough data.

2. Review Before Locking

Check inferred types match your expectations. A "number" field might be inferred as "string" if users enter "N/A".

3. Handle Edge Cases

Consider what happens with:

4. Test After Going Live

Submit test data to verify validation works correctly.

5. Monitor Rejections

Check your dashboard for rejected submissions. High rejection rates may indicate:

Validation Status

Each submission includes a validation status:

Filter submissions by status in the dashboard or API.