Blueprints
Define your data schema to structure exactly how data should look, behave, and connect
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
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 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
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:
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.