Forcing Structured Answers with a Knowledge Response Schema

Use the optional Response Schema on a Knowledge node in Query mode to force JSON output with predictable fields, so the nodes after it can read those fields without parsing free text.

Overview

A Knowledge node in Query mode searches a collection and uses an AI model to synthesize an answer from the matching passages. By default that answer comes back as free-form prose, which is fine for a person to read but awkward for the rest of a workflow to consume. The Response Schema field changes that: when you supply a JSON schema, Spojit instructs the synthesis model to return an object that matches the shape you defined, so the answer arrives as structured data instead of a paragraph.

The mental model is "ask a question, get back a record." Instead of writing fragile Transform or Regex steps to pull a number or a status out of a sentence, you declare the fields you want up front and the Knowledge node fills them in. Downstream nodes then reference those fields with handlebars like {{ answer.amount }} or {{ answer.status }}, exactly as they would with any other node output. This guide covers the three Query-mode settings that shape that output: Response Schema, Result Count, and Model. The companion article on querying your knowledge base walks through the basics of Query mode but does not cover the Response Schema option.

Before You Start

A Knowledge node already set to Query mode, with a Collection selected (a persistent collection, or Transient to query documents embedded earlier in the same run).
At least one document embedded in that collection so the query returns passages to synthesize from.
A rough idea of the fields you want back, for example an invoice total, a vendor name, and a confidence flag.

Steps

Open the workflow in the Workflow Designer, click the Knowledge node, and confirm Query is selected as the mode. Then work through the three output settings below.

Step 1: Write the Prompt

In the Prompt field, ask your question in natural language and name the fields you expect. Be explicit, because the prompt and the schema work together. For example:

From the supplier invoice, return the vendor name, the total amount due as a number, the due date in YYYY-MM-DD format, and whether a purchase order number is present.

You can template the prompt with upstream variables, such as {{ input.subject }} or {{ attachment.filename }}, so the same node adapts to each run.

Step 2: Define the Response Schema

In the Response Schema field, paste a JSON schema describing the object you want back. List each field, its type, and which fields are required. A schema for the prompt above looks like this:

{
  "type": "object",
  "properties": {
    "vendor": { "type": "string" },
    "amountDue": { "type": "number" },
    "dueDate": { "type": "string" },
    "hasPoNumber": { "type": "boolean" }
  },
  "required": ["vendor", "amountDue"]
}

When this field is filled in, the synthesis model is constrained to return an object that matches the shape, so the node output is structured rather than prose. Keep the schema flat and small: a handful of clearly named fields is far more reliable than a deeply nested structure. Leave Response Schema blank if you genuinely want a written paragraph (for example, a summary you will drop straight into a Send Email body).

Step 3: Set the Result Count

The Result Count field controls how many matching passages from the collection are handed to the model before it synthesizes an answer. It defaults to 5. Raise it when an answer needs evidence spread across many passages (for example, "list every product mentioned in these policy documents"), and lower it when you want a tight, focused answer drawn from only the closest matches. More results give the model more context but also more material to weigh, so tune this against the kind of question you are asking rather than always reaching for a large number.

Step 4: Pick the Synthesis Model

The Model field chooses the AI model that reads the retrieved passages and produces the answer. This is the model that has to honor your schema, so for strict structured extraction prefer a capable model over the smallest available one. For short factual lookups a lighter model is usually enough and costs fewer credits. The synthesis model is separate from the embedding model fixed on the collection at creation time: changing Model here only affects how the answer is written, never how documents were indexed.

Step 5: Set the Output Variable and Reference the Fields

Give the node an Output Variable name, for example answer. After the run, the structured object is available to later nodes through that variable. A downstream Condition node can branch on {{ answer.amountDue }}, a Connector node in Direct mode can map {{ answer.vendor }} into a tool input, and a Send Email node can drop {{ answer.dueDate }} into its body. Because the fields are named and typed, you avoid the brittle text parsing you would otherwise need.

Tips

Mirror your prompt and schema. If the prompt asks for a "total amount" but the schema calls the field amountDue, name the field in the prompt too so the model maps them correctly.
Mark only the fields you truly need as required. Optional fields let the model return a partial answer when a document genuinely lacks that detail, instead of inventing a value.
Pair this with a Transient collection for one-off extraction: embed a single document earlier in the run, query it with a Response Schema, and let the collection clean up automatically when the run finishes.
If you are unsure how to phrase a schema, ask Miraxa, the intelligent layer across your automation, to draft one from a description of the fields you want, then refine it in the properties panel.

Common Pitfalls

Invalid JSON in Response Schema defeats the whole purpose. Validate the schema text (a missing comma or unquoted key is easy to miss) before saving the node.
Asking for a field the documents do not contain pushes the model to guess. Keep questions answerable from the collection, and add a confidence or found boolean field if you want to detect misses downstream.
An overly large Result Count can crowd the model with loosely related passages and blur the answer. Start near the default of 5 and adjust based on the results you see.
Deeply nested schemas are harder for the model to fill reliably. Prefer a flat object with clear field names, and split complex extraction into more than one query if needed.