> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Quality Scale

> Understanding and achieving quality standards for Home Assistant integrations

The Integration Quality Scale is Home Assistant's framework for measuring and ensuring the quality of integrations. It provides clear standards and guidelines that help maintainers build reliable, user-friendly integrations.

## Overview

The quality scale consists of four tiers, each building upon the previous one:

* **Bronze**: Essential functionality and basic best practices
* **Silver**: Enhanced reliability and maintainability
* **Gold**: Production-ready with excellent user experience
* **Platinum**: Exceptional quality with advanced features

Integrations declare their quality scale level in `manifest.json`:

```json theme={null}
{
  "domain": "example",
  "name": "Example Integration",
  "quality_scale": "gold"
}
```

## Quality Scale Tiers

### Bronze Tier

The bronze tier establishes fundamental requirements for all integrations:

#### Key Requirements

* **Config Flow**: User-friendly configuration through the UI
* **Unique Config Entry**: Prevent duplicate configurations
* **Entity Unique ID**: All entities must have stable unique IDs
* **Runtime Data**: Use modern `entry.runtime_data` pattern
* **Test Before Setup**: Validate connectivity before completing setup
* **Has Entity Name**: Entities must have proper names
* **Documentation**: High-level description, installation, and removal instructions

#### Example: Runtime Data Pattern

```python theme={null}
from homeassistant.config_entries import ConfigEntry
from homeassistant.core import HomeAssistant

from .coordinator import MyCoordinator

type MyConfigEntry = ConfigEntry[MyCoordinator]

async def async_setup_entry(hass: HomeAssistant, entry: MyConfigEntry) -> bool:
    """Set up from a config entry."""
    coordinator = MyCoordinator(hass, entry)
    await coordinator.async_config_entry_first_refresh()
    
    # Store coordinator in runtime_data
    entry.runtime_data = coordinator
    
    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
    return True
```

### Silver Tier

Silver tier adds reliability and proper error handling:

#### Key Requirements

* **Config Entry Unloading**: Clean shutdown and resource cleanup
* **Reauthentication Flow**: Handle expired credentials gracefully
* **Entity Unavailable**: Mark entities unavailable when device is offline
* **Parallel Updates**: Protect against concurrent state updates
* **Test Coverage**: Minimum 90% code coverage
* **Integration Owner**: Designated code owner for maintenance

#### Example: Config Entry Unloading

```python theme={null}
async def async_unload_entry(hass: HomeAssistant, entry: MyConfigEntry) -> bool:
    """Unload a config entry."""
    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
```

#### Example: Parallel Updates Protection

```python theme={null}
from homeassistant.helpers.entity import Entity

class MyEntity(Entity):
    """Example entity with parallel updates protection."""
    
    # Limit concurrent updates to prevent race conditions
    _attr_parallel_updates = 1
```

### Gold Tier

Gold tier represents production-ready integrations with excellent UX:

#### Key Requirements

* **Devices**: Proper device registry integration
* **Diagnostics**: Debug information download
* **Discovery**: Automatic device discovery support
* **Entity Translations**: Translated entity states
* **Exception Translations**: User-friendly error messages
* **Reconfiguration Flow**: Allow changing settings without removing integration
* **Repair Issues**: Proactive issue detection and resolution
* **Comprehensive Documentation**: Examples, use cases, troubleshooting

#### Example: Diagnostics

```python theme={null}
from homeassistant.config_entries import ConfigEntry
from homeassistant.core import HomeAssistant

from .const import DOMAIN

async def async_get_config_entry_diagnostics(
    hass: HomeAssistant, entry: ConfigEntry
) -> dict:
    """Return diagnostics for a config entry."""
    coordinator = hass.data[DOMAIN][entry.entry_id]
    
    return {
        "entry": {
            "title": entry.title,
            "version": entry.version,
        },
        "data": coordinator.data,
        "device_info": coordinator.device.info,
    }
```

### Platinum Tier

Platinum tier represents the highest quality standards:

#### Key Requirements

