From 5ffbce7738be7904bf36fb0cc7fc5c489824d3ef Mon Sep 17 00:00:00 2001
From: Mark <6531552+MarkusBiggus@users.noreply.github.com>
Date: Wed, 4 Jun 2025 18:30:34 +1000
Subject: [PATCH] Improve blueprint schema explanation (#39318)

---
 source/_docs/blueprint/schema.markdown | 35 +++++++++++++-------------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/source/_docs/blueprint/schema.markdown b/source/_docs/blueprint/schema.markdown
index 02b44b173cb..602caef5a82 100644
--- a/source/_docs/blueprint/schema.markdown
+++ b/source/_docs/blueprint/schema.markdown
@@ -16,16 +16,18 @@ related:
 
 ## The blueprint schema
 
+Blueprint schemas currently supports three types of schema depending on its domain: [`automation`](/docs/automation/yaml/); `script`; and [`template`](/integrations/template/#using-blueprints).
+
 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.
+1. The blueprint's high-level metadata: name, domain and, optionally, any input required from the user.
+2. The schema for the blueprint domain it 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:
+Minimum required metadata for a blueprint is its name and domain. In its most basic form,
+a blueprint looks like:
 
 ```yaml
 blueprint:
@@ -35,10 +37,9 @@ blueprint:
 
 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
+The second part depends on its domain, the type of blueprint. For example, when creating 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:
 
@@ -50,13 +51,13 @@ name:
 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
+    recommended. Describe what the blueprint does and describe the inputs the blueprint requires. 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
+    The domain in which this blueprint is used. Currently, only three types,
     [`automation`](/docs/automation/yaml/), `script` and [`template`](/integrations/template/#using-blueprints) are supported.
   type: string
   required: true
@@ -66,7 +67,7 @@ author:
   required: false
 homeassistant:
   description: >
-    Home Assistant requirements to be able to use the blueprint successfully.
+    Home Assistant version required for the blueprint to work successfully.
   type: map
   required: false
   keys:
@@ -90,10 +91,9 @@ input:
 
 ### Blueprint inputs
 
-As described above, a blueprint can accept one (or multiple)
-inputs from the blueprint user.
+A blueprint can accept one or multiple inputs from the user, but does not require any input.
 
-These inputs can be of any type (string, boolean, list, dictionary). They can have
+These inputs can be of any type (string, boolean, list, map). They can have
 a default value and also provide a [selector](/docs/blueprint/selectors/) that
 ensures a matching input field in the user interface.
 
@@ -126,9 +126,9 @@ A blueprint input has the following configuration:
 {% endconfiguration %}
 
 Each input field can be referred to, outside of the blueprint metadata, using
-the `!input` custom YAML tag.
+the `!input` custom YAML tag before its name.
 
-The following example shows a minimal blueprint with a single input:
+The following example shows a minimal *blueprint schema* with a single input:
 
 ```yaml
 blueprint:
@@ -161,7 +161,7 @@ A section is differentiated from an input by the presence of an additional `inpu
 Input sections are a new feature in version 2024.6.0. Set the `min_version` for the blueprint to at least this version if using input sections. Otherwise, the blueprint will generate errors on older versions. See [this section](/docs/blueprint/schema/#min_version) for more details.
 {% endcaution %}
 
-The full configuration for a section is below:
+The full configuration for an input section is below:
 
 {% configuration %}
 
@@ -194,7 +194,7 @@ input:
 
 
 
-The following example shows a blueprint with some inputs in a section:
+The following example shows a *blueprint schema* with some inputs in a section:
 
 ```yaml
 blueprint:
@@ -232,7 +232,8 @@ variables:
 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:
+Here is the built-in motion light automation blueprint.
+Note the *blueprint schema* under the blueprint key is followed by its domain schema. In this example, an automation schema.
 
 ```yaml
 blueprint: