​
What are Sheets?

Sheets are individual data tables within Workbooks that organize and structure imported data. Each Sheet represents a distinct data type or entity, similar to tables in a database or tabs in a spreadsheet.

Sheets serve as containers for Records and are defined by Blueprints that specify their structure, validation rules, and data types. They provide the fundamental building blocks for organizing data within the Flatfile platform.

​
Basic Blueprint Structure

​
Basic Sheet Definition

The following examples demonstrate the configuration of isolated Sheets, which are intended to be used in the context of a Workbook configuration.

​
Single-Sheet Sheet Configuration

This example configures a single Sheet containing three Fields and one Action and defining

const customerSheet = {
  name: "Customers",
  slug: "customers",
  fields: [
    {
      key: "firstName",
      type: "string",
      label: "First Name",
      constraints: [{ type: "required" }],
    },
    {
      key: "email",
      type: "string",
      label: "Email Address",
      constraints: [{ type: "required" }, { type: "unique" }],
    },
    {
      key: "company",
      type: "string",
      label: "Company Name",
    },
  ],
  access: ["add", "edit", "delete"],
  actions: [
    {
      operation: "validate-inventory",
      mode: "background",
      label: "Validate Inventory",
      description: "Check product availability against inventory system",
    },
  ],
};

​
Sheet level access

With access you can control Sheet-level access for users.

Access LevelDescription
"*" (default)A user can use all access actions to this Sheet
"add"A user can add a record(s) to the Sheet
"delete"A user can delete record(s) from the Sheet
"edit"A user can edit records (field values) in the Sheet
"import"A user can import CSVs to this Sheet
<empty>If no parameters are specified in the access array, sheet-level readOnly access will be applied

If you use "*" access control, users will gain new functionalities as we expand access controls. Use an exhaustive list today to block future functionality from being added automatically.

{
  "sheets": [
    {
      "name": "Contacts",
      "slug": "contacts",
      "access": ["add", "edit"]
      // Define fields
    }
  ]
}

​
Sheet Options

Configurable properties for a Sheet that control its behavior and appearance:

OptionTypeRequiredDescription
namestring✓The name of your Sheet as it will appear to your end users
descriptionstringA sentence or two describing the purpose of your Sheet
slugstringA unique identifier for your Sheet. Used to reference your Sheet in code, for example in a Record Hook
readonlybooleanA boolean specifying whether or not this sheet is read only. Read only sheets are not editable by end users
allowAdditionalFieldsbooleanWhen set to true, your Sheet will accept additional fields beyond what you specify in its configuration. These additional fields can be added via API, or by end users during the file import process
accessarrayAn array specifying the access controls for this Sheet. Read more about access controls
fieldsarray✓This is where you define your Sheet’s data schema. The collection of fields in your Sheet determines the shape of data you wish to accept
actionsarrayAn array of actions that end users can perform on this Sheet. Read more about actions
metadataobjectUse metadata to store any extra contextual information about your Sheet. Must be valid JSON
mappingConfidenceThresholdnumberConfigure the minimum required confidence for mapping jobs targeting that sheet (default: 0.5). Must be greater than 0 and less than or equal to 1
  • Workbooks - Containers that hold multiple sheets
  • Blueprints - Define the structure and validation rules for sheets
  • Records - Individual rows of data within sheets
  • Fields - Individual columns that define data structure
  • Actions - Custom operations that can be performed on sheet data