​
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. 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

Blueprints are a part of your Space configuration. 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 (including defining a Blueprint).

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 configures 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",
    },
  ],
}];

​
Blueprint Relationships

Blueprints work closely with other Flatfile concepts:

  • Workbooks - Containers that hold blueprints and organize data import workflows
  • Fields - Individual column definitions that make up blueprints
  • Sheets - Data tables that implement blueprint structures
  • Records - Individual data rows that conform to blueprint definitions
  • Actions - Custom operations that can be performed on blueprint-structured data

Understanding blueprints is essential for creating effective data import experiences that maintain quality, provide excellent user experiences, and scale with your application’s needs.