Forma Overview

Forma is a declarative specification format for defining dynamic forms. It combines JSON Schema for data structure with FEEL expressions for conditional logic.

What is Forma?

Forma is a JSON-based format that describes:

• What data your form collects (schema)
• How fields behave (visibility, required state, validation)
• Calculated values derived from user input
• Multi-page structure for wizard-style forms

Specification Structure

A Forma specification has the following top-level structure:

{
  "version": "1.0",
  "meta": { ... },
  "schema": { ... },
  "fields": { ... },
  "fieldOrder": [ ... ],
  "computed": { ... },
  "referenceData": { ... },
  "pages": [ ... ]
}

Required Properties

Property	Type	Description
version	"1.0"	Specification version (always "1.0")
meta	object	Form metadata (title, description, etc.)
schema	object	JSON Schema defining the data structure
fields	object	Field display and behavior configuration
fieldOrder	array	Order in which fields are displayed

Optional Properties

Property	Type	Description
computed	object	Calculated values derived from form data
referenceData	object	Lookup tables for calculations
pages	array	Multi-page wizard structure

Minimal Example

{
  "version": "1.0",
  "meta": {
    "id": "contact-form",
    "title": "Contact Us"
  },
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "email": { "type": "string", "format": "email" }
    },
    "required": ["name", "email"]
  },
  "fields": {
    "name": { "label": "Your Name" },
    "email": { "label": "Email Address" }
  },
  "fieldOrder": ["name", "email"]
}

Complete Example

{
  "version": "1.0",
  "meta": {
    "id": "order-form",
    "title": "Product Order",
    "description": "Order form with quantity pricing"
  },
  "schema": {
    "type": "object",
    "properties": {
      "product": { "type": "string", "enum": ["basic", "pro", "enterprise"] },
      "quantity": { "type": "integer", "minimum": 1, "maximum": 100 },
      "needsSupport": { "type": "boolean" },
      "supportLevel": { "type": "string", "enum": ["standard", "premium"] }
    },
    "required": ["product", "quantity"]
  },
  "fields": {
    "product": {
      "label": "Product",
      "type": "select",
      "options": [
        { "value": "basic", "label": "Basic - $10/mo" },
        { "value": "pro", "label": "Pro - $25/mo" },
        { "value": "enterprise", "label": "Enterprise - $100/mo" }
      ]
    },
    "quantity": {
      "label": "Number of Licenses",
      "description": "How many licenses do you need?"
    },
    "needsSupport": {
      "label": "Do you need support?"
    },
    "supportLevel": {
      "label": "Support Level",
      "type": "select",
      "visibleWhen": "needsSupport = true",
      "requiredWhen": "needsSupport = true",
      "options": [
        { "value": "standard", "label": "Standard Support" },
        { "value": "premium", "label": "Premium Support (+$50/mo)" }
      ]
    }
  },
  "fieldOrder": ["product", "quantity", "needsSupport", "supportLevel"],
  "computed": {
    "basePrice": {
      "expression": "if product = \"basic\" then 10 else if product = \"pro\" then 25 else 100",
      "label": "Base Price"
    },
    "total": {
      "expression": "computed.basePrice * quantity",
      "label": "Monthly Total",
      "format": "currency",
      "display": true
    }
  }
}

Key Concepts

Schema vs Fields

• Schema defines the data types and basic constraints (using JSON Schema)
• Fields defines how those fields are displayed and behave dynamically

{
  "schema": {
    "properties": {
      "age": { "type": "integer", "minimum": 0 }
    }
  },
  "fields": {
    "age": {
      "label": "Your Age",
      "visibleWhen": "wantsAgeDiscount = true"
    }
  }
}

FEEL Expressions

Forma uses FEEL (Friendly Enough Expression Language) for all dynamic behavior. FEEL expressions are human-readable strings that reference form data:

{
  "visibleWhen": "age >= 18",
  "requiredWhen": "hasInsurance = true",
  "expression": "quantity * unitPrice"
}

Next Steps

• Schema Reference - Data structure definition
• Fields Reference - Field types and configuration
• Conditional Logic - Dynamic visibility and requirements