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:
| Field | Inferred Type | Occurrences | Sample Values |
|---|---|---|---|
| name | string | 150 | "John", "Jane" |
| 150 | "john@...", "jane@..." | ||
| age | number | 45 | 25, 30, 42 |
| subscribe | boolean | 120 | true, false |
Inferred Types
HTML form posts send every value as text, so numbers and checkboxes from HTML forms are inferred as string. Only JSON submissions produce number and boolean.
| Type | Description | Examples |
|---|---|---|
string | Text up to 500 characters | "Hello world" |
text | Text over 500 characters | Multi-line messages |
email | Email address | "user@example.com" |
number | JSON number | 42, 3.14 |
boolean | JSON boolean | true, false |
url | URL | "https://..." |
phone | Phone number | "+1-555-0123" |
Going Live
Once you're confident in your schema, lock it down:
What Changes
| Sandbox | Live |
|---|---|
| All submissions accepted | Invalid submissions rejected |
| Types observed | Types enforced |
| Schema evolves | Schema locked |
| Localhost allowed (with IP) | Localhost blocked |
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": "Invalid email format" },
{ "field": "age", "error": "Expected number" }
]
}The response status is 400. Rejected submissions are not stored.
Unknown Field Behavior
Configure how Atlas handles fields not in your schema:
Reject (default)
Submissions with unknown fields are rejected.
{
"error": "Validation failed",
"details": [
{ "field": "spam_field", "error": "Unknown field (rejected)" }
]
}Strip
Unknown fields are silently removed.
// Submitted
{ "name": "John", "email": "john@example.com", "spam_field": "buy now!" }
// Stored
{ "name": "John", "email": "john@example.com" }Unlocking Schema
Need to add new fields or change types?
Warning: Unlocking affects validation immediately. Plan for a brief transition period.
Managing the Schema
Schema settings are managed in the dashboard. The public API (/api/v1) does not expose them.
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. Watch for Rejections
Rejected submissions are not stored, so they don't appear in your dashboard. The submitter receives the 400 response. If users report that the form won't submit, check:
Validation Status
Each stored submission records a validation status:
| Status | Description |
|---|---|
accepted | Stored as submitted |
sanitized | Unknown fields were stripped |
Submissions that fail validation in live mode are rejected and not stored.