Turn existing forms into structured JSON in seconds

Configuration sent by this page

Every request includes a configuration that defines what your builder can render. This demo uses the API defaults with four exceptions: its builder has no file-upload control, treats links as text, does not support branching or formatting in helper text, so a skip instruction in the source (“If No, skip to Part 5”) comes back as a note. A builder that supports branching leaves that setting on and receives the skip in the JSON. You can send your configuration with each request, or we can store it so you only need to pass its ID.

{
  "config": {
    "supports": {
      "kinds": [
        "short_answer",
        "long_answer",
        "single_choice",
        "multi_choice",
        "date",
        "time",
        "number",
        "rating",
        "matrix",
        "ranking",
        "signature"
      ],
      "conditional_visibility": true,
      "branching": false,
      "formatting": {
        "headings": true,
        "questions": true,
        "help_text": false,
        "text": true,
        "list_items": true,
        "markers": {
          "bold": true,
          "italic": true,
          "underline": true,
          "link": true
        },
        "lists": true,
        "tables": false
      }
    },
    "other_followups": "conditional",
    "limits": {
      "max_pages": 200,
      "max_chars": 2000000
    }
  }
}

How this builder maps the JSON

Like yours, our form builder has its own element types and field names. A small set of mappings translates Pufflet's JSON into that vocabulary. These are the mappings used by the demo builder. A row without a note is a direct match: every field carries across unchanged.

Mapping JSON to this builder

This demo uses three mapping tables for text levels, question types and field names, together with the code that applies them. Your integration uses the same approach with values from your own editor.

// Reading Pufflet's form JSON into this builder: three tables and the code that applies them.
// Your builder's version is this file with your own names in the tables.

import type { Form, Item, Question } from "@pufflet/contracts";
import type {
   BuilderElement,
   BuilderForm,
   QuestionElement,
   QuestionType,
   TextElement,
   TextLevel
} from "./types";

// 1. Text. Headings, explanations and the form's own title and intro all
//    become Text elements; this is the level each one gets.
const TEXT: Record<
   | "form_title"
   | "form_description"
   | "section_heading"
   | "section_description"
   | "heading"
   | "explanation",
   TextLevel
> = {
   form_title: "title",
   form_description: "body",
   section_heading: "title",
   section_description: "body",
   heading: "subtitle",
   explanation: "body"
};

// 2. Question kinds → this builder's input types.
const KINDS: Record<Question["kind"], QuestionType> = {
   short_answer: "text",
   long_answer: "textarea",
   single_choice: "radio",
   multi_choice: "checkbox",
   date: "date",
   time: "time",
   number: "number",
   rating: "rating",
   matrix: "matrix",
   ranking: "ranking",
   signature: "signature",
   file_upload: "", // refused: the builder asks for a type (and the API never sends one here)
   text_grid: "", // refused the same way: no text grid here, so the API sends one short answer per cell
   unknown_question: "" // no type chosen; the builder asks for one
};

// 3. Question fields → this builder's field names. Same value, new name.
//    Absent or null in the JSON means absent here. Every JSON field is listed:
//    null means "handled below" (shape changes) or "not copied", so a field
//    added to the JSON later is a compile error here, not a silent drop.
type QuestionField = Question extends infer Q ? (Q extends unknown ? keyof Q : never) : never;
const FIELDS: Record<QuestionField, keyof QuestionElement | null> = {
   id: null,
   kind: null,
   label: null,
   description: "helperText",
   required: "required",
   format: "format",
   choices: "options",
   rows: "rows",
   columns: "columns",
   multi: "multi",
   notes: "notes",
   scale: null,
   show_when: null,
   // Not copied: this builder does not support branching (the demo's config
   // says so, `supports.branching: false`), so the API removes each branch and
   // a branch_dropped note says which answer would have skipped to which
   // section; the form shows every section in order, as the printed form
   // does. A builder that supports branching maps it to a jump between sections.
   branches: null,
   yes_no: null, // handled below
   other: null,
   // Not copied: the source page the item was read from (PDF only) is
   // provenance for a reader checking a note against the document; this
   // builder has nowhere to show it.
   page: null
};

