Standard for describing devices and entities provided by an integration

[ScottG489]

Context

We currently lack a standard for describing what entities (and their attributes) are provided by an integration and what data/types they provide. This would give the user a better idea of what to expect from the integration after it's set up.

For comparison, we already have a standard way to describe services (example) or for YAML configuration (example). I think it would be valuable to establish something similar for entities/devices provided by integrations.

Proposal

Some information that could be included for entities:

• Entity domain/platform (e.g. sensor, button, etc)
• Data type and/or unit of the value
• Attributes and their type (string, number, etc)

Or for integration devices/services:

• If it provides model and/or manufacturer information
• If it provides version or firmware information
• If it provides a "Visit" link

In terms of look, something similar to the table we have for services or the hierarchy we have for YAML config could work well. We just would want to make sure to differentiate the look enough from those so it isn't confused.

Consequences

For some integrations, this documentation could get very verbose. For example, the ESPHome integration can provide entities for just about every platform and the types are quite dynamic. While there are cases like this where the entities provided are too dynamic, the majority of integrations provide a more static offering of entities and would benefit from having a way to describe their offerings.

To this end, the standard would benefit from allowing doc writers to be as specific or vague as applicable depending on how dynamic the offerings are. This way, if the offerings are too dynamic, they wouldn't be completely prevented from adding what information they can. Using ESPHome again as an example, it could still at least document a list of all domains it provides.