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