TOML Configuration Practices

This guide covers TOML-specific configuration design patterns and organizational decisions. For general guidance applicable to all languages, see the main practices guide. For cross-language formatting and visual presentation principles, see the code style guide. For shared workflow guidance, see the environment guide, validation guide, testing guide, and release guide.

Configuration Design

• Prefer table arrays with name fields over proliferating custom subtables. This approach scales better and reduces configuration complexity.

  ❌ Avoid - custom subtables:

  [database]
  host = 'localhost'
  
  [database.primary]
  port = 5432
  timeout = 30
  
  [database.replica] 
  port = 5433
  timeout = 15
  

  ✅ Prefer - table arrays with name field:

  [[database]]
  name = 'primary'
  host = 'localhost'
  port = 5432
  timeout = 30
  
  [[database]]
  name = 'replica'
  host = 'localhost' 
  port = 5433
  timeout = 15
  

• Apply nomenclature guidelines from the nomenclature guide to key and table names. Use Latin-derived words when they are the established norm in the domain.

Key Naming Conventions

• Use hyphens instead of underscores in key names for better ergonomics and visual clarity.

  ❌ Avoid:

  max_connections = 100
  retry_count = 3
  database_url = 'postgresql://localhost/db'
  

  ✅ Prefer:

  max-connections = 100
  retry-count = 3
  database-url = 'postgresql://localhost/db'
  

• Follow the project’s nomenclature patterns:

  • Use suffix patterns: timeout-default, connections-maximum

  • Use Latin-derived terms for consistency with the broader project

  • Group related keys with common prefixes: server-host, server-port, server-timeout

Formatting Standards

• Use single quotes for string values unless escapes are needed, in which case use double quotes.

  ✅ Prefer:

  name = 'example-service'
  pattern = 'user-.*'
  
  # Use double quotes when escapes are needed
  windows-path = "C:\\Program Files\\Example"
  

• Keep arrays and inline tables on single lines when they fit within reasonable length. For longer arrays, use multi-line format with trailing commas.

  ✅ Prefer:

  ports = [ 8080, 8443, 9090 ]
  server = { host = 'localhost', port = 8080, timeout = 30 }
  
  # Multi-line for longer arrays
  allowed-origins = [
      'https://example.com',
      'https://api.example.com',
  ]
  

Configuration Organization

• Group related configuration keys into logical sections with descriptive table names.

  ✅ Prefer:

  [server]
  host = 'localhost'
  port = 8080
  max-connections = 100
  timeout-default = 30
  
  [database]
  url = 'postgresql://localhost/mydb'
  connections-maximum = 10
  timeout-query = 15
  
  [logging]
  level = 'INFO'
  file-path = '/var/log/myapp.log'
  rotation-size = '10MB'
  

• Use consistent patterns across configuration files in the project.

• Document complex or non-obvious configuration choices with comments.