Settle relative import destination syntax
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user