Skip to content

SonataConfig rework: dict configs -> proper config objects #452

@cattabiani

Description

@cattabiani

Context

Stemming from #429.

SonataConfig currently loads Sonata configuration entities (e.g. ConnectionOverride, Conditions, …) and converts them into plain dicts. These dicts are then mutated throughout the codebase:

  • keys are added for local or transient state
  • keys are removed to encode semantic meaning (e.g. “invalid”, “disabled”)
  • values are overridden via CLI

This pattern is widespread.


Problem

Using dicts as configuration objects causes structural issues:

  • No schema enforcement: keys can be added, removed, or misspelled silently
  • Configuration and runtime state are mixed
  • Semantics are implicit (presence/absence of keys)
  • Hard to reason about when a configuration is complete or valid
  • CLI overrides can introduce inconsistent states

Configuration is treated as a mutable bag of data rather than a domain object.


Scope of this epic

This epic is intentionally limited in scope.

Goal:
Replace dict-based internal configuration handling with explicit, typed configuration objects so that:

  • configuration structure is explicit
  • keys cannot be arbitrarily added or removed
  • semantics are expressed via fields, not conventions

Immutability, freezing, and lifecycle enforcement are explicitly out of scope and may be addressed later.


Proposal

  1. Introduce proper internal config objects
    For each Sonata configuration concept currently represented as a dict, introduce a corresponding internal config object (if mutability is needed otherwise rely on the original sonata config object) with explicit, typed fields. Dicts are no longer used as the primary internal representation.

  2. One-way conversion from SonataConfig
    SonataConfig remains the external, immutable source of truth. At load time, Sonata objects are converted once into internal config objects. Internal code never mutates raw dicts.

  3. Controlled mutation during setup
    Internal config objects may be mutated during setup (CLI overrides, defaults, normalization), but only via explicit attribute access. Adding or removing keys is no longer possible.

  4. Separation of concerns
    Configuration objects represent configuration only. Runtime or execution state must not be encoded by mutating config objects.


Non-goals

Out of scope for this epic:

  • enforcing immutability or freeze semantics
  • deep validation or invariant checking
  • multiple config layers (parsed vs resolved)
  • runtime enforcement of mutation phases

Why this matters

Even without immutability, this change:

  • removes an entire class of bugs (dynamic keys)
  • makes configuration structure explicit and reviewable
  • improves readability and maintainability
  • enables future improvements without rework

This is a necessary first step.


Acceptance criteria

  • No internal code path relies on mutating configuration dicts
  • All Sonata-derived configuration is represented by explicit config objects
  • No configuration semantics are encoded via key presence/absence
  • CLI overrides operate on config object fields, not dict keys

Sub-issues

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions