Schema and validation

Start from the schema shape#

A form schema is the shared contract used by the builder, SDK renderers, public API, response validation, exports, and delivery. JSX and defineForm() produce the same schema. The code form id is the workspace-stable sync handle; Fillo returns a separate canonical formId for published links and submissions.

Every schema has version: 1, a title, at least one page, an ordered block list, and settings. Fields create answers. Content blocks shape the reading flow without adding answer keys.

import { defineForm } from "@usefillo/core";

export const supportIntake = defineForm({
  id: "support-intake",
  title: "Tell us what happened",
  pages: [
    {
      id: "request",
      blocks: [
        {
          id: "topic",
          kind: "select",
          label: "What do you need help with?",
          required: true,
          options: [
            { id: "billing", label: "Billing" },
            { id: "technical", label: "Technical issue" },
          ],
        },
        {
          id: "details",
          kind: "long_text",
          label: "Tell us more about {{topic}}",
          required: true,
          visibleIf: [{ fieldId: "topic", op: "answered" }],
        },
        {
          id: "account_id",
          kind: "hidden",
          paramName: "account",
        },
      ],
    },
  ],
  settings: { showProgress: true, saveProgress: true },
});

Treat every id as stored data#

• Use a permanent code form handle. Reusing it updates the same Fillo form; changing it creates a different sync identity.
• Page ids must be unique within the form. Block ids must be unique across every page because field ids become keys in ResponseData.
• Choice option ids, ranking option ids, and matrix row and column ids are stored answer values. Labels may change without rewriting those values.
• Ids are strings from 1 to 128 characters. Never derive them from array position, visible copy, translated labels, or a random value generated during render.
• A schema supports 1 to 50 pages, up to 500 blocks per page, and up to 200 options, rows, or columns in one list.

Field kinds and answer shapes#

Every field accepts id, label, optional description, required, placeholder, and visibleIf where those properties apply. The table adds each kind's stored answer shape and field-specific rules.

Content blocks#

Content blocks belong in the same ordered blocks array as fields. They need stable block ids for durable schema structure and may carry visibleIf, but they never create a response value.

Read and write response data by field id#

• ResponseData is an object keyed by field id. Optional unanswered fields are absent; do not depend on every schema field having a key.
• Choice fields store option ids. Use Fillo's formatting helpers or the response formatted payload when a destination needs labels.
• Numbers, ratings, and scales are stored as numbers after normalization. Matrix answers map row ids to column ids. Files are arrays of completed file references.
• A custom field may store any JSON value. Its renderer and your downstream code must agree on the shape.
• Each response is anchored to the schema version it answered. The response grid and CSV retain removed field ids, while live integrations work from the current schema.

Validation runs at schema and response boundaries#

• Fillo normalizes and validates untrusted schemas before storing or rendering them. Invalid top-level shapes, unknown kinds, duplicate ids, invalid number ranges, and unsupported schema versions fail. Malformed field blocks such as a choice with no valid options are removed, and a schema with no valid block is rejected.
• The client gives immediate field feedback, but the submission API validates the response again. Treat the server result as authoritative.
• Only fields visible for the submitted answers are validated and retained. A stale answer from a field hidden by logic is removed from the accepted data.
• Strings are trimmed except custom-field strings. Numeric strings are normalized for number, rating, and scale fields. Phone answers receive authoritative server validation and E.164 normalization.
• File answers are accepted only after the upload protocol has created and verified the referenced file for the same form.

Model choices with stable option ids#

• Store machine-friendly option ids such as technical; show respondents changeable labels such as Technical issue.
• allowOther stores the respondent's text directly when it is not a declared option id. Downstream code must handle both declared ids and free text.
• shuffleOptions changes presentation order only. It does not change the option list or stored values.
• A ranking answer contains every option id in respondent order. Adding or removing ranking options changes the required answer set.
• Matrix rows and columns each have their own stable ids. A required matrix must contain one valid column id for every row.

Use visibleIf for conditional structure#

Attach visibleIf to a field or content block. Every condition in the array must match, so multiple conditions use AND behavior. Reference the controller by field id and compare choice answers to option ids, not labels.

Pipe answers into respondent-facing copy#

Use {{field_id}} in a field label or description, or in heading and paragraph text. Fillo substitutes the current answer for display only. Choice ids become option labels, arrays join with commas, and an unanswered field becomes an empty string.

Piping does not change stored answers and is not a templating or authorization system. Never put a secret in a schema and expect a conditional block or piping token to hide it from someone who can load the published schema.

Know who owns each setting#

All settings are part of FormSchema, but a browser-visible pk_ sync cannot control settings with mail or pre-submission privacy effects. On public-key sync, Fillo strips those values from a new form and preserves the dashboard value on an existing form.

Make version-safe schema changes#

1. 1

   Prefer additive optional fields

   An optional field does not block an older client or a respondent who never sees it. A new visible required field changes what a valid submission needs.

2. 2

   Change copy without changing ids

   Labels, descriptions, placeholders, and option labels may evolve while stable ids preserve raw answers and downstream keys.

3. 3

   Use a new id for a new answer shape

   Changing a field from select to multi_select, or reusing an old option id for a different meaning, makes one key represent incompatible data. Add a new field instead.

4. 4

   Review logic and piping references

   When removing a field or option, search visibleIf, piping tokens, response limits, prefill, webhooks, exports, and destination mappings for its id.

5. 5

   Stage and test the published path

   Public-key sync stages changes on claimed live forms. Test conditional branches, validation, uploads, and a real response before publishing. A private CLI push publishes directly unless you use --draft.

Next steps#