1.5 KiB
ADR 0002: Own YAML Semantics Behind a Private Parser Boundary
Status
Accepted. This records a design decision, not implementation completion.
Date
2026-09-06
Context
A shared library cannot provide consistent configuration semantics if each consumer inherits parser conversions, node types, and extension behavior. Exposing parser types also makes dependency changes part of the public API.
Decision
ConfigKit defines its supported YAML policy and keeps parser integration private. Application types and diagnostics must not require parser-specific public types. Use a small internal boundary rather than a general parser/provider framework. The architecture policy owns this constraint; the current YAML document and scalar contracts own the implemented syntax.
Alternatives considered
- Expose parser nodes and hooks: easy integration but couples consumers to parser behavior and permits bypassing library policy.
- Adopt the parser's entire YAML behavior: reduces initial code but leaves core semantics outside ConfigKit's control.
- Abstract many configuration languages immediately: adds unsupported scope.
Consequences
Parser changes require behavior-level compatibility verification. ConfigKit must translate errors safely and enforce its own supported subset. Some existing consumer custom decoders will need replacement with library-supported mechanisms or application resolution. No particular parser dependency is selected here.