Context
Configuration is an input to software systems, but configuration errors are often discovered only after execution has already begun. This can lead to confusing failures, partial execution, difficult-to-diagnose behavior, or invalid system state.
For systems where configuration controls execution behavior, configuration should therefore be treated as an input that requires explicit validation rather than something that can be assumed to be correct.
Problem
If invalid configuration is allowed to reach the execution layer, the resulting failure may occur far away from the original mistake.
This makes errors harder to understand, increases debugging effort, and can allow invalid states to propagate through the system.
We need a clear boundary between accepting configuration and executing with that configuration.
Decision
Configuration will be validated before execution begins.
Validation should happen as early as practical and should produce explicit, actionable errors when configuration is invalid.
The execution layer should be able to assume that the configuration it receives has already passed the relevant validation checks.
This establishes validation as a boundary between external configuration input and execution rather than treating validation as an incidental responsibility of downstream components.
Alternatives Considered
Validate During Execution
Rejected.
Configuration errors can surface too late and may produce failures that are harder to associate with the original input.
Rely on Downstream Errors
Rejected.
Low-level failures often lack the context necessary for a user or developer to understand which configuration value caused the problem.
Validate Only Basic Syntax
Rejected.
Syntactically valid configuration can still represent an invalid, unsupported, or contradictory state.
Validation therefore needs to consider the semantics and constraints of the system, not only whether the input can be parsed.
Consequences
Positive
Invalid configuration is detected earlier.
Errors can be reported closer to their source.
Execution code can operate with stronger assumptions.
Tests can explicitly cover invalid configuration states.
Configuration behavior becomes easier to document and reason about.
Failures become easier to reproduce and diagnose.
The boundary between configuration handling and execution becomes explicit.
Trade-offs
Validation introduces additional implementation and maintenance work.
Validation rules must remain consistent with the behavior they protect.
Some validation may require domain knowledge that cannot be captured by syntax or schema alone.
More comprehensive validation can require additional testing and documentation.
Evidence & Related Work
This decision is reflected in configuration and validation work contributed to ESA Pyxel. The work below provides concrete evidence of applying this principle in practice.
Implementation Evidence
Pyxel Config Lab
A configuration-focused tool for working with Pyxel configuration and making configuration behavior easier to inspect and understand.
ESA Pyxel — Merge Request !1141
Implemented the check_validity function and associated tests as part of the Pyxel configuration-validation work.
https://gitlab.com/esa/pyxel/-/merge_requests/1141
Tests
Test coverage demonstrating the validation behavior implemented in Pyxel Config Lab.
Live Demo
A working demonstration of Pyxel Config Lab.
Publication & Release Evidence
ESA Pyxel 2.14 Release
Pyxel Config Lab was included in the wider Pyxel 2.14 release work and made available as an online GUI tool.
Related Article
A related technical article documenting the work and its underlying engineering considerations.
Relationship to the Broader Engineering Approach
This ADR is part of a broader engineering principle:
Invalid states should be made difficult or impossible to reach the execution layer.
Configuration validation is one application of that principle.
The same approach can be applied to API inputs, workflow state, AI-agent actions, deployment configuration, data pipelines, and other systems where invalid inputs can otherwise propagate into expensive or difficult-to-diagnose failures.
Decision Outcome
The validation boundary is considered an intentional architectural boundary.
Future configuration-related work should preserve this principle where practical:
Input → Validation → Validated Configuration → Execution
rather than:
Input → Execution → Failure
This ADR should be revisited if future requirements make this boundary impractical or if validation responsibilities need to be distributed across multiple system layers.