Deterministic Citation Output Contract Prompt

This prompt is for API builders and RAG system engineers who need citations returned as deterministic, machine-readable JSON objects rather than free-text inline references. Use it when your application must parse citation fields programmatically, validate field presence before responding to clients, or guarantee that every claim maps to a structured source object with required fields like source_id, chunk_index, and excerpt. The core job-to-be-done is transforming a set of ranked evidence passages into a strict, schema-compliant output contract that downstream services can consume without parsing ambiguity or brittle regex extraction.

This prompt belongs in the answer-generation layer of a RAG pipeline, after retrieval and evidence ranking but before the final API response is serialized. It is not a replacement for retrieval, evidence selection, or fact-verification prompts. It assumes you already have ranked passages and need them formatted into a structured citation payload. The ideal user is an engineering lead or senior developer integrating a RAG system into a product API, where the response format is part of a published contract (e.g., an OpenAPI spec). If your use case is a chat UI where citations are displayed inline for human readers, a simpler inline citation formatting prompt is more appropriate. This prompt is overkill when human readability is the primary goal and machine parsing is not required.

Do not use this prompt when you need the model to decide which sources are relevant, rank them by credibility, or verify factual accuracy. Those are separate concerns handled by retrieval, ranking, and fact-verification prompts earlier in the pipeline. This prompt also should not be used as a guard against hallucination; it formats what it is given and will faithfully structure incorrect evidence if that evidence is provided. Always pair this prompt with an upstream evidence selection step and a downstream validation step that checks for required field presence, valid source_id formats, and non-empty excerpts. For high-stakes domains like healthcare or legal, add a human review gate before the structured output is served to end users.

This prompt template is designed for API builders and RAG system engineers who need citations in a predictable, machine-readable structure every time. Unlike free-text citation prompts, this contract guarantees that every response will contain a valid JSON object with required fields present, making it safe to parse in downstream application code without defensive null checks or format guessing. The template uses square-bracket placeholders for retrieved context, user question, output schema, and constraints so you can wire it directly into your retrieval pipeline and swap schemas without rewriting the instruction surface.

codeCopy
You are an answer generator that produces strictly valid JSON output. You must follow the output contract exactly. Do not include any text outside the JSON object.

## CONTEXT
[CONTEXT]

## QUESTION
[QUESTION]

## OUTPUT CONTRACT
You must return a single JSON object matching this schema:
{
  "answer": "string (required, never null, synthesized from context only)",
  "citations": [
    {
      "source_id": "string (required, never null, from context metadata)",
      "quote": "string (required, never null, verbatim excerpt from context)",
      "relevance": "string (required, one of: 'direct', 'supporting', 'background')",
      "location": "string (required, never null, chunk or page reference)"
    }
  ],
  "confidence": "string (required, one of: 'high', 'medium', 'low', 'insufficient')",
  "abstention_reason": "string | null (required field, null if confidence is not 'insufficient')"
}

## RULES
1. Every claim in "answer" must be supported by at least one citation in the "citations" array.
2. If the context does not contain enough information to answer, set "confidence" to "insufficient", set "answer" to an empty string, and populate "abstention_reason" with a specific explanation of what is missing.
3. Never fabricate source_ids, quotes, or locations. If a field cannot be populated from context, you must abstain.
4. The "citations" array may be empty only if "confidence" is "insufficient".
5. Return ONLY the JSON object. No markdown fences, no explanatory text.

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, replace each square-bracket placeholder with your pipeline's actual inputs. [CONTEXT] should contain the retrieved passages with their metadata (source_id, location, chunk text). [QUESTION] is the user's query. [EXAMPLES] should include at least two few-shot examples showing both a successful answer with citations and a clean abstention case where context is insufficient. [RISK_LEVEL] accepts values like low, medium, or high to adjust the model's abstention threshold—at high, the model should abstain unless evidence is unambiguous. Before deploying, validate that your context formatting consistently includes the fields referenced in the output contract (source_id, location) or the model will have no valid data to populate them. If you need a different citation schema, modify the JSON structure but preserve the required-field contract and abstention logic. Always run schema validation on the model's output in your application layer before parsing, and implement a retry with the same prompt if validation fails.

The Deterministic Citation Output Contract Prompt is designed for API endpoints where downstream consumers—SDKs, UI components, audit systems—parse the citation structure programmatically. A missing field or type mismatch breaks the contract. The implementation harness must therefore treat the model output as an untrusted payload that requires schema validation, repair attempts, and a clear escalation path before it reaches the caller. This section covers the integration layer: how to call the prompt, validate the response, handle failures, and log enough context to debug citation drift over time.

Start by wrapping the prompt call in a function that accepts the user question, retrieved chunks with their document IDs, and any style or metadata constraints. The prompt template expects these inputs mapped to the [QUESTION], [RETRIEVED_CHUNKS], and [CITATION_CONTRACT] placeholders. Each chunk must carry a stable, unique doc_id and preferably a chunk_index or position field. If your retrieval pipeline does not produce these identifiers, add them before calling the prompt—the contract depends on them. On the response side, parse the model output as JSON immediately. If the model wraps the JSON in markdown fences, strip them before parsing. Then validate the parsed object against a schema that enforces: (1) citations is an array, (2) each citation object contains doc_id (string, non-empty), claim_index (integer), and quote_text or paraphrase_text (string), and (3) every claim_index referenced in the answer_claims array has a corresponding citation entry. Use a library like jsonschema (Python) or ajv (Node.js) with strict mode enabled—no additional properties, no type coercion.

When validation fails, do not silently return a degraded response. Implement a retry loop with a maximum of two additional attempts. On each retry, append the specific validation error to the prompt as a [VALIDATION_ERROR] placeholder, instructing the model to fix only the cited issue while preserving the rest of the structure. Common recoverable failures include missing quote_text for verbatim claims, doc_id values that don't match any provided chunk ID, and claim_index out of range. If the third attempt still fails validation, log the full input, output, and error trace, then return a structured error response to the API caller with a citation_contract_failure status and the last validation message. Never fall back to an unvalidated citation format.

Logging is essential for citation contract monitoring. For every successful response, log the number of claims, the number of unique source documents cited, and the validation pass latency. For failures, log the specific schema violation, the retry count, and whether the failure was recoverable or terminal. Over time, aggregate these logs to detect citation drift: a rising rate of missing_doc_id errors may indicate that your retrieval pipeline changed chunk identifiers without updating the prompt context, while an increase in claim_index_out_of_range suggests the model is fabricating claims beyond what the evidence supports. Wire these metrics into your existing observability stack so that citation quality degrades visibly, not silently.

For model choice, prefer models with strong JSON-mode or structured-output capabilities. If your provider supports response_format with a JSON Schema parameter, use it alongside the prompt instructions rather than relying on the prompt alone. This dual enforcement—prompt-level contract description plus API-level schema constraint—reduces format drift. When using models that don't support native structured output, increase the retry budget to three attempts and consider adding a lightweight repair step that fixes common JSON syntax errors (trailing commas, unescaped quotes) before full schema validation. Avoid using this prompt with models known to struggle with multi-field JSON generation under 7B parameters unless you add a dedicated output repair layer.