Configuration Key Naming Conventions

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:

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:

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.

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.


Contents