Fields

​

What are Fields?

A Field in Flatfile is like a column in a spreadsheet — it defines the data type, format, and any constraints for a single piece of data in your import.

Fields are defined inside a Blueprint, which acts as the master schema for your import setup. The hierarchy works like this:

• A Blueprint defines the structure of one or more Workbooks.
• Each Workbook contains Sheets (like tabs in a spreadsheet).
• Each Sheet contains Fields (columns), which describe the individual data points to be collected.

When you configure a Field, you’re telling Flatfile what kind of data to expect in that column—whether it’s text, a number, a date, or another supported type. You can also apply constraints like “required,” “unique,” or custom conditions to control how data is handled during import.

Fields play a key role in ensuring data structure and quality from the moment users start importing.

​

Basic Blueprint Structure

• A Space has one Blueprint
• A Blueprint may contain the configuration for many Workbooks and many Documents
• A Workbook may contain many Sheets and many Workbook-level Actions
• A Sheet may contain many Fields and many Sheet-level Actions

​

Basic Field Configuration

The following examples demonstrate the configuration of isolated fields, which are intended to be used in the context of a Blueprint configuration under a Sheet definition.

​

Simple Field Definition

This example configures a single string Field that is required and another a number Field with a decimalPlaces config.

// Basic string field
const nameField = {
  key: "firstName",
  type: "string",
  label: "First Name",
  description: "The customer's first name",
  required: true,
};

// Number field with config
const ageField = {
  key: "age",
  type: "number",
  label: "Age",
  description: "Customer age in years",
  config: {
    decimalPlaces: 2,
  },
};

​

Field with Multiple Options

This example configures a single enum field with a status key, Customer Status label, and Current status of the customer description. It also defines four options for the field: active, inactive, pending, and suspended.

const statusField = {
  key: "status",
  type: "enum",
  label: "Customer Status",
  description: "Current status of the customer",
  options: [
    { value: "active", label: "Active" },
    { value: "inactive", label: "Inactive" },
    { value: "pending", label: "Pending" },
    { value: "suspended", label: "Suspended" },
  ],
};

​

Field Types

Supported field types for defining data structure:

​

string

A property that should be stored and read as a basic string.

config.appearance
Controls the visual presentation of the string field in the interface.

config.appearance.width
The width of the column in pixels.

{
  "key": "currency",
  "label": "Product Code",
  "type": "string",
  "config": {
    "appearance": {
      "width": 200
    }
  }
}

​

string-list

A property that stores an array of strings. This is useful for fields that need to contain multiple text values.

{
  "key": "tags",
  "label": "Tags",
  "type": "string-list"
}

​

number

A property that should be stored and read as either an integer or floating point number.

config.decimalPlaces
The number of decimal places to preserve accuracy to.

{
  "key": "price",
  "label": "Retail Price",
  "type": "number",
  "config": {
    "decimalPlaces": 2
  }
}

​

enum

Defines an enumerated list of options for the user to select from. The maximum number of options for this list is 100.

config.allow_custom
Permit the user to create new options for this specific field.

config.sortBy
The field to sort the options by (label, value, ordinal).

config.options
An array of valid options the user can select from.

{
  "key": "status",
  "label": "Status",
  "type": "enum",
  "config": {
    "options": [
      {
        "value": "active"
      },
      {
        "value": "inactive",
        "label": "Disabled",
        "meta": {
          "foo": "bar"
        }
      }
    ]
  }
}

​

enum-list

Similar to enum type but allows multiple selections from the options list. The values are stored as an array.

{
  "key": "categories",
  "label": "Categories",
  "type": "enum-list",
  "config": {
    "options": [
      {
        "value": "electronics",
        "label": "Electronics"
      },
      {
        "value": "clothing",
        "label": "Clothing"
      }
    ]
  }
}

​

boolean

A true or false value type. Usually displayed as a checkbox.

config.allowIndeterminate
Allow a neither true or false state to be stored as null.

{
  "key": "is_active",
  "label": "Active",
  "type": "boolean",
  "config": {
    "allowIndeterminate": true
  }
}

​

date

Store a field as a GMT date. Data hooks must convert this value into a YYYY-MM-DD format in order for it to be considered a valid value.

{
  "key": "start_date",
  "label": "Start Date",
  "type": "date"
}

​

reference

Defines a singular one-to-one reference to a field another sheet.

config.ref
The sheet slug of the referenced field. Must be in the same workbook.

config.key
The key of the property to use as the reference key.

{
  "key": "author",
  "type": "reference",
  "label": "Authors",
  "config": {
    "ref": "authors",
    "key": "name"
  }
}

​

reference-list

Defines a reference list referencing a column in another sheet. Enables including multiple values from the given data field.

{
  "key": "author",
  "type": "reference-list",
  "label": "Authors",
  "config": {
    "ref": "authors",
    "key": "name"
  }
}

​

Field-level access

readonly
On a field level you can restrict a user’s interaction with the data to readonly. This feature is useful if you’re inviting others to view uploaded data, but do not want to allow them to edit that field.

"fields": [
  {
    "key": "salary",
    "type": "number",
    "readonly": true
  }
]

​

Field Options

Configurable properties for a Field that define its structure and behavior:

​

Related Concepts

Fields are fundamental to the Flatfile data import process and work closely with:

• Blueprints - Collections of fields that define data structure
• Records - Data instances that conform to field definitions
• Workbooks - Containers that hold Blueprints with sheets and fields
• Listeners - Event handlers that respond to field-level changes
• Actions - Workflows that process field data
• Jobs - Background tasks that validate and transform field data

Fields are the foundation of data structure in Flatfile, defining how your data is organized, validated, and presented during the import process.