> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Blueprint

<Info>
  **Preview**

  This feature is in [Preview](/docs/astro/feature-previews).
</Info>

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](https://github.com/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](/docs/astro/user-permissions) permissions to use the Astro IDE. You need [Workspace Operator](/docs/astro/user-permissions) permissions to start ephemeral test Deployments.
* The [`airflow-blueprint`](https://github.com/astronomer/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).

## Set up blueprints

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

<Steps>
  <Step title="Install the library">
    Add the following line to your project's `requirements.txt`:

    ```text title="requirements.txt" wrap theme={null}
    airflow-blueprint>=0.2.0
    ```
  </Step>

  <Step title="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](https://github.com/astronomer/blueprint).
  </Step>

  <Step title="Create the loader file">
    Create a file at `dags/loader.py` with the following content:

    ```python title="dags/loader.py" wrap theme={null}
    from blueprint import build_all

    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.
  </Step>

  <Step title="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:

    ```sh wrap theme={null}
    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.

    <Note>
      After you add or update a blueprint, regenerate its schema so the Astro IDE picks up the changes.
    </Note>
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Configure the Dag">
    To configure Dag properties such as a description, Dag ID, or schedule, click **DAG Properties**.
  </Step>

  <Step title="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.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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**.
  </Step>
</Steps>

## Test a workflow

After building your workflow, test it in an ephemeral Deployment. See [Test and run code with the Astro IDE](/docs/astro/ide-test-run) 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](/docs/astro/ide-deploy) or [Deploy code from the Astro IDE to Git](/docs/astro/ide-deploy-git).