Improve blueprint schema explanation #39318
Conversation
Explain blueprint domain more clearly using consistent language with previously defined terms to describe schema components.
Explain blueprint domain more clearly using consistent language with previously defined terms to describe schema components.
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThe blueprint schema documentation was revised to clarify metadata fields, explicitly list supported domain types, refine input descriptions, and update terminology. The required metadata now includes both name and domain. Guidance on input types, referencing, and version requirements was improved, and example sections were updated for consistency and clarity. Changes
Sequence Diagram(s)No sequence diagram generated as the changes are limited to documentation updates. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
source/_docs/blueprint/schema.markdown (5)
19-19: Correct plural agreement in subject–verb
The sentence reads “Blueprint schemas currently supports…” but “schemas” is plural and should pair with “support.”
Apply this diff:- Blueprint schemas currently supports three types of schema depending on its domain: + Blueprint schemas currently support three domain types—automation, script, and template:🧰 Tools
🪛 LanguageTool
[grammar] ~19-~19: It seems that the correct verb form here is “support”.
Context: ...int schema Blueprint schemas currently supports three types of schema depending on its ...(AGREEMENT_SENT_START_2)
23-24: Use consistent serial comma and wording
Consider rephrasing the list for clarity and consistency with the rest of the doc:- 1. The blueprint's high-level metadata: name, domain and, optionally, any input required from the user. + 1. The blueprint's high-level metadata: name, domain, and optionally any inputs required from the user.
53-56: Avoid repetitive phrasing in description
Instead of “Describe what the blueprint does and describe the inputs…,” streamline to:- Describe what the blueprint does and describe the inputs the blueprint requires. + Explain the blueprint’s functionality and the inputs it requires.🧰 Tools
🪛 LanguageTool
[uncategorized] ~54-~54: Possible missing comma found.
Context: ...ecommended. Describe what the blueprint does and describe the inputs the blueprint r...(AI_HYDRA_LEO_MISSING_COMMA)
58-63: Refine domain listing for readability
List the supported domains in a single, clear sentence:- 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. + The domain in which this blueprint is used. Currently, only three domains are supported: [`automation`](/docs/automation/yaml/), `script`, and [`template`](/integrations/template/#using-blueprints).
94-94: Use “one or more” for numerical consistency
Replace “one or multiple” with the more conventional “one or more”:- A blueprint can accept one or multiple inputs from the user, but does not require any input. + A blueprint can accept one or more inputs from the user but does not require any.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge Base: Disabled due to data retention organization setting
📒 Files selected for processing (1)
source/_docs/blueprint/schema.markdown(9 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_docs/blueprint/schema.markdown
[grammar] ~19-~19: It seems that the correct verb form here is “support”.
Context: ...int schema Blueprint schemas currently supports three types of schema depending on its ...
(AGREEMENT_SENT_START_2)
[uncategorized] ~54-~54: Possible missing comma found.
Context: ...ecommended. Describe what the blueprint does and describe the inputs the blueprint r...
(AI_HYDRA_LEO_MISSING_COMMA)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
🔇 Additional comments (6)
source/_docs/blueprint/schema.markdown (6)
68-72: Approve clear homeassistant version description
The updated description clearly specifies the required Home Assistant version.
96-98: Approve updated input type enumeration
The change to “string, boolean, list, map” aligns with schema terminology and is clear.
128-132: Approve clarification of!inputtag usage
The wording now explicitly notes the tag precedes the input name, improving clarity.🧰 Tools
🪛 LanguageTool
[style] ~128-~128: This phrase is redundant. Consider using “outside”.
Context: ...} Each input field can be referred to, outside of the blueprint metadata, using the `!inp...(OUTSIDE_OF)
162-166: Approve introduction to input section configuration
The heading succinctly signals that the full schema follows.
193-197: Approve example schema with input section
The added example clarifies how to structure inputs within a section.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
195-195: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
196-196: Multiple consecutive blank lines
Expected: 1; Actual: 3(MD012, no-multiple-blanks)
232-237: Approve built-in blueprint note enhancement
The added note underscores the separation of blueprint schema and domain schema, improving understanding.
There was a problem hiding this comment.
Pull Request Overview
Improves the blueprint schema documentation by clarifying metadata requirements, refining input and section explanations, and standardizing terminology and grammar.
- Clarified metadata fields to explicitly require
domainand refined descriptions. - Expanded guidance on input sections with version requirements and updated examples.
- Standardized terms (e.g.,
mapvsdictionary) and corrected punctuation and grammar.
| @@ -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). | |||
There was a problem hiding this comment.
[nitpick] Subject–verb agreement: change 'Blueprint schemas currently supports' to 'Blueprint schemas currently support'.
| Blueprint schemas currently supports three types of schema depending on its domain: [`automation`](/docs/automation/yaml/); `script`; and [`template`](/integrations/template/#using-blueprints). | |
| Blueprint schemas currently support three types of schema depending on its domain: [`automation`](/docs/automation/yaml/); `script`; and [`template`](/integrations/template/#using-blueprints). |
Copilot uses AI. Check for mistakes.
| 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. |
There was a problem hiding this comment.
[nitpick] Remove the comma after 'and' to read 'domain and optionally any input required from the user' for correct punctuation.
| 1. The blueprint's high-level metadata: name, domain and, optionally, any input required from the user. | |
| 1. The blueprint's high-level metadata: name, domain and optionally any input required from the user. |
Copilot uses AI. Check for mistakes.
| @@ -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. | |||
There was a problem hiding this comment.
[nitpick] For clarity, add 'that' after 'Note': 'Note that the blueprint schema...'.
| Note the *blueprint schema* under the blueprint key is followed by its domain schema. In this example, an automation schema. | |
| Note that the *blueprint schema* under the blueprint key is followed by its domain schema. In this example, an automation schema. |
Copilot uses AI. Check for mistakes.
Proposed change
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit