Sheets

​

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

• A Blueprint defines the data structure for any number of Spaces
• A Space may contain many Workbooks and many Documents
• A Document contains static documentation and may contain many Document-level Actions
• A Workbook may contain many Sheets and many Workbook-level Actions
• A Sheet may contain many Fields and many Sheet-level Actions
• A Field defines a single column of data, and may contain many Field-level Actions

​

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 access controls.

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.

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

​

Sheet Constraints

Sheet constraints apply validation rules across multiple fields or entire sheets. These constraints ensure data integrity at the sheet level and work in conjunction with field-level constraints.

​

Composite Uniqueness

Ensures that combinations of multiple field values are unique across all records in the sheet. This is useful when individual fields can have duplicate values, but their combination should be unique.

{
  name: "Customers",
  slug: "customers", 
  constraints: [
    {
      name: "unique-customer-location",
      type: "unique",
      fields: ["customerId", "locationId"],
      requiredFields: ["customerId"], // Only enforce when customerId has a value
      strategy: "concat"
    }
  ],
  fields: [
    // field definitions
  ]
}

​

Configuration Properties

Strategy Options:

​

Choosing the Right Strategy

The strategy property determines how uniqueness is calculated. You can choose to simply concatenate the field values as a single string or use a SHA1 hash function to create a unique identifier. Consider the following when choosing a strategy:

Use concat when:

• You aren’t concerned about concatenation collisions (see example below)
• Performance is critical (string concatenation is faster than SHA1)
• You have short/consistent value sizes

Use hash when:

• You want to avoid concatenation collisions
• You aren’t concerned about the performance cost (SHA1 calculation is slower than string concatenation)
• You have long/inconsistent value sizes (SHA1 hashes are always 20 bytes)

Concatenation Collision Example:

In this example, the concat strategy would consider the following records to be duplicates:

  {
    "firstName": "John",
    "lastName": "Smith"
  }

  {
    "firstName": "JohnS",
    "lastName": "mith"
  }

Constraint configuration with concat strategy:

{
  // sheet configuration
  constraints: [
    {
      name: "unique-name-combination",
      type: "unique", 
      fields: ["firstName", "lastName"],
      strategy: "concat" 
    }
  ]
}

This is because both records have the same concatenated value:

"John" + "Smith" = "JohnSmith"
"JohnS" + "mith" = "JohnSmith"

But the hash strategy would prevent this, because the hash function creates a unique identifier based on each field’s invividual value rather than a simple concatenation.

hash(["John", "Smith"]) = "9e03c21f9beff9d943843c1b0623848fe63e2beb"
hash(["JohnS", "mith"]) = "2fd09d2f5e62d980988094b43640966a3bffbde9"

Constraint configuration with hash strategy:

{
  // sheet configuration
  constraints: [
    {
      name: "unique-name-combination",
      type: "unique", 
      fields: ["firstName", "lastName"],
      strategy: "hash" // Prevents collision
    }
  ]
}

​

Conditional Validation with Required Fields

The requiredFields property enables conditional uniqueness validation. When any field specified in requiredFields is empty (null, undefined, or empty string), the entire constraint is ignored for that record.

Use Cases:

• Partial data imports - Allow incomplete records during staged import processes
• Optional relationships - Handle cases where some composite key fields are optional
• Data migration - Gradually enforce constraints as required fields get populated
• Conditional business rules - Only enforce uniqueness when critical fields have values

Important Notes:

• requiredFields should contain only fields that exist in the fields array
• If ANY required field is empty, the constraint is completely ignored
• Empty fields are: null, undefined, or empty strings ("")
• If requiredFields is omitted, the constraint always applies

​

Example: Customer Registration System

Consider a customer registration system where you want unique combinations of email and company, but only when email is provided:

{
  name: "unique-customer-profile",
  type: "unique", 
  fields: ["email", "company"],
  requiredFields: ["email"], // Only enforce when email exists
  strategy: "hash"
}

Data Behavior:

Without requiredFields: All records would be validated, potentially causing errors during partial data imports.

​

Example: Multiple Required Fields

For more complex scenarios, you can specify multiple required fields:

{
  name: "unique-order-item",
  type: "unique",
  fields: ["orderId", "productId", "customerId"], 
  requiredFields: ["orderId", "productId"], // Both must have values
  strategy: "hash"
}

In this case, the constraint only applies when both orderId and productId have non-empty values. If either is empty, the entire constraint is ignored.

​

Sheet Treatments

Sheets have an optional treatments parameter which takes an array of treatments for your Sheet. Treatments can be used to categorize your Sheet and control its behavior. Certain treatments will cause your Sheet to look or behave differently.

​

Reference sheets

Giving your Sheet a treatment of "ENUM_REFERENCE" will mark it as reference data for other sheets. Reference sheets are currently hidden from view, allowing you to generate a number of reference values without adding visual distraction for the user.

const referenceSheet = {
  name: "Countries",
  slug: "countries",
  treatments: ["ENUM_REFERENCE"],
  fields: [
    {
      key: "code",
      type: "string",
      label: "Country Code"
    },
    {
      key: "name", 
      type: "string",
      label: "Country Name"
    }
  ]
};

Currently, "ENUM_REFERENCE" is the only treatment that changes the behavior of your Sheet.

​

Sheet Options

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