Schema

The schema property defines the data structure of your form using JSON Schema. It specifies what types of data each field accepts and basic validation constraints.

Structure

The schema must be a JSON Schema object with type: "object":

{
  "schema": {
    "type": "object",
    "properties": {
      "fieldName": { "type": "string" }
    },
    "required": ["fieldName"]
  }
}

Supported Types

String

Text values with optional constraints.

{
  "name": {
    "type": "string",
    "minLength": 1,
    "maxLength": 100
  }
}

Properties:

Property	Type	Description
minLength	integer	Minimum character length
maxLength	integer	Maximum character length
pattern	string	Regular expression pattern
format	string	Semantic format (see below)
enum	array	List of allowed values

Formats:

Format	Description
email	Valid email address
date	Date in ISO 8601 format (YYYY-MM-DD)
date-time	Date and time in ISO 8601 format
uri	Valid URL
uuid	UUID format

{
  "email": {
    "type": "string",
    "format": "email"
  },
  "birthDate": {
    "type": "string",
    "format": "date"
  }
}

Number

Floating-point numbers with optional range constraints.

{
  "price": {
    "type": "number",
    "minimum": 0,
    "maximum": 10000
  }
}

Properties:

Property	Type	Description
minimum	number	Minimum value (inclusive)
maximum	number	Maximum value (inclusive)
exclusiveMinimum	number	Minimum value (exclusive)
exclusiveMaximum	number	Maximum value (exclusive)
multipleOf	number	Value must be divisible by this (for step)

Numeric Precision with multipleOf

Use multipleOf to control input step and validate precision:

{
  "frictionCoefficient": {
    "type": "number",
    "minimum": 0.05,
    "maximum": 0.3,
    "multipleOf": 0.01
  }
}

Common use cases:

Use Case	multipleOf	Effect
Currency (cents)	0.01	Two decimal places (0.00, 0.01, ...)
Half-units	0.5	Half increments (0.0, 0.5, 1.0, ...)
Percentages	0.1	One decimal place
Coefficients	0.01	Two decimal places

Integer

Whole numbers.

{
  "quantity": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100
  }
}

Properties:

Property	Type	Description
minimum	integer	Minimum value (inclusive)
maximum	integer	Maximum value (inclusive)
multipleOf	integer	Value must be divisible by this

Boolean

True/false values.

{
  "agreeToTerms": {
    "type": "boolean"
  }
}

Array

Lists of items.

{
  "items": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "quantity": { "type": "integer" }
      }
    },
    "minItems": 1,
    "maxItems": 10
  }
}

Properties:

Property	Type	Description
items	object	Schema for array items
minItems	integer	Minimum number of items
maxItems	integer	Maximum number of items

Object

Nested objects with their own properties.

{
  "address": {
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "zip": { "type": "string" }
    },
    "required": ["street", "city"]
  }
}

Required Fields

Use the required array to specify which fields must have values:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "email": { "type": "string" },
      "phone": { "type": "string" }
    },
    "required": ["name", "email"]
  }
}

For conditional required fields, use requiredWhen in the field definition instead.

Enum Values

Restrict a field to specific allowed values:

{
  "status": {
    "type": "string",
    "enum": ["pending", "approved", "rejected"]
  }
}

For user-friendly labels, define options in the field definition.

Definitions ($defs)

Reuse schema definitions with $defs:

{
  "schema": {
    "type": "object",
    "properties": {
      "billingAddress": { "$ref": "#/$defs/address" },
      "shippingAddress": { "$ref": "#/$defs/address" }
    },
    "$defs": {
      "address": {
        "type": "object",
        "properties": {
          "street": { "type": "string" },
          "city": { "type": "string" },
          "zip": { "type": "string" }
        }
      }
    }
  }
}

Note: $ref resolution is not implemented in the Forma runtime. $defs is supported in the type system for schema documentation purposes and external tooling.

Best Practices

1. Match field names to schema properties - Each field in fields should correspond to a property in schema.properties

2. Use appropriate types - Choose integer for whole numbers, number for decimals

3. Set sensible constraints - Use minLength, maximum, etc. to catch invalid data early

4. Use formats for validation - Email, date, and URL formats provide automatic validation

5. Keep schema and fields in sync - The schema defines the data, fields define the UI