Schema / a contract the code can trust

A schema locks `rewrite` output into a guaranteed shape — query, filters, persona — every call. Consistent structure is not the same as grounded truth: the model still answers from training weights, not your `phones.json`.

Architectural Position

Before

fn(query_user, prompt_rewrite) → query_refined

search(query_refined) → results

After

(, , ) →

search() →

fn: The LLM call, now with a schema constraint on the output
query_user: Raw natural language input from the user
prompt_rewrite: The system prompt for rewriting — now paired with a schema to enforce consistent output shape
schema: A strict output contract — { query, filters, persona }
query_structured: Schema-validated output — same content, guaranteed shape every call
results: Ranked phone results from semantic search

Step by Step

# The failure from Layer 2

Run 1: "simple smartphone easy navigation
        elderly large screen"

Run 2: {"category": "budget",
        "user": "elderly",
        "features": ["large display"]}

# Embedding a JSON string ≠ embedding a sentence
# Retrieval results differ on every Run 2
# Downstream code breaks on shape mismatch

An inconsistent output shape from rewrite makes retrieval non-deterministic. Schema fixes this by enforcing a contract.

1 / 5

Implementation

What you build

A JSON schema defining the rewrite output: { query, filters, persona }
An LLM call with structured output enforcing that schema on every call
Persona re-ranking applied after retrieval using the extracted persona field

What it fixes

rewrite output has a guaranteed shape every call. Downstream code can parse query_structured reliably. Persona extraction enables intent-aware re-ranking.

Key Concepts

Structured output: An LLM feature that constrains the model to produce valid JSON matching a schema you define. Available in most major APIs.
Persona: A re-ranking signal extracted from the user query — e.g. "elderly", "teen", "photographer". Applied after semantic retrieval to re-order the top results.
Validation: Checking that a returned object matches the expected schema. If validation fails, the call can be retried or the error surfaced explicitly.
Pydantic / Zod: Schema validation libraries for Python and TypeScript respectively. The de facto tools for enforcing structured output contracts in LLM pipelines.

The Failure

The Fluency Law
Fluent output signals nothing about correctness. Validation is yours to build.

Schema is working. rewrite returns a clean query_structured. Semantic search retrieves the Moto G84 as the top result. The user asks: "Does it have wireless charging?" The model answers confidently. But it is not looking at your phones.json. It is answering from training weights. The spec it states may be accurate for a different model, or simply wrong. Schema controls the shape of output. It does not control the source of truth.

What it reveals

Output is structured and reliable — but the model answers from its own training knowledge, not from your phones.json.

Implication

Ability LLM can produce structured output reliably — but only with guidance. Without schema, fluency masks incorrectness.

Behaviour Schema defines the contract between LLM and downstream code. Breaking the schema breaks the pipeline silently.

Code Validation logic is now required. Pydantic (Python) or Zod (JS). Retry logic needed for schema failures.

Design No visible change for the user. The contract is internal. Design impact is reliability, not appearance.

Economics Schema failures trigger retries. Each retry = additional tokens. Failure rate directly affects cost.