Form.io Concepts
Defining key concepts and terminology in Form.io
Forms
A Form is the primary way data enters the platform. Forms are built using the drag-and-drop Form Builder to arrange components, which can be thought of as the fields that make up a form.
Forms may be created in three display modes:
Web Form - a standard single-page form.
Wizard - displays a web form in a multi-step format with navigation between pages.
PDF - a fillable PDF that overlays Form.io components on a document.
As a form is built Form.io simultaneously constructs the JSON schema and defines a REST API endpoint. This allows the form to be fully portable, embeddable, and programmatically accessible.
Forms collect "ad hoc" data, generally through a form user's input.
Resources
A Resource is a structured data object within a project. Resources are built using the same drag-and-drop Form Builder to arrange components. Resources are used to define reusable data models that other forms and resources can reference.
Think of a Resource as a database collection with a built-in schema. Common examples include:
A User resource that stores name, email, and a role for application users.
A Customer resource that might be used across multiple forms such as orders, returns, and support.
A Product resource that populates the selections available on an Order form.
Once a Resource is populated with submission data, it functions like a RESTful database. Entities can be created, read, updated, deleted, and queried through the same automatically generated API. Other forms can reference Resource data using components like the Select Resource field, enabling complex relational data structures.
Forms vs. Resources — when to use which:
Function
Collect unstructured / supplemental data
Define structured, reusable data objects
Examples
Job application, feedback survey
Employee profile, Cost Center list
Referenced by others?
Rarely
Frequently, resources populate form fields
Typical use
One-time or event-driven submissions
Persistent records queried by the application
Components
Components are the building blocks of every form and resource. Components are dragged from the palettes of available components onto the Form Builder canvas. Components capture input through a variety of fields. Each component is stored as a JSON object within the form's schema, and defines how the input is stored in submission data.
Every component can be configured in a variety of ways to customize the appearance and functionality, altering the way the field appears, the way data is validated, and more.
Developers who need functionality beyond the built-in library can create custom components by extending an existing component class and registering it with the renderer.
Projects
A Project is the top-level organizational unit in Form.io. Typically, a single project corresponds to a single application. All collateral developed in Form.io (forms, resources, roles, submission data) are contained within a project. Projects shares a single domain API endpoint.
Projects serve as a scope boundary for Form.io users. A particular form builder might be granted permission to create forms in one project but not another, while a form user may view submissions in one project but not others. Every element within a project is encapsulated within that project's context; roles, data, and permissions in one project are distinct to that project, and cannot be shared or accessed from a different project.
A project can contain an unlimited number of forms, resources, and developers, and can handle an unlimited number of API submission calls.
Developer Portal
The Developer Portal is the web-based UI where platform users manage everything: projects, forms, resources, roles, submissions, stages, teams, and integrations. It is the primary interface for form builders and developers during the build phase.
Form users (the people who fill out forms in production) do not interact with the Developer Portal. They access forms through the application that embeds and renders them using the Form.io JavaScript renderer.
Form JSON
Every form and resource in Form.io is represented under the hood as Form JSON. Form JSON is a JSON object that describes the form's title, display type, API path, and the full tree of components with their settings, validation rules, conditional logic, and layout.
A simplified example:
The JSON schema is the single source of truth for a form. It powers three critical functions:
Rendering - The JavaScript form renderer reads the JSON and displays the form in the browser. No server-side rendering is needed as the form is fully described by its schema.
API generation - The server uses the same JSON to generate the REST API endpoints and validate incoming submission data.
Portability - Because the form is just JSON, it can be versioned, exported, imported, migrated between stages, and stored in source control.
The Form Builder UI updates the JSON schema in real time as components are arranged and configured.
Submissions
A Submission is a single data record created when a user fills out and submits a form or resource. The submission payload is a JSON object whose structure mirrors the key values defined in the form's components.
In the "Person" form example above, a submission would look like:
Submissions are the data layer of the platform. Submissions are:
API-accessible - Every submission is reachable via the REST API at a URL of the form
{projectUrl}/{formPath}/submission/{submissionId}. Submissions can be created, read, updated, deleted, filtered, and paginated through the API.Owned - Each submission has an owner (the user who created it), which is used by the permissions system to enforce _own vs. _all access control.
Portable - In addition to API access, submission data can be viewed in JSON, CSV, or PDF formats directly from the Developer Portal.
Revision-tracked - Submission Revisions (available with the Security & Compliance package) provide an audit log of who changed a submission, when, and what was modified, with the ability to revert to previous versions.
Collection-configurable - Submissions can optionally be directed to separate database collections on a per-form basis for compliance or performance requirements.
Actions
Actions are configurable server-side operations that execute when a form is submitted. Every form can have an unlimited number of actions that execute sequentially. Actions can be used as a bridge to other parts of an application or integrated systems.
Actions are where integration and workflow logic lives. The built-in actions include:
Save Submission - Saves the submission data. By default every form has this action, saving data to itself. It can also be configured to route data to a different Resource (e.g., a Registration form that saves to a User resource).
Email - Sends an email using a configured email transport (SMTP, SendGrid, Mailgun, or Mandrill) with customizable templates that can include submission data.
Login - Authenticates a user by generating a JWT token based on the submitted credentials.
Webhook - Sends the submission payload to an external API endpoint in real time, enabling integration with any external system.
Integrations - Sends submission data to third-party providers.
Roles & Permissions
Form.io uses a role-based access control (RBAC) system to govern who can do what within a project. The system is built on two concepts: Roles (which are assigned to users) and Permissions (which are given to roles).
Roles
Every new project starts with four default roles:
Anonymous - Reserved for unauthenticated users (e.g., someone filling out a public survey or a login form). Cannot be deleted.
Everyone - A role that represents any user assigned to any role, including anonymous ones. When a permission is given to Everyone, every role in the project inherits that permission. Cannot be deleted.
Authenticated - A starting role for logged-in users.
Administrator - A starting role for users with elevated privileges.
Additional custom roles can be added. Each role has a unique ID scoped to its project. Roles exist within the Project context and cannot cross project boundaries.
Permissions
Permissions are organized across three scopes:
Project
Who can create, read, update, or delete project-level elements (forms, roles, settings).
Form Definition
Who can read, update, or delete a specific form's JSON schema.
Submission Data
Who can create, read, update, or delete the data submitted through a specific form.
Within each scope, eight permission types are available:
Create Own
Create All
Read Own
Read All
Update Own
Update All
Delete Own
Delete All
"Own" permissions restrict users to records they own (typically records they created). "All" permissions grant access to all records, regardless of ownership. As a general rule, "All" permissions are for administrative roles and "own" permissions are for end users.
By default, forms allow all roles to read the form definition (so the form can be rendered in the application), but submission access is disabled for every form. You must explicitly grant submission permissions for users to interact with a form's data.
Teams
Teams enable collaboration by granting groups of developers and form builders access to projects and stages. A team is created at the portal level (outside any individual project). Teams can then be assigned to one or more projects.
Teams can operate at two levels:
Project-level - Grants the team access to the entire project.
Stage-level - Grants the team access to a specific stage of a specific project (e.g., the Development stage) without access to other stages like Live.
Stage-level teams support two permission tiers: Stage Read (view forms and data, but cannot modify) and Stage Write (view and modify forms and data).
Stages
Stages deliver control over a project's development lifecycle, such as authoring, testing, and production. By default, every project has a Live stage that represents the production environment.
Additional stages can be created to match a team's SDLC. A typical configuration includes:
Live
The production stage connected to the production environment.
Authoring
Where form builders create and modify forms before they are ready for testing.
QA / Test
Where stage versions are deployed and tested in a live-like environment before promotion to Live.
Development
A dedicated stage for developers to test new platform releases or application changes.
Each stage can be connected to its own Environment (a separate backend with its own database and Form.io server containers), or multiple stages can share an environment. Stage Versions allow you to snapshot a project's forms, resources, actions, and roles and deploy that version from one stage to another, enabling controlled promotion workflows.
Stages can also be placed in Protected Mode, which prevents modifications to forms, resources, roles, and project access, often used for any stage connected to a live application.
The API Layer
One of Form.io's defining characteristics is that every form and resource automatically generates a full REST API. There is no separate step to define or deploy an API. The API is created alongside the form and is functional the moment the form is saved.
API URL Structure
The API is hierarchical, mirroring the project > form >submission structure:
Project
{baseUrl}/{projectName}
https://myenv.com/hrapp
Form / Resource
{projectUrl}/{formPath}
https://myenv.com/hrapp/employee
Submission
{formUrl}/submission/{id}
https://myenv.com/hrapp/employee/submission/abc123
Action
{formUrl}/action/{id}
https://myenv.com/hrapp/employee/action/def456
Role
{projectUrl}/role/{id}
https://myenv.com/hrapp/role/ghi789
Standard HTTP methods apply: GET to read, POST to create, PUT to update, DELETE to remove. Submissions support filtering, pagination, and sorting through query parameters.
Authentication
API requests are authenticated using JSON Web Tokens (JWT). When a user logs in through a Form.io Authentication (usingLogin action) or an OAuth/SAML/LDAP flow, the platform issues a JWT that is included in subsequent API requests as an x-jwt-token header. The server evaluates the token to determine the user's roles and enforces the permission rules described above.
JavaScript SDK
The platform provides a JavaScript SDK (Formio class) that wraps the API and provides convenient methods for common operations. The SDK mirrors the hierarchical URL structure:
The SDK is used internally by the Form.io renderer and is also available for direct use in application code.
API Explorer
The Developer Portal includes a built-in API Explorer (powered by Swagger) that visualizes all the API endpoints generated by the forms and resources in your project. It is a live explorer — requests made through it execute against the real API.
Multi-Tenancy
For SaaS and multi-tenant applications, Form.io supports Multi-Tenancy. This offers the ability to create isolated tenant sub-projects within a single parent project. Each tenant functions as a self-contained project with its own API endpoint, forms, resources, data, authentication, file storage, and access permissions, while inheriting CORS settings from the parent project.
This architecture allows a single deployment to serve multiple customers or organizational units, each with full project-level isolation, managed from a unified Developer Portal interface.
Customer Applications
Through most Form.io documentation Application refers to the Application that developers are building outside of Form.io, and which will embed the Form.io Rendered.
Form.io major components are created within the Form.io system, but are ultimately used in the customer Application. It is important to distinguish a customer Application from the work being completed within Form.io.
How It All Fits Together
The diagram below summarizes the relationships between these concepts:
Last updated
Was this helpful?