diff --git a/docs/roadmap/relative-import-destinations.md b/docs/roadmap/relative-import-destinations.md index 41f0b33..93281ed 100644 --- a/docs/roadmap/relative-import-destinations.md +++ b/docs/roadmap/relative-import-destinations.md @@ -14,7 +14,7 @@ effective destination, then processes the imported application content through the existing placement and loading lifecycle. Applications continue to select entry sources, input destinations, filesystem contexts, and precedence tiers. -Proposed syntax, pending the syntax decision below: +Selected YAML syntax: ```yaml configkit: @@ -43,6 +43,9 @@ The feature must preserve these requested and existing behaviors: - Omission and an empty destination list retain the importing document's destination. Each glob match receives the same relative placement. Transitive imports accumulate destinations from their immediate parents. +- An explicit `destination` is a sequence of strings. Null, scalar values, and + non-string members are invalid directive shapes; values are not coerced. + For a numeric-looking key, use a string such as `destination: ["0"]`. - Segments are mapping keys under the existing `Input.Destination` rules. Dots, slashes, and numeric-looking text within a key are literal. There is no filesystem-style normalization, parent traversal, or application-root reset. @@ -113,10 +116,11 @@ placement and assembly rather than introduce a second merge or validation model. ## Ordered implementation plan -### 1. Select syntax and document the semantic extension +### 1. Document the selected syntax and semantic extension -Resolve the Open Decision below and specify valid shapes, literal key handling, -and structured failures. Preserve existing `path`/`glob` and `optional` behavior. +Use the Selected Design Decision below to specify valid shapes, literal key +handling, and structured failures. Preserve existing `path`/`glob` and `optional` +behavior. Validate declared destination syntax even when an optional import has no match; optionality suppresses missing input, not malformed directives. @@ -209,23 +213,17 @@ passes, and implemented documentation matches the behavior. Source specification headers can then be reconsidered as a separate feature; their implementation is not required to complete this roadmap. -## Open Decisions +## Selected Design Decision ### YAML destination representation -Recommendation: adopt `destination` as a sequence of strings, for example -`destination: [prompts, "0"]`. Omission and `[]` inherit placement. Treat null, -scalar destinations, and non-string members as invalid shapes rather than -coercing them. Permit every string key allowed by existing destination rules, -including the empty string. This directly expresses literal segments, matches -the request's example, and keeps numeric key text distinct from YAML numbers. -These shape choices are proposed syntax, not pre-existing restrictions. +Use `destination` as a sequence of strings, for example +`destination: [prompts, "0"]`. Omission and `[]` inherit placement. Null, scalar +destinations, and non-string members are invalid shapes rather than values to +coerce. Every string key allowed by existing destination rules remains valid, +including the empty string. -Alternative: also accept a scalar JSON-pointer representation using existing -`ParsePath` conventions, while retaining the sequence form. This is viable and -may be convenient for users already familiar with public paths, but introduces -two spellings and escaping rules for one operation. A leading slash would still -describe relative segments, not reset to the application root, which could be -surprising. Prefer the sequence-only form unless consumer evidence justifies -the additional notation. A null-as-inherit shorthand is also viable but adds a -third spelling for behavior already covered by omission and an empty list. +This representation directly expresses literal segments and keeps numeric key +text distinct from YAML numbers. It provides one explicit notation consistent +with the existing mapping-destination model. These shape rules define the new +directive syntax; other configuration values retain their existing semantics.