export function readItem(item: Item): BuilderElement {
   if (item.kind === "heading" || item.kind === "explanation") {
      return { id: item.id, type: "page_text", level: TEXT[item.kind], text: item.text };
   }
   const q: QuestionElement = {
      id: item.id,
      type: "question",
      questionType: KINDS[item.kind],
      label: item.label
   };
   const fields = item as Partial<Record<QuestionField, unknown>>;
   for (const from of Object.keys(FIELDS) as QuestionField[]) {
      const to = FIELDS[from];
      const value = fields[from];
      if (to && value !== undefined && value !== null)
         Object.assign(q, { [to]: Array.isArray(value) ? [...value] : value });
   }
   // The few fields whose shape changes, not just their name.
   if (item.kind === "rating") {
      q.scale = {
         min: item.scale.min,
         max: item.scale.max,
         minLabel: item.scale.min_label,
         maxLabel: item.scale.max_label
      };
   }
   if (item.show_when) {
      q.rules = [
         {
            action: "show",
            when: {
               questionId: item.show_when.question,
               operator: item.show_when.operator,
               value: item.show_when.value
            }
         }
      ];
   }
   if ("other" in item && item.other) {
      q.allowOther = true;
      q.otherOptionLabel = item.other.label; // "Other (please specify)"
      q.otherInput = item.other.input; // "none" | "short" | "long"
      if (item.other.prompt !== null) q.otherLabel = item.other.prompt;
      if (item.other.input === "long") q.otherMultiline = true;
   }
   // A yes/no question: the pair the import recognised in the form's own
   // language (2026-09-30), or, for a form from before that field, the
   // English words. The options keep the verbatim words either way, so a
   // condition's value still matches what the respondent picks.
   if (
      item.kind === "single_choice" &&
      !item.other &&
      item.choices.length === 2 &&
      (item.yes_no !== undefined || (item.choices[0] === "Yes" && item.choices[1] === "No"))
   ) {
      q.questionType = "yes_no";
      if (item.yes_no) q.options = [item.yes_no.yes, item.yes_no.no];
   }
   return q;
}

// 1b. Bullets. A run of explanation items marked list: "bullet" is one
//     Text · Bullet list element, one line per item; the ids ride along so
//     the list writes back as the same items.
function readList(items: Item[], start: number): { element: TextElement; end: number } {
   const run: { id: string; text: string }[] = [];
   let end = start;
   for (; end < items.length; end++) {
      const item = items[end];
      if (item.kind !== "explanation" || item.list !== "bullet") break;
      run.push(item);
   }
   return {
      element: {
         id: run[0].id,
         type: "page_text",
         level: "list",
         text: run.map((i) => i.text).join("\n"),
         ids: run.map((i) => i.id)
      },
      end
   };
}

export function readForm(form: Form): BuilderForm {
   const text = (id: string, slot: keyof typeof TEXT, value: string): TextElement => ({
      id,
      type: "page_text",
      level: TEXT[slot],
      text: value
   });
   const elements: BuilderElement[] = [];
   if (form.title !== null) elements.push(text("form_title", "form_title", form.title));
   if (form.description !== null)
      elements.push(text("form_description", "form_description", form.description));
   form.sections.forEach((section, i) => {
      if (i > 0) elements.push({ id: section.id, type: "page_break" });
      if (section.heading !== null)
         elements.push(text(`${section.id}_heading`, "section_heading", section.heading));
      if (section.description !== null)
         elements.push(
            text(`${section.id}_description`, "section_description", section.description)
         );
      for (let k = 0; k < section.items.length;) {
         const item = section.items[k];
         if (item.kind === "explanation" && item.list === "bullet") {
            const { element, end } = readList(section.items, k);
            elements.push(element);
            k = end;
         } else {
            elements.push(readItem(item));
            k++;
         }
      }
   });
   return { elements };
}

Review note codes

Each review note includes a code, a severity and a plain-language message. The API returns all three; the short labels below are used in our demo builder. The severity is “review” when something needs attention, and “info” when the note is merely explanatory.

We recommend displaying all review notes to your users. They explain what changed, why it changed and what may need attention after import.