Citation Format for JSON API Response Prompt

This prompt is for API developers and backend engineers who need to return RAG-generated answers inside structured JSON payloads that downstream clients, SDKs, and OpenAPI-described endpoints can consume without fragile string parsing. The job-to-be-done is producing a citation object that is schema-compliant, field-stable, and backward-compatible across API versions—not just a human-readable attribution string. The ideal user is someone integrating an LLM into a production API surface where the response contract is already defined in an OpenAPI spec or typed client SDK, and where breaking the citation shape causes integration failures in mobile apps, web frontends, or third-party consumers.

Use this prompt when you control the API response schema and need every answer to include a deterministic citations array with guaranteed fields such as source_id, document_title, chunk_text, relevance_score, and location. It is appropriate when the consuming system expects to render citations in its own UI components, run analytics on citation frequency, or audit source usage programmatically. The prompt enforces a strict output contract: no missing fields, no type coercion surprises, and no free-text citation blocks that require regex extraction. It is also the right choice when you need to version your citation format and run backward-compatibility tests against stored golden responses.

Do not use this prompt when the primary consumer is a human reading plain text in a chat interface, when the citation format is still being designed and subject to frequent ad-hoc changes, or when the model's output will be displayed directly without a validation layer. It is also the wrong tool when you need rich inline citation markers inside prose paragraphs—this prompt produces a separate structured citations block, not interleaved reference tokens. If your API clients cannot handle a breaking schema change without a migration window, pair this prompt with a citation format migration prompt and run round-trip fidelity tests before deployment. For high-stakes domains such as legal or clinical RAG, always add a post-generation validation step that checks field presence, type correctness, and source grounding before the JSON reaches the API response writer.

This prompt template is designed for API developers who need RAG-generated answers returned in structured JSON payloads with deterministic citation formats. It enforces a strict output schema where every claim is backed by a citation object containing source metadata, excerpt text, and confidence indicators. The template is built to be dropped into a production pipeline where the response will be validated against an OpenAPI schema before reaching the client SDK.

codeCopy
You are an API response generator for a RAG question-answering system. Your output must be valid JSON conforming to the schema below. Do not include any text outside the JSON object.

## INPUT
User Question: [USER_QUESTION]
Retrieved Contexts: [RETRIEVED_CONTEXTS]

## OUTPUT SCHEMA
{
  "answer": string,  // The synthesized answer, max [MAX_ANSWER_LENGTH] characters
  "citations": [
    {
      "source_id": string,  // The document ID from the retrieved context
      "source_title": string,  // Human-readable source title
      "excerpt": string,  // Verbatim excerpt from source, max [MAX_EXCERPT_LENGTH] characters
      "excerpt_start": integer,  // Character offset where excerpt begins in source
      "excerpt_end": integer,  // Character offset where excerpt ends in source
      "relevance_score": number,  // 0.0 to 1.0, how relevant this source is to the answer
      "confidence": number,  // 0.0 to 1.0, model confidence in this citation's accuracy
      "claim_referenced": string  // The specific claim in the answer this citation supports
    }
  ],
  "abstention": {
    "is_abstained": boolean,  // True if the system cannot answer with sufficient confidence
    "reason": string | null,  // Explanation if abstained, null otherwise
    "partial_answer": string | null  // Best-effort partial answer if applicable, null otherwise
  },
  "metadata": {
    "model_version": string,  // Version of the model generating this response
    "generated_at": string,  // ISO 8601 timestamp
    "total_sources_retrieved": integer,  // Number of sources provided in input
    "total_sources_cited": integer  // Number of sources actually cited
  }
}

## CONSTRAINTS
- Every factual claim in "answer" must have at least one corresponding citation in the "citations" array.
- "excerpt" must be a verbatim substring from the source. Do not paraphrase or modify.
- If no retrieved context supports a confident answer, set "abstention.is_abstained" to true and provide a reason.
- If sources conflict, include citations for all conflicting positions and note the conflict in the answer.
- "relevance_score" should reflect retrieval ranking quality; "confidence" should reflect how well the excerpt supports the claim.
- Do not fabricate source_ids, excerpts, or offsets. If a source lacks sufficient detail, abstain.
- The JSON must be parseable by standard JSON parsers. Escape all special characters.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

Adaptation guidance: Replace [USER_QUESTION] with the end user's query and [RETRIEVED_CONTEXTS] with the structured context objects from your retrieval pipeline—each should include source_id, title, and full_text fields at minimum. Set [MAX_ANSWER_LENGTH] and [MAX_EXCERPT_LENGTH] based on your API contract limits. The [FEW_SHOT_EXAMPLES] placeholder should be replaced with 2-3 concrete input-output pairs showing correct citation behavior, including one example where the system correctly abstains. The [RISK_LEVEL] field should be set to "high", "medium", or "low" to adjust the model's caution threshold—high-risk domains like healthcare or legal should trigger earlier abstention. Before deploying, validate that your OpenAPI schema matches the output structure exactly, and run backward-compatibility tests against existing client SDKs to ensure field additions don't break deserialization.

This prompt is designed to be the final step in a RAG pipeline, sitting between evidence retrieval and the API response serializer. It expects a pre-assembled context block containing retrieved passages with their source metadata, a user question, and a strict JSON schema for the citation object. The prompt is not a conversational agent; it should be called as a stateless transformation with a single-turn request. The ideal implementation pattern is a dedicated microservice or serverless function that receives the retrieval results, constructs the prompt payload, calls the model, validates the output against the target OpenAPI schema, and either returns the validated object or triggers a repair loop.

Validation and repair loop: The output must be validated against the expected JSON schema before it reaches the API gateway. Use a JSON Schema validator (such as ajv for Node.js or jsonschema for Python) to check required fields, enum values, and field types. If validation fails, capture the specific error messages and feed them back into a retry prompt that includes the original context, the malformed output, and the validation errors. Limit retries to a maximum of 2 attempts to avoid infinite loops. Log every validation failure and retry attempt with the model's raw output for debugging. For high-stakes domains, add a human review queue for outputs that fail after all retries, rather than silently dropping the request.

Model choice and temperature: Use a model with strong JSON mode or structured output support, such as GPT-4o with response_format: { type: 'json_schema' } or Claude 3.5 Sonnet with tool-use mode constrained to the target schema. Set temperature to 0 or near-zero to maximize format determinism. If your model does not support native structured output, include a post-processing step that strips markdown fences and parses the JSON, but be aware that this increases the failure rate. For production systems, prefer models with guaranteed JSON output contracts.

Backward-compatibility testing: Before deploying a new version of this prompt, run a regression suite against a golden dataset of known inputs and expected citation structures. Compare field presence, enum values, and nested object shapes. Flag any breaking changes—such as renamed fields, changed types, or missing required properties—as release blockers. Store prompt versions alongside their schema versions in your prompt registry, and include the schema version in the API response metadata so clients can detect mismatches.

Logging and observability: Log the full prompt payload, model response, validation result, and final output for every request. Include a correlation ID that ties the citation generation step back to the retrieval step and the original user request. This trace is essential for debugging hallucinated citations, missing sources, or format drift. Set up alerts on validation failure rate spikes, which often indicate prompt drift, model version changes, or upstream retrieval format changes that break the context block structure.