Skip to content

Add generated integration domain registry - #5512

Draft
thomasgregg wants to merge 1 commit into
hacs:mainfrom
thomasgregg:codex/add-integration-domain-registry
Draft

Add generated integration domain registry#5512
thomasgregg wants to merge 1 commit into
hacs:mainfrom
thomasgregg:codex/add-integration-domain-registry

Conversation

@thomasgregg

@thomasgregg thomasgregg commented Aug 29, 2026

Copy link
Copy Markdown

Summary

  • publish a compact, sorted, and deduplicated list of default HACS integration domains as integration/domains.json
  • validate the registry during both generation and publication
  • purge the Cloudflare cache for the registry after publication
  • cover generation and duplicate removal in the existing data-generator tests

Motivation

Home Assistant Analytics currently filters public custom-integration statistics through the legacy home-assistant/brands domain list. Custom integrations can now ship branding locally, so newer integrations are no longer guaranteed to enter that list. This leaves valid integrations absent from the public Analytics dataset.

The Analytics discussion suggested using presence in HACS as the trust boundary instead of removing the guardrail entirely:

HACS already publishes the required domain information in integration/data.json. This change exposes the same validated data through a small, purpose-specific endpoint:

["domain_a","domain_b"]

This does not add analytics or tracking to HACS and does not change HACS runtime or UI behavior. It only publishes a stable registry derived from the existing default integration dataset. Home Assistant Analytics can consume this endpoint in a separate change and union it with the legacy Brands list.

Why a dedicated endpoint?

Analytics could technically parse the existing integration/data.json, but that file is repository metadata rather than a purpose-specific domain-registry contract. It is currently about 2.1 MB, while the derived domain list is approximately 47 KB.

Publishing domains.json keeps downstream consumers independent of the internal repository-data structure and gives HACS explicit control over the definition of a trusted default integration. The file is generated from the same validated data, so it introduces no additional source of truth or maintenance burden.

The intended Analytics behavior is:

trusted custom domains = legacy Brands domains + default HACS integration domains

Unknown custom domains would remain excluded. This restores visibility for reviewed HACS integrations without removing the existing publication guardrail.

Future possibilities

A stable domain registry would allow ecosystem tools to associate reviewed HACS integrations with other public, domain-indexed datasets without depending on HACS's full repository-metadata format.

If Home Assistant Analytics adopts this registry, downstream tools could combine release activity with anonymized, opt-in installation reporting, store historical snapshots, and show weekly or monthly adoption trends. The registry itself would contain no usage data and would not change HACS's privacy model.

Validation

  • python -m pytest tests/scripts/data/test_generate_category_data.py --no-cov -q — 24 passed
  • ruff check scripts/data/generate_category_data.py tests/scripts/data/test_generate_category_data.py
  • ruff format --check scripts/data/generate_category_data.py
  • workflow YAML parse and JSON contract checks

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant