Settle relative import destination syntax

This commit is contained in:
2026-10-14 16:44:11 +00:00
parent edb6d05ec1
commit b2db3233b2

View File

@@ -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.