Record collection schema roots and native composition
This commit is contained in:
@@ -1,7 +1,7 @@
|
|||||||
# Prompt-Owned Inline And Source-Relative Schemas
|
# Prompt-Owned Inline And Source-Relative Schemas
|
||||||
|
|
||||||
Status: proposed target and implementation roadmap. The decisions at the end
|
Status: proposed target and implementation roadmap. Decision 1 is accepted;
|
||||||
remain open; examples use recommended field names, not implemented syntax.
|
Decisions 2 and 3 remain open. Examples describe target, not implemented, syntax.
|
||||||
This document authorizes no code changes and selects no release number.
|
This document authorizes no code changes and selects no release number.
|
||||||
|
|
||||||
## Purpose And Boundary
|
## Purpose And Boundary
|
||||||
@@ -32,7 +32,8 @@ boundaries:
|
|||||||
[Configuration capture](../../internal/configuration/prompts.go) copies that
|
[Configuration capture](../../internal/configuration/prompts.go) copies that
|
||||||
string into the domain contract; no inline or source-relative schema selection
|
string into the domain contract; no inline or source-relative schema selection
|
||||||
is captured.
|
is captured.
|
||||||
- Schema source options configure a root used by the engine's validator. The
|
- Schema source options configure a root used by the engine's validator, with
|
||||||
|
an implicit default directory of `"."`. The
|
||||||
[schema format contract](../formats.md#schemas) defines existing path meaning,
|
[schema format contract](../formats.md#schemas) defines existing path meaning,
|
||||||
dialect, self-contained resources, and operational-error behavior.
|
dialect, self-contained resources, and operational-error behavior.
|
||||||
- [Message files](../formats.md#messages-and-templates) already resolve using the
|
- [Message files](../formats.md#messages-and-templates) already resolve using the
|
||||||
@@ -53,18 +54,18 @@ or application-managed overlay system.
|
|||||||
|
|
||||||
### Schema Forms
|
### Schema Forms
|
||||||
|
|
||||||
The recommended configuration forms are:
|
The accepted configuration forms are:
|
||||||
|
|
||||||
| Field | Meaning |
|
| Field | Meaning |
|
||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `schema` | An inline schema value in the prompt's output definition. |
|
| `schema` | An inline schema value in the prompt's output definition. |
|
||||||
| `schema_file` | A schema file resolved using that effective field's source context. |
|
| `schema_file` | A schema file resolved using that effective field's source context. |
|
||||||
| `schema_path` | The existing reference in the explicitly configured schema root. |
|
| `schema_path` | A reference within the applicable explicitly configured schema root. |
|
||||||
|
|
||||||
Inline and source-relative forms are the new capability. The explicit-root route
|
Inline and source-relative forms are the new capability. The explicit-root route
|
||||||
remains available for existing consumers and programmatic contracts. Decisions
|
remains available, with optional collection-specific roots and an application-wide
|
||||||
1–3 below settle selection and API details; no multi-root fallback search or
|
default. Decisions 2 and 3 below settle selection and API details. There is no
|
||||||
implicit working-directory interpretation is proposed.
|
multi-root fallback search or implicit working-directory root.
|
||||||
|
|
||||||
Illustrative inline output fragment:
|
Illustrative inline output fragment:
|
||||||
|
|
||||||
@@ -85,6 +86,56 @@ JSON document expresses that schema. Equivalence means equivalent schema values,
|
|||||||
validation, and submitted constraints, not identical YAML/JSON source bytes or
|
validation, and submitted constraints, not identical YAML/JSON source bytes or
|
||||||
an assurance that every provider supports every locally valid schema.
|
an assurance that every provider supports every locally valid schema.
|
||||||
|
|
||||||
|
### Optional Schema Roots
|
||||||
|
|
||||||
|
Accept an optional `schema_root` at the configuration root and within each
|
||||||
|
`collections` entry. A collection can manage schemas centrally without requiring
|
||||||
|
other collections to adopt that layout. Inline and source-relative forms remain
|
||||||
|
available whether or not a root is configured.
|
||||||
|
|
||||||
|
Illustrative configuration:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
schema_root: ./application-schemas
|
||||||
|
collections:
|
||||||
|
weatherreporter:
|
||||||
|
schema_root: ./schemas
|
||||||
|
prompts:
|
||||||
|
- id: summarize.alerts
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: Summarize the supplied alerts.
|
||||||
|
output:
|
||||||
|
format: json
|
||||||
|
validation_mode: json_schema
|
||||||
|
schema_path: alerts.schema.json
|
||||||
|
```
|
||||||
|
|
||||||
|
ConfigKit owns composition, layering, inheritance, and effective source context
|
||||||
|
for these fields, just as for other configuration. PromptKit consumes the final
|
||||||
|
values without another override or merge pass. Resolve each declared root against
|
||||||
|
the defining field's effective filesystem and base directory; an overridden root
|
||||||
|
uses the overriding source's context. This supports embedded and host filesystems
|
||||||
|
without assuming that a root is a host path.
|
||||||
|
|
||||||
|
After composition, use the selected prompt's collection root when present;
|
||||||
|
otherwise use the application-wide root. Root-level prompts use the application
|
||||||
|
root. This is a scope-selection rule, not an exception to ConfigKit composition.
|
||||||
|
Select one root before opening the schema: a missing file under that root is an
|
||||||
|
error, not a reason to search another root or the prompt's directory.
|
||||||
|
|
||||||
|
No root is needed for `schema` or `schema_file`. Selecting `schema_path` without
|
||||||
|
an applicable root is a configuration problem. Remove the implicit `"."` root
|
||||||
|
as an intentional breaking change; callers relying on it must explicitly select
|
||||||
|
a root or migrate their schema selection.
|
||||||
|
|
||||||
|
Retain the ability to supply explicit schema directories and filesystems through
|
||||||
|
Go configuration helpers, but fit those helpers into ConfigKit's normal source
|
||||||
|
composition. Do not give Go options a special precedence rule or retain a second
|
||||||
|
runtime override pass. API planning must spell out the helper adaptation and any
|
||||||
|
migration required; unchanged legacy option behavior is not a requirement where
|
||||||
|
it conflicts with this decision.
|
||||||
|
|
||||||
### Effective Source Context And Composition
|
### Effective Source Context And Composition
|
||||||
|
|
||||||
Resolve `schema_file` using the effective field's defining filesystem and base
|
Resolve `schema_file` using the effective field's defining filesystem and base
|
||||||
@@ -180,11 +231,13 @@ and new provider-specific dialects are outside this work.
|
|||||||
2. **Capture schema ownership.** Extend configuration decoding, normalization,
|
2. **Capture schema ownership.** Extend configuration decoding, normalization,
|
||||||
domain selection, and inspection. Share the existing effective-field resource
|
domain selection, and inspection. Share the existing effective-field resource
|
||||||
resolution mechanics where useful, but separate resource binding from file
|
resolution mechanics where useful, but separate resource binding from file
|
||||||
reading so schema bytes remain preparation-time data.
|
reading so schema bytes remain preparation-time data. Capture optional roots
|
||||||
|
and their effective contexts, then apply the accepted scope-selection rule.
|
||||||
3. **Unify schema preparation.** Extend the validator's input route to consume
|
3. **Unify schema preparation.** Extend the validator's input route to consume
|
||||||
the selected inline value or file source. Retain one compilation/plan path for
|
the selected inline value or file source. Retain one compilation/plan path for
|
||||||
local checks, provider metadata, and repairs. Keep existing explicit-root
|
local checks, provider metadata, and repairs. Adapt explicit-root source helpers
|
||||||
source options operational; avoid parallel validators with divergent semantics.
|
to native ConfigKit composition and remove the implicit root; avoid parallel
|
||||||
|
validators with divergent semantics.
|
||||||
4. **Complete public integration.** Update output-contract conversion, typed
|
4. **Complete public integration.** Update output-contract conversion, typed
|
||||||
helpers, prompt inspection, preparation details, and ordinary/prepared runs.
|
helpers, prompt inspection, preparation details, and ordinary/prepared runs.
|
||||||
Check request replacement, continuation, and smoke-test paths that use output
|
Check request replacement, continuation, and smoke-test paths that use output
|
||||||
@@ -193,8 +246,8 @@ and new provider-specific dialects are outside this work.
|
|||||||
5. **Verify and document.** Add focused offline coverage below; update the format
|
5. **Verify and document.** Add focused offline coverage below; update the format
|
||||||
reference, GoDoc, consumer examples, and internal source/validation documentation
|
reference, GoDoc, consumer examples, and internal source/validation documentation
|
||||||
when implementation lands. Show embedded and operator collections coexisting,
|
when implementation lands. Show embedded and operator collections coexisting,
|
||||||
switching forms, and retaining the legacy explicit-root route. Describe any
|
switching forms, and configuring optional roots. Document migration from the
|
||||||
Go struct/API compatibility considerations without selecting a release here.
|
implicit root and any Go helper/API changes without selecting a release here.
|
||||||
|
|
||||||
Internal refactoring is permitted; these steps specify behavior and ownership,
|
Internal refactoring is permitted; these steps specify behavior and ownership,
|
||||||
not a permanent package layout. No interim application asset assembly layer is
|
not a permanent package layout. No interim application asset assembly layer is
|
||||||
@@ -213,10 +266,16 @@ existing injected-client or transport seams.
|
|||||||
- Imports and inheritance retain effective field context; overrides change it.
|
- Imports and inheritance retain effective field context; overrides change it.
|
||||||
Resolution is independent of process working directory and observes existing
|
Resolution is independent of process working directory and observes existing
|
||||||
root/context rules.
|
root/context rules.
|
||||||
|
- Collection and application roots follow native ConfigKit composition and
|
||||||
|
effective field context, including roots supplied through Go helpers. Collection
|
||||||
|
scope wins when configured; otherwise application scope applies. Missing files
|
||||||
|
never trigger a search of another root. Inline/source-relative schemas require
|
||||||
|
no root, and `schema_path` without an applicable root fails clearly.
|
||||||
- Native inline composition, null clearing, conflicting forms, empty objects,
|
- Native inline composition, null clearing, conflicting forms, empty objects,
|
||||||
boolean schemas, and malformed selections follow the chosen contract.
|
boolean schemas, and malformed selections follow the chosen contract.
|
||||||
- Request replacement does not borrow the prompt's schema or context. Legacy
|
- Request replacement does not borrow the prompt's schema or context. Explicit
|
||||||
schema source options retain their documented meaning.
|
schema source helpers follow the accepted composition model and documented
|
||||||
|
migration, without a special Go-option precedence rule.
|
||||||
- Missing/invalid files fail at preparation, not eager engine construction;
|
- Missing/invalid files fail at preparation, not eager engine construction;
|
||||||
prepared execution survives later source modification/removal. Inline input
|
prepared execution survives later source modification/removal. Inline input
|
||||||
and returned-detail mutation do not alter retained execution state.
|
and returned-detail mutation do not alter retained execution state.
|
||||||
@@ -229,25 +288,30 @@ existing injected-client or transport seams.
|
|||||||
continue using the common plan without duplicating schema loading or compilation
|
continue using the common plan without duplicating schema loading or compilation
|
||||||
beyond existing self-contained checks.
|
beyond existing self-contained checks.
|
||||||
|
|
||||||
## Open Decisions
|
## Decisions And Remaining Questions
|
||||||
|
|
||||||
### 1. How Should New File References Coexist With `schema_path`?
|
### 1. How Should New File References Coexist With `schema_path`?
|
||||||
|
|
||||||
**Recommendation:** add `schema` and `schema_file` while preserving `schema_path`
|
**Accepted:** add `schema` and `schema_file` while preserving `schema_path` for
|
||||||
for the explicit schema root. Each name has one meaning, so installed collections
|
an explicitly selected root. Roots are optional and configurable per collection
|
||||||
can adopt nearby schema files without changing existing consumers. Retain the
|
and application, as specified in [Optional Schema Roots](#optional-schema-roots).
|
||||||
current schema-source options. This costs an additional field but gives an
|
Use ConfigKit's standard composition and effective source contexts, with no
|
||||||
unambiguous migration path with no fallback search.
|
special Go-option precedence. Remove the implicit `"."` root. The three forms
|
||||||
|
support different collection layouts without requiring application asset assembly
|
||||||
|
or fallback searches; migration must cover the deliberate default-root change
|
||||||
|
and any necessary adaptation of Go helpers.
|
||||||
|
|
||||||
**Alternative:** replace the selection with one tagged schema-source value
|
**Alternative considered:** replace the selection with one tagged schema-source value
|
||||||
covering inline, relative-file, and explicit-root forms. This makes alternatives
|
covering inline, relative-file, and explicit-root forms. This makes alternatives
|
||||||
structurally explicit and may simplify future API representation. It requires
|
structurally explicit and may simplify future API representation. It requires
|
||||||
configuration and Go migration, or a compatibility translation layer, for a need
|
configuration and Go migration, or a compatibility translation layer. Separate
|
||||||
that can be met additively. It is viable if the cleaner single selector justifies
|
fields were selected to keep each reference form's meaning direct; the accepted
|
||||||
that migration; silently reinterpreting existing `schema_path` is not recommended.
|
root changes do not reinterpret `schema_path` as a source-relative file.
|
||||||
|
|
||||||
### 2. How Should Selection, Composition, And Clearing Work?
|
### 2. How Should Selection, Composition, And Clearing Work?
|
||||||
|
|
||||||
|
**Status: open.**
|
||||||
|
|
||||||
**Recommendation:** in JSON Schema mode, require exactly one nonnull effective
|
**Recommendation:** in JSON Schema mode, require exactly one nonnull effective
|
||||||
selection among the three forms. Null clears a selection; `{}` and `false` remain
|
selection among the three forms. Null clears a selection; `{}` and `false` remain
|
||||||
schema values, not absence. Blank file/path selections are invalid rather than
|
schema values, not absence. Blank file/path selections are invalid rather than
|
||||||
@@ -271,6 +335,8 @@ errors are preferable unless consumers demonstrate substantial value in fallback
|
|||||||
|
|
||||||
### 3. How Much Source Selection Should Programmatic Requests Expose?
|
### 3. How Much Source Selection Should Programmatic Requests Expose?
|
||||||
|
|
||||||
|
**Status: open.**
|
||||||
|
|
||||||
**Recommendation:** support inline values and existing `SchemaPath` in request
|
**Recommendation:** support inline values and existing `SchemaPath` in request
|
||||||
contracts; keep source-relative `schema_file` tied to configuration inputs with
|
contracts; keep source-relative `schema_file` tied to configuration inputs with
|
||||||
resource context. Typed configuration sources can supply that context through
|
resource context. Typed configuration sources can supply that context through
|
||||||
|
|||||||
Reference in New Issue
Block a user