7.7 KiB
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:
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 still selects one schema source, and
internal engine wiring 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 includes
effective resource context in the ConfigKit handoff, and the
content_file contract 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:
output:
format: json
validation_mode: json_schema
schema:
type: object
properties:
summary:
type: string
required: [summary]
additionalProperties: false
File-backed:
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.
RunPreparedshould 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,
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.