Configuration Values Displaying Technical Names
Issue Description
When the schema has been upgraded to a newer version, but the configuration interface or the config CLI deployed are still at the old version, newly introduced configuration values will have technical names such as cfg.server.mail.notification.delay instead of pretty names and descriptions.
This occurs because the configuration interface and config CLI rely on metadata that describes configuration properties. When the schema is upgraded to a newer version that introduces new configuration properties, older versions of the configuration interface or config CLI do not have the metadata for these new properties. As a result, they fall back to displaying the technical property names instead of user-friendly labels and descriptions.
Symptoms
- Configuration properties appear with technical names like
cfg.server.mail.notification.delayinstead of descriptive names - Missing descriptions or help text for newly introduced configuration options
- Configuration interface or CLI commands may not display proper labels for new settings
Solution
Once the schema has been upgraded to a newer version, the corresponding version of the config CLI and the configuration interface should be used. This ensures that:
- Metadata Alignment: The configuration interface and CLI have the proper metadata (labels, descriptions, validation rules) for all configuration properties in the upgraded schema
- User Experience: Users see friendly, descriptive names and helpful descriptions instead of technical property paths
- Functionality: All new configuration options are properly accessible and configurable through the interface
Best Practices
- Always upgrade the configuration interface and config CLI to match the schema version
- Verify that configuration properties display correctly after an upgrade
- Keep all components (schema, CLI, and interface) at compatible versions
- Test configuration changes in a non-production environment first