home assistant integration knowledge

File Locations

General guidelines

When looking for examples, prefer integrations with the platinum or gold quality scale level first.
Polling intervals are NOT user-configurable. Never add scan_interval, update_interval, or polling frequency options to config flows or config entries.
Do NOT allow users to set config entry names in config flows. Names are automatically generated or can be customized later in UI. Exception: helper integrations may allow custom names.
For entity actions and entity services, avoid requesting redundant defensive checks for fields already enforced by Home Assistant validation schemas and entity filters; only request extra guards when values bypass validation or are transformed unsafely.
When validation guarantees a key is present, prefer direct dictionary indexing (data["key"] ) over .get("key") so invalid assumptions fail fast.

The following platforms have extra guidelines:

Integration Quality Scale

When validating the quality scale rules, check them at https://developers.home-assistant.io/docs/core/integration-quality-scale/rules
When implementing or reviewing an integration, always consider the quality scale rules, since they promote best practices.

Template scale file: ./script/scaffold/templates/integration/integration/quality_scale.yaml

How Rules Apply

Check manifest.json : Look for "quality_scale" key to determine integration level
Bronze Rules: Always required for any integration with quality scale
Higher Tier Rules: Only apply if integration targets that tier or higher
Rule Status: Check quality_scale.yaml in integration folder for:
done : Rule implemented
exempt : Rule doesn't apply (with reason in comment)
todo : Rule needs implementation

Testing Requirements

Source Transparency