Skip to content

Clarify state attributes rules for entity #2437

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Clarify state attributes rules for entity #2437

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
89846dc
Clarify state attributes rules for entity
gjohansson-ST Nov 3, 2024
625358c
Some remarks
gjohansson-ST Nov 9, 2024
597eb89
Fix comment
gjohansson-ST Nov 9, 2024
88c0f52
Mods
gjohansson-ST Oct 24, 2025
e51f55a
Fix
gjohansson-ST Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docs/core/entity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,26 @@ The following properties are also available on entities. However, they are for a
| state_attributes | <code>dict &#124; None</code> | `None` | State attributes of a base domain. This property is implemented by the domain base entity and should not be implemented by integrations.
| unit_of_measurement | <code>str &#124; None</code> | The unit of measurement that the entity's state is expressed in. In most cases, for example for the `number` and `sensor` domains, this is implemented by the domain base entity and should not be implemented by integrations.

## State attributes

Entities can provide additional state attributes besides the built-in ones, to provide further details to its state.
This should be done by providing a dictionary with keys and values to the `extra_state_attributes` property.

Providing state attributes comes with the following rules:

- If an attribute is expected, it should be in the dictionary. Attributes should not "come and go". If it's not currently providing a value it should set it to `None`.
- If an attribute is not expected, it should not be in the dictionary. An attribute is expected if supported by the entity, for example as indicated by `supported_features`.
Copy link
Member

@joostlek joostlek Nov 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not really sure what this means and how it would look in practice

Copy link
Member Author

@gjohansson-ST gjohansson-ST Nov 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As an example, in statistics the buffer_usage_ratio attribute is only shown if the sensor is configured to handle a buffer size. Otherwise this attribute would be irrelevant hence not showing in that case.

Copy link
Member

@joostlek joostlek Nov 9, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But how can someone expect it to be there? We're quite bad with describing entities in the docs, let alone describing the state attributes

Copy link
Member

@MartinHjelmare MartinHjelmare Nov 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the developer docs not the user docs. The attribute is expected if it's part of a supported feature and that feature is supported or if it's an extra state attribute the attribute is expected if the device has support for that attribute.


Most often, the use of state attributes should be limited and in general it's often better to use another sensor than providing data as attributes.

Some general guidance to consider how to handle it:

- Would someone extract it using a template into an other (binary) sensor -> Not an attribute.
- It is essential to automation on? Can it be standalone as its own entity? -> Not an attribute.
- It is static, e.g., from configuration; doesn't belong in the state machine -> Not an attribute.
- Do we want to track long term statistics of the value? -> Not an attribute.
- Does is have historical value? If not, can be an attribute and exclude it from being recorded.

## System properties

The following properties are used and controlled by Home Assistant, and should not be overridden by integrations.
Expand Down