> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Editing a Formbricks File

> The Formbricks file format for people and AI assistants: its envelope, its JSON Schema, what you can change, what an Update replaces, and what each import error means.

A Formbricks file (`.formbricks.json`) is a survey written as JSON. You can edit it in any text editor, or hand it to an AI assistant such as ChatGPT or Claude, then import it back. It's the way to iterate on a survey with an assistant that isn't connected to Formbricks.

**1. Export the survey**

On the survey's card, open **⋮ → Export → Formbricks file (.json)**. See [Import & Export](https://formbricks.com/docs/surveys/import-export/overview.md#export-a-survey).

**2. Edit the file**

Change it by hand, or give it to your assistant along with this page and the [JSON Schema](#the-json-schema).

**3. Import it**

Go to **Surveys → New Survey → Import survey** and drop the file. In the workspace the survey came from,
choose **Update** to change it in place, or **Create a new survey** for a copy.

An invalid file creates nothing, so you can fix it and try again as often as you need. A file you have already used for an Update keeps working: the dialog tells you the survey changed since the export and offers **Update anyway**.

## The envelope

Every file has four keys at the top:

```json theme={null}
{
  "$schema": "https://formbricks.com/docs/schemas/formbricks-file/v1.json",
  "formbricks": {
    "format": 1,
    "exportedAt": "2026-10-30T12:00:00.000Z",
    "appVersion": "6.2.0",
    "source": {
      "surveyId": "clsurvey0000000000000001",
      "workspaceId": "clworkspace0000000000001",
      "updatedAt": "2026-10-29T11:30:00.000Z"
    }
  },
  "survey": {
    "name": "Onboarding NPS",
    "type": "link",
    "defaultLanguage": "en-US",
    "languages": [
      { "code": "en-US", "default": true, "enabled": true },
      { "code": "de-DE", "default": false, "enabled": true }
    ],
    "blocks": [
      {
        "id": "clblock00000000000000001",
        "name": "Block 1",
        "elements": [
          {
            "id": "nps",
            "type": "nps",
            "headline": {
              "en-US": "How likely are you to recommend us?",
              "de-DE": "Wie wahrscheinlich ist es, dass Sie uns weiterempfehlen?"
            },
            "required": true
          }
        ]
      }
    ]
  },
  "references": {
    "actionClasses": [],
    "attributeKeys": [],
    "embeddedFields": []
  }
}
```

| Key | What it is |
| - | - |
| `$schema` | The address of the file's [JSON Schema](#the-json-schema). Optional. |
| `formbricks` | About the file: its `format`, when it was exported, the Formbricks version that wrote it, and its `source`. |
| `formbricks.source` | The survey and workspace it came from, and when the survey last changed before the export. An import uses these to offer **Update**. |
| `survey` | The survey: the same document the [API v3](https://formbricks.com/docs/api-v3-reference/introduction.md) creates a survey from, without `workspaceId` and `metadata` (the link's share preview, which stays with the survey). |
| `references` | What the survey uses from its workspace: `actionClasses` its triggers use, `attributeKeys` its targeting names, and shared `embeddedFields`. `languages` is optional: it lists only the survey's languages that have a name in the workspace, with that name. |

`format` is the file format's own version, separate from the Formbricks version. Formbricks reads every format up to its own and refuses newer ones.

## The JSON Schema

Every file names its JSON Schema in `$schema`:

[`https://formbricks.com/docs/schemas/formbricks-file/v1.json`](https://formbricks.com/docs/schemas/formbricks-file/v1.json)

It describes every key the format allows, every question type and the fields each one needs. Editors such as VS Code use it to check the file as you type. Give the address to an AI assistant and it can check its own output before you import.

The schema can't express every rule. The import also checks that logic and recall point at questions, variables and hidden fields that exist, that every text is in every language the survey declares, and that IDs are unique. Each problem it finds names the field, so you know where to look.

## What you can edit

Anything under `survey`. Some rules keep the file importable:

* **Texts** are objects keyed by language code: `{ "en-US": "…", "de-DE": "…" }`. Give each text in every language listed in `languages`, and use no other codes.
* **IDs.** Keep the IDs of what you don't change: logic, recall and existing responses point at them. A new question needs its own ID, unique in the survey, made of letters, numbers, `-` and `_`. A new block needs an ID of lowercase letters and numbers.
* **Codes.** Questions and options carry the `code` the survey gave them, which exports use. Once a survey has left draft, an Update can't change a code, a question's type or an option's text, and can't remove an option.
* **Logic and recall** point at questions by ID. Logic can only check a question in the same or an earlier block, and recall can only use a question shown before it.
* **Show-ifs and rules before the first question.** A block, question or option shows only when its `showIf` matches, and `startLogic` holds the rules that run before the first question. Both follow the rules of logic; a rule before the first question can't read an answer, since nothing is answered yet.
* **Embedded Data.** `embeddedFields` lists every hidden field, variable and calculated field with its type; a calculated date field is only there, not in `variables`. `hiddenFields` and `variables` are the older form of the same list: change `embeddedFields` with them, or the import refuses the file and names each field that disagrees. Create new skips this check for an empty `variables` list or an empty `hiddenFields.fieldIds` list, so a field you remove from that list alone stays in the survey. Update checks empty lists too. A shared field carries its library `key`: it links to the target workspace's field with the same key, source and type, or else becomes a field of the survey's own.
* **Triggers** (app surveys) point at an action by its ID in `references.actionClasses`. Add the action there when you add a trigger.
* **Targeting filters** that name a contact attribute need that attribute in `references.attributeKeys`. An attribute the workspace doesn't have yet is created, so its key must be lowercase letters, numbers and underscores, starting with a letter, and not one Formbricks reserves (`user_id`, `first_name`, `last_name`).
* **`name`** is used for a new survey, with "(imported)" added. An Update keeps the survey's own name.
* **`status`** is ignored. An import always creates a draft, and an Update keeps the survey's status.

Leave `formbricks` as it was exported. `source.surveyId` is how Formbricks finds the survey to update, and `source.updatedAt` is how it notices the survey changed after the export. Changing it doesn't make the file a new survey by itself: if it matches another survey in the workspace, the import offers to update that one. For a new survey, use an ID that matches none, or choose **Create new** when the import finds a match, and check which survey a match names before you choose **Update**.

Keys the format doesn't know are dropped with a warning each in the import report, so a key an assistant invents doesn't block the import. A file exported before the share preview was left out still carries `survey.metadata`: it is dropped the same way, with one warning, and never written to a survey.

### Writing a file from scratch

You can write a file without exporting one first. It needs the whole `formbricks` part, with `format` set to `1` and a `source` whose IDs are made of lowercase letters and numbers. Use made-up IDs: a `surveyId` that matches no survey in the workspace makes the import create a new survey. The quickest start is to export any survey and replace its content.

## What Update replaces

Update replaces the survey's:

* questions, blocks and endings, and the welcome card;
* languages and translations, and the language switch settings;
* hidden fields, variables and calculated fields (`embeddedFields`);
* logic, the rules before the first question, show-ifs and targeting;
* triggers, only when **Use the file's triggers** is ticked.

A file without a `startLogic` key, such as one exported before the flow editor, keeps the survey's rules before the first question. To remove them, add `"startLogic": []` to the file.

It keeps the survey's ID, name, status, responses, display and link settings, styling and other settings. It never updates an active survey. See [Update a survey from a file](https://formbricks.com/docs/surveys/import-export/overview.md#update-a-survey-from-a-file) for the choices the dialog offers.

Two parts of the file must match the survey: its `type` (link or app) and its `defaultLanguage`. To change either, import the file as a new survey.

## Common errors

When a file has problems, the dialog says **This Formbricks file has problems. Fix them and import it again:** and lists up to ten of them, each as the field and the reason. Fields are named from the top of the file: `file.survey.blocks.0.elements.1.headline` is the headline of the second question in the first block. Nothing is created until every problem is fixed.

Behind the dialog, the import answers with an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem whose `code` is `formbricks_file_invalid`. Each entry of its `invalid_params` has the field's `name`, the `reason`, and often a `code`:

| Code | Example reason | What to do |
| - | - | - |
| (none) | `Invalid input: expected string, received number`, `Invalid input: expected array, received undefined` | The value has the wrong type, is missing a field its question type needs (like a choice question's `choices`), or isn't one the field allows. Check it against the [JSON Schema](#the-json-schema). |
| `missing_required_field` | `Missing required field 'headline' for element type 'openText'` | Add the field. Every question needs an `id`, a `type`, a `headline` and `required`. |
| `missing_translation` | `Translatable field is missing configured language 'de-DE'` | Add the text in that language, or remove the language from `languages`. |
| `unsupported_locale` | `Language 'fr-FR' must be declared in languages before it can be used in translatable content` | Add the language to `languages`, or remove the text in that code. |
| `invalid_locale`, `duplicate_locale` | `Language key 'xx' is not a valid locale code` | Use one valid code per language, like `de-DE`. |
| `dangling_reference` | `Element id 'q9' is not defined in blocks`, `The action class this trigger uses is not in references.actionClasses` | Logic, recall, a trigger or a targeting filter points at something the file doesn't have. Add it, or fix the ID. |
| `misordered_reference` | `Condition references element 'q5' in a later block …` | Logic checks a later block, or recall uses a question shown after it. Move the question, or point at an earlier one. |
| `duplicate_identifier` | `Element id 'q1' is duplicated; first used at blocks.0.elements.0` | Give each question, block, option, ending, hidden field and variable its own ID. |
| `immutable_identifier` | `Element id 'q1' cannot be changed because the survey and element are no longer drafts` | An Update can't change the ID of a question that has been live. Keep the old ID, or import the file as a new survey. |
| `immutable_question_code`, `immutable_answer_code`, `immutable_question_type`, `immutable_option_text`, `immutable_option_deletion` | A code, type or option text that changed, or an option that was removed | Once a survey has left draft, an Update keeps its codes, question types, option texts and options. Restore them, or import the file as a new survey. |
| `read_only_field` | `Field 'type' is immutable after creation; …` | An Update can't change `type` or `defaultLanguage`. Keep them, or import the file as a new survey. |
| `limit_exceeded` | `A question takes at most 200 choices`, `A text must not exceed 50000 characters`, `Importing this survey adds 12 attribute keys, past the 150 a workspace can have` | A question can have up to 200 choices, or 200 matrix rows and 200 columns, and a text up to 50,000 characters in each language. Split the question or shorten the text. For attribute keys, remove unused contact attributes from the workspace, or the filters that need them. |

Other messages the dialog shows for a Formbricks file:

| Message | What it means |
| - | - |
| This kind of file cannot be imported. | The file isn't JSON with a `formbricks` part at the top, so Formbricks doesn't see a Formbricks file. |
| This file could not be read. | The JSON is broken, for example a missing comma or quote. |
| This file was exported from a newer version of Formbricks. | `formbricks.format` is newer than this instance reads. Update Formbricks, or export the survey again from an instance on the same version. |
| This file is too large or too complex to import. | The JSON nests deeper than 256 levels, has an array of more than 1,000 items, or more than 50,000 items in all, or takes Formbricks more than 15 seconds to read. |
| The survey in this file is too large to import. | `survey` is larger than about 2 MB as JSON. |
| This file is larger than 15 MB. | The whole file is past the upload limit. |
| The survey went live after this review… | You chose Update, and the survey became active before you clicked. Save the file as a new survey instead. |
| The survey changed again after this review. | You chose **Update anyway**, and someone changed the survey once more. Pick the file again to review it against the latest version. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.