Skip to main content
PreviewThis feature is in Preview.
Blueprint is a template-based Dag authoring mode in the Astro IDE. Platform teams define reusable building blocks in Python. Analysts, analytics engineers, and data scientists assemble those blocks into production Dags through a visual builder and form-driven configuration, without writing Airflow code. The open-source astronomer/blueprint library powers Blueprint in the Astro IDE, handling blueprint definition, YAML parsing, validation, and Dag generation. See the GitHub repository for the full API reference, blueprint authoring guide, and examples.

​
How Blueprint works

Blueprint has two sides: platform teams define blueprints; other team members use them.

​
Prerequisites

  • An Astro Workspace with Astro IDE access.
  • Workspace Author permissions to use the Astro IDE. You need Workspace Operator permissions to start ephemeral test Deployments.
  • The airflow-blueprint library (version 0.2.0 or later) added to your project’s requirements.txt.
  • At least one blueprint defined in your project with its JSON schema generated. See Set up blueprints.

​
Set up blueprints

Platform teams complete this setup so blueprints appear in the Astro IDE library for other team members to use.
1

Install the library

Add the following line to your project’s requirements.txt:
requirements.txt
2

Define blueprints in Python

Create blueprint files in your project under dags/templates/. Each blueprint is a Python class that defines a configuration schema and a render() method. The field descriptions you write become the form labels users see in the IDE.The Astro IDE renders supported Pydantic field types as interactive form fields. The following types are supported:The following types are not supported and render as an unsupported field with a warning in the IDE:For full details on defining blueprints, including configuration models, field validation, and versioning, see the Blueprint GitHub repository.
3

Create the loader file

Create a file at dags/loader.py with the following content:
dags/loader.py
Airflow scans the dags/ folder for Python files that contain Dag objects. This file tells Blueprint to discover all .dag.yaml files in your project, parse them, and register the resulting Dags with Airflow automatically.
4

Generate JSON schemas

For the Astro IDE to discover your blueprints, generate a JSON schema for each blueprint and output it to blueprint/generated-schemas/ in your project:
Repeat this command for each blueprint. The IDE reads this folder to determine which blueprints are available and uses the schemas to render configuration forms.
After you add or update a blueprint, regenerate its schema so the Astro IDE picks up the changes.
5

Commit the schemas

Commit the generated schema files in blueprint/generated-schemas/ to your repository so the IDE can read them when you or your team members open the project.

​
Build a workflow with Blueprint

After your platform team has set up blueprints, other team members can build workflows in the Astro IDE without writing Airflow code.
1

Open Blueprint mode

  1. Open your project in the Astro IDE.
  2. Click the Blueprint toggle in the top navigation bar. The interface switches to Blueprint mode.
2

Create a workflow

Click New DAG to create a new workflow. Enter a Dag ID and click Generate DAG. Blueprint creates a new Dag YAML file in your project’s dags/ folder.To open an existing workflow, select it from the workflow list.
3

Add steps from the library

  1. Browse the library panel on the left side of the canvas. The library shows all blueprints your platform team has defined and registered.
  2. Drag a blueprint from the library onto the canvas. Each item you add to the canvas is a step.
  3. Repeat to add more steps.
4

Configure the Dag

To configure Dag properties such as a description, Dag ID, or schedule, click DAG Properties.
5

Configure each step

  1. Click a step on the canvas to open its configuration form in the right panel.
  2. Fill in the fields your platform team has exposed. The IDE marks required fields. Field descriptions explain what each value controls.
The configuration form only shows fields your platform team has explicitly exposed. Operational settings like retry logic, connection credentials, and default values are baked into the blueprint.
6

Set dependencies between steps

To define the order in which steps run, draw a dependency line between them:
  1. Hover over the step that should run first. A connection point appears at the edge.
  2. Click and drag from that connection point to the next step.
  3. Release to create the dependency. An arrow appears between the two steps.
Steps with no dependencies run in parallel.
7

Set the schedule, description, or Dag ID

  1. Open the DAG Properties panel.
  2. Enter a cron expression in the Schedule field.
  3. Configure any additional pipeline-level settings such as Description.

​
Test a workflow

After building your workflow, test it in an ephemeral Deployment. See Test and run code with the Astro IDE for instructions.

​
Fix issues

If a task fails or produces unexpected output:
  • Edit the configuration directly: Click the step on the canvas to reopen its configuration form and adjust the values.
  • Use Ask AI to Fix: Click Ask AI to Fix next to an error message for AI-generated suggestions on how to resolve the issue.
After making changes, click Sync to Test to push the updated configuration to the running Deployment without restarting it.

​
Commit and deploy

After testing, commit your workflow and deploy it. See Deploy code from the Astro IDE or Deploy code from the Astro IDE to Git.