Error Body Schema Validation Prompt

Use this prompt when you need to programmatically verify that API error response bodies conform to a documented schema. This is a critical step in API governance, CI/CD pipelines, and contract testing. The primary job-to-be-done is automated enforcement: ensuring that every error payload returned by your API—whether a 400 validation failure or a 503 service unavailable—matches the structure you promised to consumers. This prompt is designed for API designers, platform engineers, and QA teams who treat error responses as a product surface, not an afterthought. It validates error payloads against a target schema, flagging missing required fields, type mismatches, and undocumented fields that would break client-side parsing.

The prompt handles versioned schemas and backward compatibility checks, making it suitable for multi-version API maintenance where v1 and v2 error bodies may differ intentionally. It accepts a target schema (typically an OpenAPI component or JSON Schema definition), one or more error response bodies, and version context. The output is a structured validation report that can be consumed by CI gates, contract testing frameworks, or governance dashboards. Do not use this prompt for generating error schemas from scratch—that requires a design workflow with domain expertise. Do not use it for classifying the root cause of an error or drafting remediation steps; those are separate workflows covered by sibling prompts like Common Cause Classification and Resolution Step Drafting. This prompt is also not suited for validating successful response bodies, which typically have different schema constraints and testing patterns.

Before using this prompt, ensure you have a well-defined error schema to validate against. If your API lacks documented error schemas, start with the Error Code Catalog Generation Prompt or the Error Code Taxonomy Builder Prompt to establish that foundation. Wire this validation into your CI/CD pipeline as a gate: run it against recorded error responses from staging or production traffic, and block releases that introduce schema regressions. For high-risk APIs where error body changes could break critical integrations, pair this automated validation with human review of the validation report before approving a release. The next section provides the copy-ready prompt template you can adapt with your own schemas, version rules, and output format requirements.

This prompt template is designed to be wired into a CI pipeline, a pre-release documentation review, or an API gateway test harness. It accepts a raw error response body and the corresponding schema definition, then produces a structured validation report. The report flags missing required fields, type mismatches, undocumented fields, and backward-compatibility breaks when a versioned schema is provided. Use this prompt when you need to ensure that every error response your API emits matches its published contract before customers encounter a discrepancy.

textCopy
You are an API schema validator. Your task is to validate an error response body against its documented schema.

## INPUT
Error Response Body:
[ERROR_BODY]

Documented Schema:
[ERROR_SCHEMA]

Previous Schema Version (for backward-compatibility checks, optional):
[PREVIOUS_SCHEMA]

## CONSTRAINTS
- Flag every field in the error body that is not defined in the documented schema.
- Flag every required field in the documented schema that is missing from the error body.
- Flag every field whose type in the error body does not match the type defined in the documented schema.
- If [PREVIOUS_SCHEMA] is provided, flag any field that was required in the previous version but is now missing or has a changed type.
- Do not hallucinate fields. Only report on fields present in the input or defined in the schema.

## OUTPUT_SCHEMA
Return a single JSON object with the following structure:
{
  "valid": boolean,
  "errors": [
    {
      "field": string,
      "issue": "missing_required" | "type_mismatch" | "undocumented_field" | "backward_compatibility_break",
      "expected": string | null,
      "actual": string | null,
      "message": string
    }
  ]
}

## EXAMPLES
Input Error Body: {"error": "Not Found"}
Schema: {"type": "object", "required": ["error", "code"], "properties": {"error": {"type": "string"}, "code": {"type": "integer"}}}
Output: {"valid": false, "errors": [{"field": "code", "issue": "missing_required", "expected": "integer", "actual": null, "message": "Required field 'code' is missing from the error body."}]}

Input Error Body: {"error": "Not Found", "code": 404, "trace_id": "abc-123"}
Schema: {"type": "object", "required": ["error", "code"], "properties": {"error": {"type": "string"}, "code": {"type": "integer"}}}
Output: {"valid": false, "errors": [{"field": "trace_id", "issue": "undocumented_field", "expected": null, "actual": "string", "message": "Field 'trace_id' is present in the error body but not defined in the schema."}]}

## RISK_LEVEL
Medium. This prompt performs structural validation only. It does not assess the semantic correctness of error messages or the appropriateness of HTTP status codes. Human review is required for any backward-compatibility breaks that may affect client parsing.

To adapt this prompt, replace [ERROR_BODY] with the raw JSON string of the error response, [ERROR_SCHEMA] with the JSON Schema definition for that error type, and optionally [PREVIOUS_SCHEMA] with the prior version's schema. In a production harness, you should run this prompt before every API release and on a sample of production traffic. Log every validation failure and route backward-compatibility breaks to a human reviewer before the release is cut. For high-throughput systems, consider batching multiple error bodies into a single prompt call to reduce latency and cost.

This prompt is designed to operate as a validation gate within an API development or documentation pipeline, not as a standalone chat interaction. The typical integration point is a CI/CD check that runs after an OpenAPI spec or error schema document is updated. The prompt receives a candidate error response body and the authoritative schema definition, then returns a structured validation report. The application layer should never trust the raw model output directly—always parse the JSON report, check the valid boolean, and route failures to a review queue or block the merge.

Wiring the prompt into a pipeline requires three components: a schema source of truth (OpenAPI spec, JSON Schema file, or a versioned schema registry), a test corpus of error response bodies (both valid and intentionally invalid), and a post-processing validator. The application should: (1) Load the schema and candidate error body from the current branch or PR. (2) Populate the prompt's [ERROR_BODY] and [SCHEMA_DEFINITION] placeholders. (3) Call the model with response_format set to json_object (or equivalent structured output mode) and a low temperature (0.0–0.1) to maximize deterministic behavior. (4) Parse the returned JSON and verify it contains the expected fields (valid, errors, warnings, schema_version_checked). If parsing fails, retry once with a repair prompt; if it fails again, escalate for human review. (5) For backward compatibility checks, run the prompt against each supported schema version and aggregate results. Flag any field removal or type narrowing as a breaking change requiring a major version bump.

Model choice and cost considerations: Schema validation is a deterministic task that benefits from strong instruction-following and JSON output discipline. GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro are appropriate for high-assurance gates. For cost-sensitive or high-volume pipelines, consider a smaller model (GPT-4o-mini, Claude 3 Haiku) with a stricter post-processing validator that catches obvious hallucinations. Always log the full prompt, response, and validation report to an observability platform for audit trails. What to avoid: Do not use this prompt as the sole gate for security-critical schema enforcement—pair it with a deterministic JSON Schema validator (like ajv or jsonschema) that catches structural violations the model might miss. Do not run this prompt on every commit without caching schema definitions; cache the schema side of the prompt and only re-run when the schema or error body changes.