* **Async Dependency**: Library must be fully asynchronous
* **Inject Websession**: Reuse Home Assistant's aiohttp session
* **Strict Typing**: Complete type hints with mypy validation

#### Example: Injecting Web Session

```python theme={null}
from homeassistant.helpers.aiohttp_client import async_get_clientsession

async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Set up from a config entry."""
    # Reuse Home Assistant's aiohttp session
    session = async_get_clientsession(hass)
    client = MyAPIClient(session)
    
    coordinator = MyCoordinator(hass, client)
    await coordinator.async_config_entry_first_refresh()
    
    entry.runtime_data = coordinator
    return True
```

## Quality Scale Files

Integrations track their progress using `quality_scale.yaml` files:

```yaml theme={null}
rules:
  # Bronze
  config-flow: done
  unique-config-entry: done
  runtime-data: done
  test-before-setup: done
  
  # Silver
  config-entry-unloading: done
  reauthentication-flow: done
  test-coverage: done
  
  # Gold
  diagnostics: done
  discovery:
    status: exempt
    comment: |
      This integration does not support automatic discovery
      as devices must be manually configured with API keys.
```

## Special Scales

### Internal Scale

Integrations marked as `internal` are core Home Assistant components:

```json theme={null}
{
  "domain": "zone",
  "quality_scale": "internal"
}
```

Internal integrations don't require quality scale validation.

### Legacy Scale

Integrations marked as `legacy` are maintained but don't meet modern standards:

```json theme={null}
{
  "domain": "example_legacy",
  "quality_scale": "legacy"
}
```

Legacy integrations are discouraged for new development.

## Validation

The quality scale is enforced by the `hassfest` tool:

```bash theme={null}
python3 -m script.hassfest --action validate
```

This validates:

* Declared quality scale matches implemented rules
* All required rules for the tier are completed
* Documentation matches requirements
* Test coverage meets minimums

## Best Practices

### Start with Bronze

New integrations should target bronze tier first:

1. Implement config flow
2. Add unique IDs to entities
3. Use runtime\_data pattern
4. Write basic documentation
5. Add test-before-setup validation

### Progress Gradually

Move up tiers systematically:

1. Complete all rules in current tier
2. Update `quality_scale.yaml`
3. Run validation: `python3 -m script.hassfest`
4. Update manifest.json when tier is complete

### Exemptions

Some rules can be exempted with justification:

```yaml theme={null}
rules:
  discovery:
    status: exempt
    comment: |
      Clear explanation of why this rule doesn't apply
      to this specific integration.
```

## Resources

* [Quality Scale Rules Documentation](https://developers.home-assistant.io/docs/core/integration-quality-scale/rules/)
* [Integration Manifest Schema](/home/daytona/workspace/source/script/json_schemas/manifest_schema.json)
* [Quality Scale Validation Code](/home/daytona/workspace/source/script/hassfest/quality_scale.py)

## Common Pitfalls

### Not Using Runtime Data

❌ **Wrong**: Storing data in `hass.data`

```python theme={null}
hass.data.setdefault(DOMAIN, {})
hass.data[DOMAIN][entry.entry_id] = coordinator
```

✅ **Correct**: Using `entry.runtime_data`

```python theme={null}
entry.runtime_data = coordinator
```

### Missing Parallel Updates

❌ **Wrong**: No protection against concurrent updates

```python theme={null}
class MyEntity(Entity):
    async def async_turn_on(self):
        await self.device.turn_on()
```

✅ **Correct**: Limited parallel updates

```python theme={null}
class MyEntity(Entity):
    _attr_parallel_updates = 1
    
    async def async_turn_on(self):
        await self.device.turn_on()
```

### Incomplete Unloading

❌ **Wrong**: Not unloading platforms

```python theme={null}
async def async_unload_entry(hass, entry):
    return True
```

✅ **Correct**: Proper cleanup

```python theme={null}
async def async_unload_entry(hass, entry):
    return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
```

By following the quality scale framework, you ensure your integration meets Home Assistant's standards for reliability, maintainability, and user experience.