GraphQL Response Envelope with Errors Array Prompt

Use this prompt when you are building or maintaining a GraphQL gateway and need to enforce a consistent, spec-compliant response shape across multiple upstream resolvers or microservices. The primary job-to-be-done is wrapping partial or complete resolver outputs into a predictable envelope containing data, errors, and optional extensions fields, ensuring that any client consuming your graph can reliably parse both successful and failed responses. The ideal user is a backend engineer, platform architect, or API gateway developer who already understands the GraphQL specification's section on response format and needs a programmatic way to normalize outputs before they reach the client.

This prompt is most valuable when your architecture involves stitching, federation, or a custom gateway layer where individual services may not produce GraphQL-compliant error shapes on their own. It is also appropriate when you need to inject extensions metadata—such as tracing IDs, cost analysis, or deprecation warnings—into every response without modifying each resolver. You should not use this prompt for designing the schema itself, for authoring resolver logic, or for handling transport-level concerns like HTTP status codes. It is strictly focused on shaping the JSON payload body after execution.

Before applying this prompt, ensure you have a clear specification for what constitutes a valid data payload, a defined error taxonomy (including message, locations, path, and extensions fields), and a decision on whether partial data is allowed alongside errors. The prompt works best when you provide concrete examples of malformed upstream responses and the desired corrected output. Avoid using this prompt as a substitute for proper resolver-level error handling; instead, treat it as the final normalization layer that guarantees every client receives a structurally valid GraphQL response. Proceed by gathering representative upstream payloads—both successful and error cases—and defining your exact extensions contract before wiring this into your gateway pipeline.

This prompt template is designed to be wired into a GraphQL gateway or API orchestration layer. It instructs the model to produce a response envelope that strictly conforms to the GraphQL specification's requirements for the top-level data, errors, and extensions fields. The template uses square-bracket placeholders so you can inject the original query, upstream resolver results, partial error payloads, and any operational extensions before sending the request to the model.

textCopy
You are a GraphQL response formatter. Your task is to construct a valid GraphQL response envelope from the provided inputs. You must follow the GraphQL specification (June 2018 edition) for the structure of the response map.

## Inputs
- **GraphQL Query:** [GRAPHQL_QUERY]
- **Resolver Results (JSON):** [RESOLVER_RESULTS]
- **Upstream Errors (JSON Array, optional):** [UPSTREAM_ERRORS]
- **Extensions (JSON Object, optional):** [EXTENSIONS]

## Output Schema
Produce a single JSON object with the following top-level keys:
- `data` (object or null): The successful response data. Must be `null` if no data is returned and errors are present. Must match the shape requested in the GraphQL query.
- `errors` (array of objects, optional): An array of error objects if any errors occurred. Each error object must contain a `message` string. It may optionally contain `locations` (array of `{line, column}` objects), `path` (array of field names/indices), and `extensions` (object with a `code` string).
- `extensions` (object, optional): A map for protocol extensions. If provided, merge the input [EXTENSIONS] here.

## Constraints
- If [UPSTREAM_ERRORS] is provided and non-empty, the `errors` array must be populated. The `data` field should be `null` unless partial data is explicitly requested and available.
- If a field in [RESOLVER_RESULTS] is `null` due to an error, that error must be represented in the `errors` array with a `path` reflecting the field's location in the query.
- Do not include the key `errors` if there are no errors.
- Ensure all `path` arrays use the correct string field names and integer indices as per the query.
- The output must be a single, parseable JSON object with no surrounding text or markdown fences.

## Examples
[EXAMPLES]

## Risk Level
[RISK_LEVEL]

To adapt this template, replace the placeholders with data from your GraphQL execution engine. [RESOLVER_RESULTS] should be the partial or complete data map from your resolvers. [UPSTREAM_ERRORS] is the array of GraphQL errors you've already collected, which the model will normalize and de-duplicate. The [EXAMPLES] placeholder is critical for teaching the model how to handle edge cases like null propagation and list index paths; provide at least two few-shot examples showing a partial success scenario and a full error scenario. For high-risk operations, set [RISK_LEVEL] to HIGH and add a final instruction requiring a human to review the output before it is returned to the client.

This prompt is designed to sit inside a GraphQL gateway or API middleware layer that intercepts raw model outputs and reshapes them into a spec-compliant GraphQL response envelope. The primary integration point is a post-generation transformation step: the model produces structured content (data, errors, extensions), and your application layer validates, normalizes, and wraps that content before returning it to the client. Do not expose raw model output directly to GraphQL consumers—always pass it through this envelope layer to guarantee the data, errors, and extensions fields match your schema contract.

Wire the prompt into your application with a strict validation pipeline. After the model returns its JSON payload, run a validator that checks: (1) the root object contains exactly data, errors, and extensions keys with no extras; (2) data is either an object or null, never an array or scalar; (3) errors is an array where each element has a required message string and optional locations, path, and extensions fields; (4) path arrays contain only strings or integers; (5) locations arrays contain objects with line and column integers. If validation fails, log the raw output and the validation error, then retry with the same prompt plus the validator's error message appended as a correction instruction. After two retries, fall back to a safe error envelope: { "data": null, "errors": [{ "message": "Internal processing error" }], "extensions": {} }. For high-stakes production use, route outputs that fail validation to a human review queue rather than silently dropping them.

Model choice matters for this workflow. Use a model with strong JSON mode or structured output support (e.g., GPT-4 with response_format: { type: "json_object" }, Claude with tool-use mode, or any model that guarantees valid JSON output). Avoid models that frequently inject markdown fences or commentary outside the JSON block. If you must use a model without native JSON mode, add a post-processing step that extracts the first JSON object from the response using a regex or JSON parser before validation. For logging and observability, capture the prompt version, model ID, raw output, validation result, and final envelope in your tracing system. This makes it possible to debug partial response handling, error path accuracy, and location reference correctness when clients report issues.

When integrating with an existing GraphQL server, ensure the envelope prompt's output schema matches your server's ExecutionResult type exactly. If your server uses additional envelope fields (e.g., hasNext, subscriptionId for subscriptions), add those to the prompt's [OUTPUT_SCHEMA] placeholder. Test the integration with a suite of eval cases: a successful query returning only data, a query with field-level errors returning both data and errors, a completely failed query returning data: null with errors, and a query with extension metadata. Run these evals on every prompt change and model upgrade. The most common production failure mode is the model omitting the locations array on errors or using incorrect path segment types—add specific eval assertions for these cases.