mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-05-31 15:26:49 +00:00
212 lines
6.3 KiB
Markdown
212 lines
6.3 KiB
Markdown
---
|
|
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:
|
|
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
|
|
```
|
|
|
|
### 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 |