Blueprint

Use Blueprint to create Airflow Dags from platform-defined templates in the Astro IDE, without writing Airflow code.

Public Preview

This feature is in

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

1. Install the library
2. Add the following line to your project’s requirements.txt:
3. airflow-blueprint>=0.2.0
   

4. Define blueprints in Python
5. 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.
6. The Astro IDE renders supported Pydantic field types as interactive form fields. The following types are supported:
7. Pydantic typeUI fieldNotesstrStringFieldintNumberFieldstep=1floatNumberFieldboolBooleanFieldLiteral["a","b"]EnumFieldlist[str]ArrayFieldlist[int]ArrayFieldValidates whole numbers on entrylist[float]ArrayFieldValidates numeric input on entrylist (untyped)ArrayFieldTreated as string arrayField(ge=, le=, pattern=, etc.)Constraint propsIncludes exclusiveMin/exclusiveMax, converted to ±1Field(multiple_of=)NumberField stepOnly for float; int always uses step=1Optional[T] / T | NoneUnwraps to T’s fieldConstraints from inner type preservedOptional[Literal["a","b"]]EnumFieldMulti-version blueprintMatched variantMatches by discriminator and selectedVersion; defaults to latest
8. The following types are not supported and render as an unsupported field with a warning in the IDE:
9. Pydantic typeNotesstr | int (true unions)Shows “unsupported schema type” warningNested BaseModellist[Model]list[bool]Text input doesn’t fit true/false valuesdict[str, T]
10. For full details on defining blueprints, including configuration models, field validation, and versioning, see the Blueprint GitHub repository.
11. Create the loader file
12. Create a file at dags/loader.py with the following content:
13. # dags/loader.py
    from blueprint import build_all
    
    build_all()
    

14. 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.
15. Generate JSON schemas
16. 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:
17. blueprint schema <blueprint-name> > blueprint/generated-schemas/<blueprint-name>.schema.json
    

18. 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.
19. After you add or update a blueprint, regenerate its schema so the Astro IDE picks up the changes.

20. Commit the schemas
21. 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
3. Create a workflow
4. 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.
5. To open an existing workflow, select it from the workflow list.
6. Add steps from the library
8. Configure the Dag
9. To configure Dag properties such as a description, Dag ID, or schedule, click DAG Properties.
10. Configure each step
12. 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.

13. Set dependencies between steps
14. To define the order in which steps run, draw a dependency line between them:
16. Steps with no dependencies run in parallel.
17. Set the schedule, description, or Dag ID

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.