Add entity name as comment after numeric ID in YAML configuration

Problem Description

Since Home Assistant version 2025.6, YAML configuration files have moved away from using human-readable entity IDs in favor of numeric references. While this change may have technical benefits, it has significantly impacted the maintainability and readability of YAML configuration files for users who manually edit and maintain their configurations.

Current Issues:

• YAML configuration files are no longer human-readable when they contain numeric entity references
• Troubleshooting automations and scripts becomes much more difficult without recognizable entity names
• Code review and collaboration on configurations is severely hampered
• New users and experienced users alike struggle to understand what entities are being referenced
• Manual documentation of configurations requires significant additional effort
• Version control diffs become meaningless when only numeric IDs are shown

Impact on User Experience:

• Increased time spent identifying entities during configuration maintenance
• Higher barrier to entry for users learning YAML configuration
• Reduced ability to quickly spot errors or understand automation logic
• Loss of self-documenting code benefits that readable entity IDs provided

Proposed Solution

Automatically append human-readable entity name comments immediately after numeric entity references in YAML configuration files.

Implementation Details:

1. Automatic Comment Generation: When Home Assistant writes or updates YAML files containing numeric entity references, automatically append a comment with the entity’s friendly name and/or entity ID.
2. Comment Format: Use a standardized, consistent format that doesn’t interfere with YAML parsing but provides maximum readability.
3. Dynamic Updates: Comments should be automatically updated when entity names change, ensuring they remain accurate.
4. Optional Feature: Provide a configuration option to enable/disable this feature for users who prefer minimal YAML files.

Benefits:

• Maintains backward compatibility while improving readability
• Requires no user intervention - works automatically
• Preserves the technical benefits of numeric references
• Significantly improves code maintainability and debugging
• Reduces learning curve for YAML configuration
• Enables better collaboration and version control practices

Configuration Option:

yaml
add the description of the device (home-assistant-voice-098dfb) after the ID.

  actions:
  - action: media_player.play_media
    target:
      device_id:
      - 3d746d8c5086e6a6fe734c7bfb530867 #home-assistant-voice-098dfb```

This feature would bridge the gap between technical efficiency and human usability, making Home Assistant configurations both robust and maintainable.

1 post - 1 participant

Read full topic