TL;DR: TOML form specifications let you define forms as code - version control them, copy-paste between projects, and maintain consistent validation across your entire stack.

Code-First Form Definition

While Formshive offers a visual form editor, the real power lies in TOML specifications. Think of them as configuration files for your forms - structured, version-controllable, and completely portable.

[email]
name = 'email'
field = 'email'
label = 'Email Address'
required = true
is_email = true
on_fail = 'reject'

[message]
name = 'message'
field = 'textarea'
label = 'Your Message'
required = true
is_min = 10
check_spam = true
on_fail = 'spam'

[settings]
discard_additional_fields = true

Why Developers Love TOML Specs

Version Control Ready

Your forms live in code alongside your application:

git add forms/contact-form.toml
git commit -m "add validation to contact form"

Copy-Paste Between Forms

Need the same validation logic across multiple forms? Copy the TOML specification from one form and paste it into another form’s TOML editor.

Environment Consistency

Same form configuration works across development, staging, and production.

Team Collaboration

Review form changes in pull requests just like any other code.

Advanced Field Types

Modern web forms need more than just text fields:

[phone]
name = 'phone'
field = 'tel'
label = 'Phone Number'
is_pattern = '^\\+?[1-9]\\d{1,14}$'
helptext = 'International format preferred'

[website]
name = 'website'
field = 'url'
label = 'Company Website'
is_url = true

[budget]
name = 'budget'
field = 'select'
label = 'Project Budget'
options = 'Under $5k,$5k-$25k,$25k-$100k,Over $100k'
required = true

[skills]
name = 'skills'
field = 'checkbox'
label = 'Technical Skills'
options = 'React,Vue,Angular,Node.js,Python,Go'
multiple = true

[event_date]
name = 'event_date'
field = 'datetime'
label = 'Event Date & Time'
required = true

Validation Arsenal

Data Type Validation

[age]
name = 'age'
field = 'number'
is_min = 18
is_max = 120
on_fail = 'reject'

[username]
name = 'username'
field = 'text'
is_min = 3
is_max = 20
is_pattern = '^[a-zA-Z0-9_]+$'

Business Logic Validation

[invite_code]
name = 'invite_code'
field = 'text'
is_in = 'BETA2025,LAUNCH2025,SPECIAL2025'
on_fail = 'reject'

[company_size]
name = 'company_size'
field = 'select'
options = '1-10,11-50,51-200,200+'
required = true

Smart Failure Handling

Control what happens when validation fails:

  • pass - Accept anyway (default)
  • spam - Mark as spam
  • trash - Move to trash
  • reject - Return HTTP 400 error

Working with the UI

Switching to TOML Mode

  1. Go to form settings
  2. Enable “Check Form Fields”
  3. Click the “TOML” tab
  4. Start typing your specification

Template Shortcuts

Click “Prefill Example” to get a complete template with common field types and validation patterns.

Real-time Validation

The UI validates your TOML syntax as you type, highlighting errors and providing specific feedback.

Production Integration

HTML Generation

Generate clean HTML forms from your specifications:

<form action="https://api.formshive.com/v1/digest/your-form-id" method="POST">
  <label for="email">Email Address</label>
  <input type="email" name="email" required />
  
  <label for="message">Your Message</label>
  <textarea name="message" required minlength="10"></textarea>
  
  <button type="submit">Submit</button>
</form>

API Testing

Get cURL commands for testing:

curl -X POST \
  -d "email=test@example.com" \
  -d "message=Hello from the API" \
  https://api.formshive.com/v1/digest/your-form-id

Developer Workflow

Local Development

  1. Create TOML specifications in your editor
  2. Copy-paste into Formshive TOML editor
  3. Test using generated HTML and previews

Team Workflow

  1. Store TOML specs in your repository
  2. Review changes via pull requests
  3. Deploy to Formshive by copying from your repo

Maintenance

# Update validation rules across all forms
[email]
name = 'email'
field = 'email'
required = true
is_email = true
on_fail = 'reject'  # Stricter validation in production

Getting Started

  1. Create a form in Formshive
  2. Enable form specifications in settings
  3. Switch to TOML tab and start defining fields
  4. Test with the HTML preview
  5. Copy specifications to your code repository

Form specifications bridge the gap between visual form builders and code-first development, giving you the best of both worlds: developer control with production reliability.