The configuration schema of a blueprint consists of 2 parts:
- The blueprint high-level metadata, like its name and a description and the input the blueprint needs from the user.
- The schema of the thing the blueprint describes.
The first part is referred to as the blueprint schema and contains mainly the blueprint’s metadata. The second part depends on what the blueprint is for.
For example, in the case of creating a blueprint for an automation, the full schema for an automation applies.
This page is mainly set up to describe the configuration schema of the blueprint metadata. Try our blueprint tutorial in case you are interested in creating your first blueprint.
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
And this is already a valid blueprint. But typically, one would need more. For example, user inputs or a description to describe the blueprint’s functionality.
This is the full blueprint schema:
The description of the blueprint. While optional, this field is highly recommended. For example, to describe what the blueprint does, or tell more about the options inputs of the blueprint provide. The description can include Markdown.
The domain name this blueprint provides a blueprint for. Currently, only
script are supported.
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.
A short description of the input field. Keep this short and descriptive.
The selector to use for this input. A selector defines how the input is displayed in the frontend UI.
As written in the above schema, a blueprint can accept one (or multiple) inputs from the blueprint consumer.
These inputs can be of any type (string, boolean, list, dictionary), 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
!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, that can be
referred to later on using the
!input my_input custom tag.
In this example, no
selector was provided. In this case, if this blueprint
was used in the user interface, a text input field would be shown to the user.
A blueprint can have as many inputs as you like.
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
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: domain: binary_sensor device_class: motion 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
Additional examples, provided by the community, can be found on the community forum.