79 lines
3.7 KiB
Markdown
79 lines
3.7 KiB
Markdown
# ADR 0012: Place Imported Configuration at Relative Destinations
|
|
|
|
## Status
|
|
|
|
Accepted and implemented. The
|
|
[configuration contract](../config.md#input-destinations) 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.
|