About 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:

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

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

This is the full blueprint schema:

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 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:

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 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 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 or in a variable script step.

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

Example blueprints

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

Here is the built-in motion light automation blueprint:

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