Forms

Overview

The Forms module provides a schema-driven system for defining data collection interfaces and processing submissions at the platform level. A Form consists of a name and a set of typed Fields that specify what data to collect, validation rules, and conditional logic. Submissions are captured as Entry objects containing the submitted payload.

Forms support two creation paths. You can define a Form with its Fields inline during creation for simple schemas, or create a Form first and add Fields individually afterwards using the field sub-resource endpoints.

The module exposes four resources: Form (the schema container), Field (individual field definitions), Entry (form submissions), and EntryData (normalized field-level submission values).

Before You Start

To use the Forms module you need one of the following access methods configured:

• CLI – See: Getting Started with the CLI
• SDK – See: SDK Installation & Initialization
• REST API – See: API Authentication & Requests

All API requests require the app-id header and a valid Authorization: Bearer <token> header. See: Authentication & Authorization.

When to Use

• Collecting user input through dynamic forms without building custom backend endpoints
• Enforcing field-level validation (required, options, data type, conditional visibility) at the platform level
• Storing submissions in a structured queryable format for downstream processing
• Powering internal tools, onboarding flows, surveys, and lead capture pages
• Triggering automated workflows or notifications on form submission

How It Fits

    flowchart LR
  A[Auth] --> F[Forms]
  F --> N[Notifications]
  F --> FL[Flux]
  F --> FM[File Manager]
  F --> B[Bookmarks]
  

Works Well With

• Auth – Associate form submissions with authenticated users and enforce role-based access to forms
• Notifications – Send email or webhook alerts when a form entry is created
• Flux – Trigger server-side scripts on form submission for custom validation, transformation, or integration logic
• File Manager – Handle file uploads within form fields and store attachments
• Bookmarks – Save frequently accessed forms or entries for quick navigation

Quick Example

This example creates a contact form with two fields and submits an entry.

Creating a form

Define the form schema with name and typed fields.

obx app forms init

obx app forms push init

import { Oblax } from "@oblax/core";
import { platform as browserPlatform } from "@oblax/platform-browser";
import { forms } from "@oblax/forms";

const oblax = new Oblax({
  clientAppId: "<your-oblax-client-appid>",
  platform: browserPlatform(),
  modules: [forms()],
});

const form = await oblax.forms.form.create({
  name: "contact_us",
  fields: [
    {
      name: "email",
      data_type: "string",
      required: true,
    },
    {
      name: "message",
      data_type: "text",
      required: true,
    },
  ],
});

POST /api/v1/forms

{
  "name": "contact_us",
  "fields": [
    {
      "name": "email",
      "data_type": "string",
      "required": true
    },
    {
      "name": "message",
      "data_type": "text",
      "required": true
    }
  ]
}

{
  "id": "frm_abc123def456",
  "name": "contact_us",
  "slug": "contact_us",
  "fields": [
    {
      "id": "fld_abc123def457",
      "form_id": "frm_abc123def456",
      "name": "email",
      "data_type": "string",
      "options": null,
      "required": true,
      "depends_field": "",
      "depends_field_value": ""
    },
    {
      "id": "fld_abc123def458",
      "form_id": "frm_abc123def456",
      "name": "message",
      "data_type": "text",
      "options": null,
      "required": true,
      "depends_field": "",
      "depends_field_value": ""
    }
  ]
}

Submitting an entry to the form

Submit data matching the form schema.

const entry = await oblax.forms.entry.create("frm_abc123def456", {
  email: "jane@example.com",
  message: "Hello from Oblax",
});

POST /api/v1/forms/frm_abc123def456/entries

{
  "email": "jane@example.com",
  "message": "Hello from Oblax"
}

{
  "id": "ent_ghi789jkl012",
  "form_id": "frm_abc123def456",
  "payload": {
    "email": "jane@example.com",
    "message": "Hello from Oblax"
  }
}

Errors

Best Practices

• Create forms with fields inline for simple schemas. Use the field sub-resource endpoints for dynamic or multi-step schema building.
• Use descriptive field names that match your expected payload keys to avoid confusion during entry submission.
• Set required: true on fields that must always be present. Use options to constrain values to a fixed set and depends_field with depends_field_value for conditional visibility.
• Validate entry payloads server-side with custom data type identifiers. The platform enforces required fields, option membership, and conditional field logic automatically.
• Delete fields individually when you need to remove them from a form schema without recreating the entire form.
• Always provide the app-id header and a valid Bearer token on every request. Missing authentication returns a 401.

Related Modules

Auth, Notifications, Flux, File Manager, Bookmarks