Skip to main content

​
Overview

Terra supports importing and exporting forms as JSON, enabling:
  • Backup and restore — Save form schemas for safekeeping
  • Migration — Import forms from legacy systems
  • Sharing — Transfer forms between Terra instances
  • Version control — Track form changes in Git

​
Exporting Forms

​
From the Dashboard

  1. Navigate to Forms and open the form you want to export
  2. Go to Settings (gear icon)
  3. Scroll to the Export Form section
  4. Click Export as JSON
  5. The form schema downloads as {form-slug}.json

​
Export Contents

The exported JSON includes the complete form configuration: 
{
  "version": "1",
  "exportedAt": "2024-01-15T10:30:00.000Z",
  "form": {
    "title": "Housing Application",
    "description": "Apply for housing assistance",
    "schema": {
      "id": "form_1234567890",
      "title": { "en": "Housing Application", "es": "Solicitud de Vivienda" },
      "pages": [...]
    },
    "settings": {
      "languages": ["en", "es"],
      "defaultLanguage": "en",
      "isAnonymous": false,
      "logoUrl": "...",
      "brandColor": "#3B82F6"
    }
  }
}
Exported forms include all translations, field configurations, and display settings. Submission data is never included in exports.

​
Importing Forms

​
From the Dashboard

  1. Navigate to the Forms page
  2. Click the Import button (next to “Create Form”)
  3. Paste your JSON into the text area
  4. Click Import Form
  5. The imported form opens in the builder
You can import into a specific workspace by selecting it before clicking Import.

​
Supported Formats

Terra auto-detects and transforms these formats:
FormatDescriptionAuto-Transform
Terra JSONNative Terra export✅ Direct import
Legacy JSONExternal system format (see below)✅ Automatic conversion

​
Legacy Format Support

Terra can import forms from external systems that use the following structure: 
{
  "version": "0",
  "root": {
    "__t": "GroupedQuestion",
    "config": {
      "questions": [
        {
          "__t": "ChoiceQuestion",
          "name": "state_selection",
          "prompt": {
            "values": [
              { "languageCode": "en-US", "value": "Select your state" },
              { "languageCode": "es-US", "value": "Seleccione su estado" }
            ]
          },
          "config": {
            "options": [...]
          }
        }
      ]
    }
  }
}

​
Type Mapping

Legacy TypeTerra TypeNotes
ChoiceQuestion (single)choiceDropdown or radio
ChoiceQuestion (multiple)multiselectCheckboxes
TextQuestiontextShort text
TextQuestion (multiline)textareaLong text
InfoQuestionstatementMarkdown content blocks
GroupedQuestion—Flattened into elements
AddressQuestionaddressFull address fields
PhoneQuestionphonePhone with validation
EmailQuestionemailEmail with validation
DateQuestiondateDate picker
NumberQuestionnumberNumeric input
FileQuestionfileFile upload

​
Conditional Logic

Legacy conditions are automatically converted: 
// Legacy format
{
  "condition": {
    "operator": "INTERSECTS_WITH",
    "left": { "answerRaw": "state_field" },
    "right": { "arrayOfStrings": ["CA", "NY", "TX"] }
  }
}

// Becomes Terra format
{
  "logic": {
    "condition": {
      "field": "state_field",
      "operator": "is_one_of",
      "value": ["CA", "NY", "TX"]
    },
    "action": "show"
  }
}

​
Language Mapping

Legacy language codes are normalized:
Legacy CodeTerra Code
en-USen
es-USes
Legacy imports create forms in draft status. Review and test before publishing.

​
Duplicate Forms

To create a copy of an existing form:
  1. Open the form’s Settings
  2. Click Duplicate Form
  3. Choose a name for the copy
  4. Click Create Copy
The duplicate includes all fields and settings but no submission data.

​
Best Practices

Export forms before major changes. Store exports in Git alongside your codebase for audit trails.
Always import into a test environment first. Verify all fields, logic, and translations render correctly.
When importing multilingual forms, ensure all target languages are enabled in Terra before import.
Legacy imports preserve original field names when possible. Check for naming conflicts with existing forms.

​
Technical Reference

​
Server Actions

ActionDescriptionParameters
exportFormAsJSON(formId)Export form as JSONformId: string
importFormFromJSON(json, workspaceId?)Import form from JSONjson: string, workspaceId?: string

​
Transformer Functions

// Auto-detect format
function detectAndTransformLegacyFormat(json: object): FormSchema | null

// Transform specific legacy format
function transformLegacyFormToTerra(legacy: LegacyFormat): FormSchema

​
Component Architecture

app/(dashboard)/forms/
├── create-button.tsx     # Contains ImportFormButton
└── client.tsx            # Import dialog integration

lib/
└── form-import-transformer.ts  # Legacy format conversion

​
Troubleshooting

Ensure the JSON is valid. Use a JSON validator to check for syntax errors like trailing commas or unquoted keys.
Some legacy field types may not have direct Terra equivalents. Check the console for transformation warnings.
Logic depends on field names matching exactly. Verify the referenced field exists and the name is spelled correctly.
Statement fields render markdown. Ensure the content uses standard markdown syntax (not HTML).