# Configuration Key Naming Conventions Profile: System Administrator This guide explains the naming conventions and formatting rules for configuration keys in Squirro. Following these conventions ensures consistency across the platform and prevents configuration errors. ## Key Format Rules Configuration keys follow a hierarchical dot-separated structure with specific character restrictions to maintain consistency and readability. ### Structure - **Hierarchy** `section.subsection.key-name` - **Multiple sections allowed** `section1.section2.section3.key-name` - **Separator** Dots `.` separate sections and the final key name. ### Character Rules **Section Names** - all parts except the final key: - Only lowercase letters (`a-z`). - No numbers, underscores, or special characters. - Used to group related configuration settings. **Key Names** - the final part - Lowercase letters (`a-z`) - Numbers (`0-9`) - Dashes (`-`) to separate multiple words - No underscores (`_`) or camelCase. The camelCase typographical convention capitalizes the first letter of each word after the first, like `myConfigValue` or `userName`. ## Examples ### Valid Keys These examples demonstrate proper configuration key formatting: ```text integrations.graphite.project frontend.userapp.chat-preferences topic.search.query-strategy genai.sqgpt.default-settings topic.search.field-boosts security.content-security-policy user.json-preferences ``` ### Invalid Keys These examples show common mistakes to avoid: ```text Frontend.userapp.settings # ❌ Uppercase in section name integrations.graphite_project # ❌ Underscore instead of dash integrations.graphite.projectSettings # ❌ camelCase in key name integrations.graph1te.project # ❌ Number in section name topic.search.query_strategy # ❌ Underscore in key name FRONTEND.userapp.settings # ❌ All uppercase section ``` ## Secret Configuration Keys Secret configuration keys follow the same naming rules as regular configuration keys. These keys store sensitive information like API passwords and tokens. ### Recommended Pattern For integration secrets, use this pattern: ```text integrations..password. ``` Examples: ```text integrations.graphite.password.my-graphite-instance integrations.openai.password.default-api-key integrations.external-service.password.production-env ``` ### Security Considerations - Always store passwords and sensitive data in separate secret configuration keys. - Never include sensitive information in non-secret configuration keys. - Use descriptive but not overly specific names for secret keys. - Follow the same character restrictions as regular keys. ## Best Practices ### Organizing Configuration Keys 1. **Group related settings** Use section names to logically group configuration options. 2. **Be descriptive** Key names should clearly indicate their purpose. 3. **Use consistent terminology** Maintain the same vocabulary across similar features. 4. **Avoid abbreviations** Use full words when possible for clarity. ### Common Section Names These are frequently used section names in Squirro configuration: - `frontend` User interface and web application settings. - `integrations` Third-party service integrations. - `topic` Project and content-related configurations. - `security` Security and authentication settings. - `genai` Configurations related to the GenAI service. - `user` User-specific preferences and settings. ## Validation The Squirro configuration system automatically validates key names according to these rules. Invalid key names will be rejected with an error message indicating a formatting issue. If you encounter configuration key validation errors, verify that: 1. All section names contain only lowercase letters. 2. Key names use only lowercase letters, numbers, and dashes. 3. No underscores or uppercase letters are present anywhere. 4. Dots are used only as section separators.