167 lines
7.7 KiB
Markdown
167 lines
7.7 KiB
Markdown
# Feature Request: Prompt-Owned Inline And Source-Relative Schemas
|
|
|
|
**Status:** Requested by the Notarius consumer; proposed behavior, not an
|
|
implemented API or an approved implementation plan.
|
|
|
|
## Requested Capability
|
|
|
|
Allow a prompt's structured-output schema to be supplied directly inline in its
|
|
output definition or loaded from a file relative to the source that defines the
|
|
schema reference. Use the same effective resource-context model already used by
|
|
`content_file`, including imports, inheritance, embedded filesystems, and operator
|
|
sources.
|
|
|
|
The guiding user observation is that a structured-output schema is part of a
|
|
prompt definition. Users generally expect it to behave like any other part of
|
|
that definition: they can provide it inline or place it in a separate file loaded
|
|
relative to the prompt where it is defined. Requiring a separately assembled,
|
|
engine-wide schema filesystem makes that ordinary mental model unnecessarily
|
|
hard to express.
|
|
|
|
## Consumer Problem
|
|
|
|
Notarius is moving to native PromptKit declarations, with embedded defaults and
|
|
higher-priority operator prompt sources. It wants to remove its asset registries,
|
|
synthetic mounts, file copying, flattened schema namespace, and separate schema
|
|
identity/digest machinery.
|
|
|
|
PromptKit already composes prompt definitions and resolves message files using
|
|
their source contexts. Schema paths currently resolve against a separately
|
|
selected schema root. Replacing an embedded prompt with an operator prompt can
|
|
therefore require changing the schema source for the whole engine, assembling a
|
|
custom filesystem, or copying unrelated default schemas into the replacement
|
|
root. An inline schema cannot currently express the simpler alternative either.
|
|
|
|
The desired arrangement is straightforward:
|
|
|
|
```text
|
|
embedded/
|
|
spell-extraction.yml
|
|
spell-response.json
|
|
operator/
|
|
custom-extraction.yml
|
|
custom-response.json
|
|
```
|
|
|
|
Each prompt references its nearby schema, or embeds that schema directly.
|
|
Replacing one prompt leaves unchanged prompts and their schemas usable. PromptKit
|
|
owns this reusable resource resolution; Notarius supplies prompt content and
|
|
retains domain interpretation and artifact validation.
|
|
|
|
## Why The Current Behavior Appears To Exist
|
|
|
|
The original public engine facade exposed separate prompt, profile, and schema
|
|
sources (see repository history at `e4899fb`). The current
|
|
[`WithSchemaFS` option](../../engine.go) still selects one schema source, and
|
|
[internal engine wiring](../../internal/engine/engine.go) constructs a validator
|
|
bound to that source.
|
|
|
|
This suggests an inheritance from the earlier architecture, rather than a
|
|
fundamental requirement that every prompt share one schema root. That is an
|
|
inference from the implementation and history, not a documented statement of
|
|
the original author's intent. A central root remains useful when an application
|
|
selects output contracts programmatically; the request is to support ordinary
|
|
prompt-owned schemas as well.
|
|
|
|
The newer configuration model already supplies the relevant foundation.
|
|
[Configuration ownership ADR-0001](../adr/0001-configuration-boundary.md) includes
|
|
effective resource context in the ConfigKit handoff, and the
|
|
[`content_file` contract](../formats.md#messages-and-templates) resolves each
|
|
effective reference using its own source context. Schema references should have
|
|
an equivalent native path through this model.
|
|
|
|
## Proposed Consumer Experience
|
|
|
|
These output fragments illustrate the two requested forms. `schema` and
|
|
`schema_file` are suggested names only; exact syntax and public Go API design
|
|
remain upstream decisions. They do not describe currently supported fields.
|
|
|
|
Inline:
|
|
|
|
```yaml
|
|
output:
|
|
format: json
|
|
validation_mode: json_schema
|
|
schema:
|
|
type: object
|
|
properties:
|
|
summary:
|
|
type: string
|
|
required: [summary]
|
|
additionalProperties: false
|
|
```
|
|
|
|
File-backed:
|
|
|
|
```yaml
|
|
output:
|
|
format: json
|
|
validation_mode: json_schema
|
|
schema_file: ./summary-response.json
|
|
```
|
|
|
|
Both forms should feed the same native preparation, structural validation,
|
|
provider structured-output, and repair behavior. No application schema loader
|
|
or registry should be necessary to use them.
|
|
|
|
## Resource And Composition Semantics
|
|
|
|
- A file reference uses the source context of the effective schema-reference
|
|
field, rather than a process working directory or the final child prompt's
|
|
location regardless of origin.
|
|
- An inherited reference retains its originating context. An overridden reference
|
|
uses the overriding source's context. Imports and collection composition follow
|
|
the same native rules as other resource-bearing fields.
|
|
- Embedded sources and operator files can coexist within one engine. Existing
|
|
filesystem-root rules apply; this does not request a second path-security model.
|
|
- Inline schema values participate in native configuration composition. Define
|
|
presence, replacement/clearing, and selection between inline and file-backed
|
|
forms explicitly, using ConfigKit's effective values rather than reconstructing
|
|
configuration history in the runner.
|
|
- Retain an explicit schema-source route for programmatic request contracts and
|
|
existing root-based consumers. Define how it interacts with prompt-owned forms;
|
|
avoid ambiguous multi-root searching or silently reinterpreting existing paths.
|
|
- Preserve preparation-time loading for schema files and the prepared execution's
|
|
captured validation plan. `RunPrepared` should execute with the schema captured
|
|
during preparation rather than reopening the source.
|
|
|
|
This provides composition through schema references. It does not require a
|
|
filename-based schema overlay system: an operator replacement explicitly selects
|
|
its schema, while unchanged prompts continue using theirs.
|
|
|
|
## Self-Contained Schemas Remain A Separate Concern
|
|
|
|
The self-contained-schema decision has a concrete rationale. Local validation
|
|
could resolve external files that were absent from the single schema object sent
|
|
to the provider. Repository history at `c542b81` records the decision to remove
|
|
that mismatch without introducing schema bundling.
|
|
|
|
That rationale does not require a global schema root. PromptKit can load a
|
|
self-contained schema beside its prompt, or accept it inline, and submit the same
|
|
complete object. Preserve the current [self-contained schema semantics](../formats.md#schemas),
|
|
including supported in-document references. Loading the root schema from a
|
|
prompt-relative file does not imply loading external JSON Schema `$ref` resources.
|
|
Schema bundling and network resource loading are outside this request.
|
|
|
|
## Suggested Verification And Documentation
|
|
|
|
- Equivalent inline and file-backed schemas produce equivalent local validation
|
|
and provider constraints.
|
|
- Embedded and operator prompts with different schema files work in one engine,
|
|
including files with the same basename in different source contexts.
|
|
- Replacing one prompt does not require copying or replacing unrelated schemas.
|
|
- Imported/inherited references preserve their defining context; overridden
|
|
references resolve against the new context independently of working directory.
|
|
- Inline/file selection and clearing follow the documented native composition
|
|
rules, including deliberate errors for unresolved or ambiguous selections.
|
|
- Existing explicit-root and request-level contract behavior has a deliberate,
|
|
documented compatibility path.
|
|
- Missing or invalid schema files produce useful errors identifying the relevant
|
|
prompt/reference. Self-contained-schema behavior remains consistent for both
|
|
new forms, and prepared executions retain their captured schema.
|
|
|
|
Document the selected syntax, source-context behavior, request-level interaction,
|
|
and migration in the format reference, GoDoc, and consumer examples when
|
|
implemented. The request does not select a release number or require a new
|
|
application-owned asset assembly layer as an interim design.
|