Skip to main content

JSON Schema Reference

The complete Forma specification is available as a JSON Schema for validation and IDE autocompletion.

Download​

Download Forma JSON Schema v1.0

Using the Schema​

IDE Autocompletion​

Add the $schema property to your Forma specification for editor support:

{
  "$schema": "https://docs.formidable.software/schemas/forma/v1.json",
  "version": "1.0",
  "meta": {
    "id": "my-form",
    "title": "My Form"
  }
}

This enables:

  • Property autocompletion
  • Inline documentation
  • Validation errors in the editor

Supported Editors​

  • VS Code - Native JSON Schema support
  • JetBrains IDEs - WebStorm, IntelliJ, etc.
  • Sublime Text - With LSP plugin
  • Vim/Neovim - With coc.nvim or similar

Programmatic Validation​

Use any JSON Schema validator to validate Forma specifications:

JavaScript (Ajv):

import Ajv from "ajv";
import formaSchema from "./forma-v1.json";

const ajv = new Ajv();
const validate = ajv.compile(formaSchema);

const isValid = validate(myFormaSpec);
if (!isValid) {
  console.log(validate.errors);
}

Python (jsonschema):

import json
from jsonschema import validate, ValidationError

with open('forma-v1.json') as f:
    schema = json.load(f)

try:
    validate(instance=my_forma_spec, schema=schema)
except ValidationError as e:
    print(e.message)

Schema Contents​

The JSON Schema defines:

Root Object (Forma)​

PropertyRequiredDescription
$schemaNoSchema URL for IDE support
versionYesMust be "1.0"
metaYesForm metadata
schemaYesJSON Schema for data structure
fieldsYesField definitions
fieldOrderYesField display order
computedNoComputed values
referenceDataNoLookup tables
pagesNoMulti-page structure

Meta Object​

PropertyRequiredDescription
idYesUnique form identifier
titleYesForm title
descriptionNoForm description
versionNoForm version string

Field Definition​

PropertyDescription
labelDisplay label
descriptionHelp text
placeholderInput placeholder
typeField type override
visibleWhenVisibility condition
requiredWhenRequired condition
enabledWhenEnabled condition
defaultValueInitial value on load
readonlyWhenRead-only condition
variantPresentation variant hint
variantConfigVariant-specific configuration
validationsCustom validation rules
optionsSelect options
itemFieldsArray item fields
minItemsMinimum array items
maxItemsMaximum array items

Validation Rule​

PropertyRequiredDescription
ruleYesFEEL expression
messageYesError message
severityNo"error" or "warning"

Computed Field​

PropertyRequiredDescription
expressionYesFEEL expression
labelNoDisplay label
formatNoDisplay format
displayNoShow in form

Page Definition​

PropertyRequiredDescription
idYesUnique page ID
titleYesPage title
descriptionNoPage description
visibleWhenNoVisibility condition
fieldsYesFields on this page

Version History​

VersionDateChanges
1.02024-01Initial release