Request/Response Schema Validation Prompt

Use this prompt when you need to verify that a documented API request or response schema matches the actual behavior of a live endpoint. The primary job-to-be-done is field-by-field accuracy auditing: confirming that every property name, data type, required/optional flag, constraint, and example payload in your documentation reflects what the API truly returns. The ideal user is a doc platform engineer, API technical writer, or developer-tools engineer responsible for maintaining documentation that developers trust. You should have access to a live API endpoint, a valid authentication method, and the documented schema you intend to validate—typically sourced from an OpenAPI specification, a markdown reference page, or a static JSON Schema file.

This prompt is designed for structured, deterministic comparison work. It expects you to provide the documented schema and a representative sample of actual API responses (or a tool that can fetch them). The model will produce a discrepancy report, not a rewritten schema. It will flag type mismatches (e.g., string documented but integer observed), missing fields present in the response but absent from the docs, undocumented fields, incorrect required/optional designations, and example payloads that don't conform to the stated schema. The prompt works best when you supply the schema in a standard format like JSON Schema or OpenAPI Schema Object, and the response payload as a raw JSON object.

Do not use this prompt when you need to author a schema from scratch, design a new API contract, or perform semantic review of field descriptions. It is not a substitute for contract testing in CI/CD, nor does it replace runtime schema validation middleware. Avoid using it for endpoints with highly variable or non-deterministic responses (e.g., those containing timestamps, random IDs, or AI-generated text) unless you first normalize those fields. For high-risk APIs—such as those handling payments, health data, or authentication—always pair the model's output with automated JSON Schema validation and a human review step before publishing documentation changes.

This prompt template is the core instruction set for a schema validation workflow. It is designed to be dropped into an AI harness that supplies the documented schema, a live response payload, and the expected output format. The prompt instructs the model to act as a meticulous API auditor, comparing every field, type, constraint, and example value without making assumptions or skipping optional parameters. Use this template when you have a source of truth for the expected schema—such as an OpenAPI specification, a JSON Schema file, or a manually curated documentation extract—and a sample of the actual API's response body.

markdownCopy
You are an API documentation auditor. Your task is to compare a documented API schema against a live response payload and produce a strict, field-by-field validation report.

## INPUTS
- **Documented Schema:** [DOCUMENTED_SCHEMA]
- **Live Response Payload:** [LIVE_RESPONSE_PAYLOAD]
- **Schema Format:** [SCHEMA_FORMAT] (e.g., OpenAPI 3.0, JSON Schema Draft 7)
- **Endpoint Context:** [ENDPOINT_CONTEXT] (e.g., GET /users/{id})

## CONSTRAINTS
- Compare every field in the documented schema against the live payload.
- Flag fields present in the live payload but missing from the documented schema.
- For each field, check: type, format, required/optional status, nullable status, constraints (min/max, pattern, enum), and example values.
- Do not hallucinate fields. Only report on what is present in the inputs.
- If the documented schema is ambiguous, flag it as a documentation gap rather than assuming intent.
- Classify each finding by severity: `error` (breaking contract), `warning` (likely unintentional), or `info` (addition or clarification).

## OUTPUT SCHEMA
Return a single JSON object conforming to this structure:
{
  "endpoint": "string",
  "schema_source": "string",
  "validation_summary": {
    "total_fields_documented": "integer",
    "total_fields_in_payload": "integer",
    "errors_count": "integer",
    "warnings_count": "integer",
    "info_count": "integer"
  },
  "findings": [
    {
      "field_path": "string (e.g., data.attributes.name)",
      "documented_type": "string | null",
      "actual_type": "string",
      "documented_constraints": "object | null",
      "actual_value_sample": "string",
      "severity": "error | warning | info",
      "category": "type_mismatch | missing_from_docs | missing_from_payload | constraint_violation | example_invalid | undocumented_field",
      "description": "string explaining the discrepancy",
      "suggested_fix": "string"
    }
  ]
}

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

If [RISK_LEVEL] is `high`, flag any undocumented breaking change as a blocking error and recommend human review before publication.

To adapt this template, replace the square-bracket placeholders with your specific inputs. [DOCUMENTED_SCHEMA] should contain the full schema object, not just a reference. [LIVE_RESPONSE_PAYLOAD] must be a real, unmodified response body captured from the running API. [EXAMPLES] is optional but strongly recommended: provide one or two few-shot examples of correct findings to calibrate the model's severity classification and description style. [RISK_LEVEL] should be set to high for externally-facing, stable, or revenue-critical APIs where a breaking change in documentation could cause customer incidents. For internal or beta APIs, medium or low is acceptable. After copying the template, wire it into a harness that validates the output JSON against the schema defined in the prompt itself—this prevents the model from drifting the report structure over repeated runs.

This prompt is designed to be the reasoning core of an automated documentation testing harness, not a standalone chat interaction. The primary integration pattern is a CI/CD job that triggers on changes to either the API specification (e.g., an OpenAPI file) or the human-authored documentation. The harness fetches the live API's response for a given endpoint, feeds both the documented schema and the live response body into the prompt, and parses the structured comparison report. The model's output should be treated as a sophisticated diff engine that understands semantic equivalence, not just structural identity.

To wire this up, build a script that: (1) parses the target endpoint and its documented schema from your source of truth; (2) makes a live API call with appropriate authentication and a representative payload; (3) constructs the prompt by injecting the documented schema into [DOCUMENTED_SCHEMA] and the live JSON response into [LIVE_RESPONSE]; and (4) calls the LLM with response_format set to a strict JSON Schema that matches the expected SchemaComparisonReport output. Implement a retry wrapper with a maximum of two attempts. If the first response fails JSON Schema validation, feed the raw output and the validation error back into the model with a repair instruction before retrying. If the second attempt also fails, escalate the check to a NEEDS_HUMAN_REVIEW status and log the raw output for a developer to triage.

The harness must include a severity classifier that gates CI pass/fail. Parse the model's findings array and block the pipeline if any finding has a severity of error. Findings with a severity of warning should post a non-blocking comment on the pull request. To reduce false positives, maintain a small suppression file (e.g., schema-suppressions.yaml) that allows teams to mute known acceptable discrepancies, such as intentionally undocumented internal fields or write-only parameters that don't appear in read responses. Every suppression entry must include a reason and an expiration date to prevent drift. Finally, log every prompt invocation, the raw model response, and the final pass/fail verdict to your observability platform to track accuracy trends and identify endpoints that frequently generate false positives.