A
Atlas
...

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 (default) - Learn and observe field types
  • Live Mode - Strictly validate against defined schema
  • Sandbox Mode

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

    What Happens

  • All submissions are accepted
  • Field types are inferred automatically
  • Sample values are recorded
  • A schema is built over time
  • Localhost testing is enabled (with registered IP)
  • Viewing Observations

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

    FieldInferred TypeOccurrencesSample Values
    namestring150"John", "Jane"
    emailemail150"john@...", "jane@..."
    agenumber4525, 30, 42
    subscribeboolean120true, 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.

    TypeDescriptionExamples
    stringText up to 500 characters"Hello world"
    textText over 500 charactersMulti-line messages
    emailEmail address"user@example.com"
    numberJSON number42, 3.14
    booleanJSON booleantrue, false
    urlURL"https://..."
    phonePhone number"+1-555-0123"

    Going Live

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

  • Go to Form Settings → Security → Schema Validation
  • Review the inferred schema
  • Click Go Live — Lock Schema
  • What Changes

    SandboxLive
    All submissions acceptedInvalid submissions rejected
    Types observedTypes enforced
    Schema evolvesSchema 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:

    json
    {
      "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.

    json
    {
      "error": "Validation failed",
      "details": [
        { "field": "spam_field", "error": "Unknown field (rejected)" }
      ]
    }

    Strip

    Unknown fields are silently removed.

    json
    // 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?

  • Go to Form Settings → Security → Schema Validation
  • Click Unlock — Return to Sandbox
  • Form returns to sandbox mode
  • New observations are collected
  • Go live again when ready
  • 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:

  • Optional fields (may not appear in every submission)
  • Fields with multiple possible types
  • User typos and invalid input
  • 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:

  • Schema too strict
  • Frontend validation missing
  • A field was added to the form after the schema was locked
  • Validation Status

    Each stored submission records a validation status:

    StatusDescription
    acceptedStored as submitted
    sanitizedUnknown fields were stripped

    Submissions that fail validation in live mode are rejected and not stored.