---
title: "About the blueprint schema"
description: "Introduction to the blueprint schema."
---

## The blueprint schema

The configuration schema of a blueprint consists of 2 parts:

1. The blueprint's high-level metadata: name, description, the input required from the user.
2. The schema of the thing the blueprint describes.

The first part is referred to as the *blueprint schema*. It contains the
blueprint's metadata.

The only requirement for a blueprint is a name. In its most basic form,
a blueprint would look like:

```yaml
blueprint:
  name: Example blueprint
  domain: automation
```

Although this is a valid blueprint, it is not very useful.

The second part depends on the use case of the blueprint. For example, if you create a blueprint for an automation, the full
schema for an [automation](/docs/automation/yaml/) applies.

You can add a description of the blueprint's use case and user inputs.

This is the full blueprint schema:

{% configuration %}
name:
  description: The name of the blueprint. Keep this short and descriptive.
  type: string
  required: true
description:
  description: >
    The description of the blueprint. While optional, this field is highly
    recommended. Describe what the blueprint does and describe the inputs the blueprint provide. The description can
    include [Markdown](https://commonmark.org/help/).
  type: string
  required: false
domain:
  description: >
    The domain in which this blueprint is used. Currently, only
    [`automation`](/docs/automation/yaml/) and `script` are supported.
  type: string
  required: true
author:
  description: The name of the blueprint author.
  type: string
  required: false
homeassistant:
  description: >
    Home Assistant requirements to be able to use the blueprint successfully.
  type: map
  required: false
  keys:
    min_version:
      description: >
        Minimum required version of Home Assistant to use the blueprint. For example,
        `2022.4.0`. It is important to set this if the blueprint uses any features
        introduced in recent releases to head off issues.
      type: string
      required: false
input:
  description: >
    A dictionary of defined user inputs. These are the input fields that the
    consumer of your blueprint can provide using YAML definition, or via
    a configuration form in the UI.
  type: map
  required: false
  keys:
    name:
      description: The name of the input field.
      type: string
      required: false
    description:
      description: >
        A short description of the input field. Keep this short and descriptive.
        The description can include [Markdown](https://commonmark.org/help/).
      type: string
      required: false
    selector:
      description: >
        The [selector](/docs/blueprint/selectors/) to use for this input. A
        selector defines how the input is displayed in the frontend UI.
      type: selector
      required: false
    default:
      description: >
        The default value of this input, in case the input is not provided
        by the user of this blueprint.
      type: any
      required: false
{% endconfiguration %}

### Blueprint inputs

As described above, a blueprint can accept one (or multiple)
inputs from the blueprint user.

These inputs can be of any type (string, boolean, list, dictionary). They can have
a default value and also provide a [selector](/docs/blueprint/selectors/) that
ensures a matching input field in the user interface.

Each input field can be referred to, outside of the blueprint metadata, using
the `!input` custom YAML tag.

The following example shows a minimal blueprint with a single input:

```yaml
blueprint:
  name: Example blueprint
  description: Example showing an input
  input:
    my_input:
      name: Example input
```

In the above example, `my_input` is the identifier of the input. It can be
referenced by using the `!input my_input` custom tag.

In this example, no [`selector`](/docs/blueprint/selectors/) was provided. In the user interface, a text input field would be shown to the user.
It is then up to the user to find out what to enter there. Blueprints that come with [selectors](/docs/blueprint/selectors/) are easier to use.

A blueprint can have as many inputs as you like.

### Blueprint inputs in templates

The inputs are available as custom YAML tags, but not as template variables.
To use a blueprint input in a template, it first needs to be exposed as either
a [script level variable](/integrations/script/#configuration-variables) or in
a [variable script step](/docs/scripts/#variables).

```yaml
variables:
  # Make input my_input available as a script level variable
  my_input: !input my_input
```

### Example blueprints

The [built-in blueprints][blueprint-built-in]
are great examples to get a bit of a feeling of how blueprints work.

Here is the built-in motion light automation blueprint:

```yaml
blueprint:
  name: Motion-activated Light
  description: Turn on a light when motion is detected.
  domain: automation
  input:
    motion_entity:
      name: Motion Sensor
      selector:
        entity:
          filter:
            device_class: motion
            domain: binary_sensor
    light_target:
      name: Light
      selector:
        target:
          entity:
            domain: light
    no_motion_wait:
      name: Wait time
      description: Time to leave the light on after last motion is detected.
      default: 120
      selector:
        number:
          min: 0
          max: 3600
          unit_of_measurement: seconds

# If motion is detected within the delay,
# we restart the script.
mode: restart
max_exceeded: silent

trigger:
  - platform: state
    entity_id: !input motion_entity
    from: "off"
    to: "on"

action:
  - service: light.turn_on
    target: !input light_target
  - wait_for_trigger:
      platform: state
      entity_id: !input motion_entity
      from: "on"
      to: "off"
  - delay: !input no_motion_wait
  - service: light.turn_off
    target: !input light_target
```

### Related information
- [About blueprints](/docs/blueprint/)
- [Blueprint selectors](/docs/blueprint/selectors/)
- [Using blueprints in automations](/docs/automation/using_blueprints/)
- [Tutorial: Create an automation blueprint »](/docs/blueprint/tutorial/)
- [Blueprint community forum][blueprint-forums]

[blueprint-built-in]: https://github.com/home-assistant/core/tree/dev/homeassistant/components/automation/blueprints
[blueprint-forums]: /get-blueprints