diff --git a/source/_docs/blueprint/schema.markdown b/source/_docs/blueprint/schema.markdown index e1a06fdf79b..3b1f7326764 100644 --- a/source/_docs/blueprint/schema.markdown +++ b/source/_docs/blueprint/schema.markdown @@ -1,25 +1,17 @@ --- -title: "Blueprint schema" -description: "The schema for a valid blueprint." +title: "About the blueprint schema" +description: "Introduction to the blueprint schema." --- +## The blueprint schema + 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. +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 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](/docs/automation/yaml/) applies. - -This page is mainly set up to describe the configuration schema of the -blueprint metadata. Try our [blueprint tutorial](/docs/blueprint/tutorial/) -in case you are interested in creating your first blueprint. - -## The blueprint schema +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: @@ -30,9 +22,12 @@ 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. +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: @@ -44,15 +39,14 @@ name: description: description: > 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 + 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 name this blueprint provides a blueprint for. Currently, only - `automation` and `script` are supported. + The domain in which this blueprint is used. Currently, only + [`automation`](/docs/automation/yaml/) and `script` are supported. type: string required: true author: @@ -67,7 +61,7 @@ homeassistant: keys: min_version: description: > - Minimum required version of Home Assistant to use the blueprint (e.g. + 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 @@ -104,12 +98,12 @@ input: required: false {% endconfiguration %} -## Blueprint inputs +### Blueprint inputs -As written in the above schema, a blueprint can accept one (or multiple) -inputs from the blueprint consumer. +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), can have +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. @@ -127,11 +121,11 @@ blueprint: 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 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 this case, if this blueprint -was used in the user interface, a text input field would be shown to the user. +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. @@ -148,7 +142,7 @@ variables: my_input: !input my_input ``` -## Example blueprints +### Example blueprints The [built-in blueprints][blueprint-built-in] are great examples to get a bit of a feeling of how blueprints work. @@ -207,8 +201,12 @@ action: target: !input light_target ``` -Additional examples, provided by the community, can be found on the -[community forum][blueprint-forums]. +### 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 +[blueprint-forums]: /get-blueprints \ No newline at end of file diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html index 78e94865803..8a4e2ece122 100644 --- a/source/_includes/asides/docs_navigation.html +++ b/source/_includes/asides/docs_navigation.html @@ -110,7 +110,7 @@ {% active_link /docs/blueprint/ Blueprints %}