Blueprint

Preview

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

Concept	What it is
Blueprint	A reusable building block defined in Python by the platform team. Each blueprint has a configuration schema that controls what users see and configure.
Step	An instance of a blueprint placed on the canvas and configured with specific values.
Workflow	A collection of steps with dependencies and a schedule, stored as a Dag YAML file in your project repository.
Airflow Dag	The production Dag generated automatically from the workflow Dag YAML.

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.

Install the library

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

airflow-blueprint>=0.2.0

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:

Pydantic type	UI field	Notes
`str`	StringField
`int`	NumberField	step=1
`float`	NumberField
`bool`	BooleanField
`Literal["a","b"]`	EnumField
`list[str]`	ArrayField
`list[int]`	ArrayField	Validates whole numbers on entry
`list[float]`	ArrayField	Validates numeric input on entry
`list` (untyped)	ArrayField	Treated as string array
`Field(ge=, le=, pattern=, etc.)`	Constraint props	Includes `exclusiveMin`/`exclusiveMax`, converted to ±1
`Field(multiple_of=)`	NumberField step	Only for `float`; `int` always uses step=1
`Optional[T]` / `T \| None`	Unwraps to T’s field	Constraints from inner type preserved
`Optional[Literal["a","b"]]`	EnumField
Multi-version blueprint	Matched variant	Matches by discriminator and `selectedVersion`; defaults to latest

The following types are not supported and render as an unsupported field with a warning in the IDE:

Pydantic type	Notes
`str \| int` (true unions)	Shows “unsupported schema type” warning
Nested `BaseModel`
`list[Model]`
`list[bool]`	Text input doesn’t fit true/false values
`dict[str, T]`

For full details on defining blueprints, including configuration models, field validation, and versioning, see the Blueprint GitHub repository.

Create the loader file

Create a file at dags/loader.py with the following content:

1 # dags/loader.py
2 from blueprint import build_all
3 
4 build_all()

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.

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:

$ blueprint schema <blueprint-name> > blueprint/generated-schemas/<blueprint-name>.schema.json

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.

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.

Open Blueprint mode

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

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.

Add steps from the library

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

Configure the Dag

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

Configure each step

Click a step on the canvas to open its configuration form in the right panel.
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.

Set dependencies between steps

To define the order in which steps run, draw a dependency line between them:

Hover over the step that should run first. A connection point appears at the edge.
Click and drag from that connection point to the next step.
Release to create the dependency. An arrow appears between the two steps.

Steps with no dependencies run in parallel.

Set the schedule, description, or Dag ID

Open the DAG Properties panel.
Enter a cron expression in the Schedule field.
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.