3.7 KiB
ADR 0012: Place Imported Configuration at Relative Destinations
Status
Accepted and implemented. The
configuration contract owns current behavior.
The completed roadmap and review records are preserved at e4270c9 under
docs/roadmap/ in Git history; the relative-import implementation plan remains
at d9f08ff:docs/roadmap/implementation.md.
Date
2026-10-14
Context
ConfigKit can place an input document at a literal mapping path while retaining source identity, composition, and inspection in its normal loading lifecycle. An importing document can currently bring in other documents, but those contributions inherit only the importing input's destination. Consumers that assemble a collection therefore cannot declare the layout of imported fragments alongside the import itself without rewriting source documents or performing another merge outside ConfigKit.
The extension should reuse input placement and the existing import lifecycle. Logical application placement must remain independent from physical path resolution, source identity, precedence, and resource ownership.
Decision
Add an optional destination field to each YAML import declaration. Its value
is a sequence of strings representing literal mapping-key segments. Omission
and an empty sequence add no segments. A non-empty destination appends to the
effective destination of the immediately importing document; nested imports
continue from the resulting child destination. Every match of one glob
declaration receives the same computed destination.
Use the existing input-destination validation and reserved-key rules. Do not interpret destination segments as filesystem paths, separators, sequence indices, or root-reset instructions. Physical import paths continue to resolve from their declaring source under existing containment rules.
Imports remain in their existing strict-composition group. A destination does not grant precedence, bypass cycle or repeated-source rules, or change source identity. Existing placement, version ownership, source records, diagnostics, resource contexts, inheritance, history, and inspection mechanisms continue to govern the placed contributions. No public Go entry point or independent specification-header behavior is introduced.
This is additive YAML functionality and is minor-release work. Version selection, release notes, roadmap retirement, and publication remain separate release-preparation work.
Alternatives Considered
- Require complete application-root destinations on every import. This avoids inherited context but repeats collection prefixes in nested source declarations and does not express placement relative to the importing document.
- Encode destinations as dotted or slash-delimited strings. This introduces separator and escaping rules even though existing paths already represent literal mapping keys as segments.
- Rewrite or merge imported documents in consumers. This duplicates source placement, strict composition, attribution, and inspection behavior outside ConfigKit's loading lifecycle.
- Add independent specification headers or collection-specific validation. These are separate design questions and are not required to declare relative placement.
Consequences
Import declarations can describe the logical placement of their contributions while preserving the physical source and existing composition lifecycle. Placement is immediate-parent-relative, so nested imports accumulate their declared segments and sibling declarations remain independent. The feature is implemented behind the existing public loading surface; detailed validation, diagnostic, accounting, and inspection requirements are tracked by the implementation roadmap.