​
What is a Blueprint?

Blueprints enable you to create repeatable, reliable data import experiences that scale with your needs while maintaining data quality and user experience standards. A Blueprint is your complete data definition in Flatfile. It controls how your data should look, behave, and connect—from simple field validations (like unique and required) to complex relationships between sheets. You can even create filtered reference fields that dynamically control available dropdown options based on other field values. Think of it as an intelligent template that ensures you collect the right data in the right format, every time.
Terminology Note: “Blueprint” is Flatfile’s term for what might be called a “schema” in other systems. Throughout Flatfile’s documentation and API, we use “Blueprint” as the standard term for data structure definitions to distinguish Flatfile’s comprehensive data modeling approach from generic schema concepts.

​
How Blueprints Work

Every Space has exactly one Blueprint that defines its data structure. Whenever a new space is created, the Flatfile Platform automatically triggers a space:configure Job, and you can configure a Listener to pick up that job and configure the new space by defining its Blueprint. Creating workbooks, sheets, and actions is your Blueprint definition, establishing the data schema that will govern all data within that Space. To make that part easier, we have provided the Space Configure Plugin to abstract away the Job/Listener code, allowing you to focus on what matters: Preparing your space for data.

​
Basic Blueprint Structure

A note about Actions: Actions also require a listener to respond to the event published by clicking on them. For more, see Using Actions

​
Example Blueprint Configuration

Recommendation: Although throughout the documentation we’ll be explicitly defining each level of a blueprint, it’s important to note that you can split each of your Workbooks, Sheets, Documents, and Actions definitions into separate files and import them. Then your Workbook blueprint can be as simple as:
const companyWorkbook = {
  name: "Company Workbook",
  documents: [dataProcessingSteps]
  sheets: [usersSheet],
  actions: [exportToCRM],
};
This leads to a more maintainable codebase, and the modularity opens the door for code reuse. For instance, you’ll be able to use usersSheet.slug in your listener code to filter or differentiate between sheets, or re-use exportToSCRM in any other workbook that needs to export data to a CRM.
This example shows a Blueprint definition for Space configuration. It creates a single Workbook with a single Document and a single Sheet containing two Fields and one Action. 
const workbooks = [{
  name: "Company Workbook",
  documents: [
    {
      title: "Data Processing Walkthrough",
      body: "1. Add Data\n2. Process Data\n3. Export Data",
      actions: [
        {
          operation: "confirm",
          label: "Confirm",
          type: "string",
          primary: true,
        },
      ],
    },
  ],
  sheets: [
    {
      name: "Users",
      slug: "users",
      fields: [
        {
          key: "fname",
          type: "string",
          label: "First Name",
        },
        {
          key: "lname",
          type: "string",
          label: "Last Name",
        },
      ],
      actions: [
        {
          operation: "validate-inventory",
          mode: "background",
          label: "Validate Inventory",
          description: "Check product availability against inventory system",
        },
      ],
    },
  ],
  actions: [
    {
      operation: "export-to-crm",
      mode: "foreground",
      label: "Export to CRM",
      description: "Send validated customers to Salesforce",
    },
  ],
}];

​
Workbook Folders and Sheet Collections

Although they have no impact on your data itself or its structure, Workbook Folders and Sheet Collections are a powerful way to organize your data in the Flatfile UI. They are essentially named labels that you assign to your Workbooks and Sheets, which the Flatfile UI interprets to group them together (and apart from others). You can define them directly in your Blueprint when configuring your Space or when otherwise creating or updating a Workbook or Sheet via the API. You can think of Folders and Collections like a filing system:
  • Folders help you organize your Workbooks within a Space (like organizing binders on a shelf).
  • Collections help you organize Sheets within each Workbook (like organizing tabs within a binder).
This is a great way to declutter your Sidebar and keep your data organized and easy to find in the Flatfile UI. In the following example, we have several Workbooks grouped into two Folders:
  • Analytics (folded)
  • Business Operations (unfolded)
The Business Operations Workbooks each contain several Sheets grouped into Collections:
  • Compensation and Personel
  • Stock Management and Vendor Management

An example of Workbooks grouped by Folder and Sheets grouped by Collection