OpenAPI Example vs Schema Conformance Check Prompt

Use this prompt when you are a documentation engineer, API designer, or platform reviewer who needs to verify that every example payload in an OpenAPI specification actually conforms to its declared schema. The job-to-be-done is automated conformance auditing: you have a spec that passes structural validation but you suspect—or need to prove—that the example objects inside request bodies, responses, and component schemas contain type errors, missing required fields, or enum violations that will break client code, mock servers, or contract tests. This prompt is ideal when you are preparing a spec for publication, running a pre-release documentation QA pass, or integrating spec validation into a CI pipeline that already checks for structural correctness but lacks semantic example validation.

This prompt is not a replacement for a full OpenAPI structural linter like Spectral or Redocly CLI. Do not use it to check for missing $ref targets, invalid path templating, or spec-version rule compliance—those belong in a separate structural validation step. It is also not designed for generating new examples from scratch; use a dedicated example-generation prompt for that. The prompt works best when you provide a complete, structurally valid OpenAPI document and expect a per-example conformance report. If your spec is large, consider chunking it by path or schema component to stay within context windows and to make the failure report easier to act on. For high-risk APIs where example accuracy is a contractual or security boundary—such as payment, healthcare, or identity APIs—always pair the automated report with a human review step before publication.

Before running this prompt, ensure your OpenAPI document is structurally valid (passes standard OpenAPI 3.0/3.1 validation) and that all $ref pointers resolve correctly. The prompt will flag mismatches but cannot fix broken references. After receiving the conformance report, prioritize fixes for examples that appear in public documentation or client SDK generation paths, as these have the highest blast radius. If the report surfaces systemic issues—such as a pattern of missing required fields across multiple endpoints—consider updating your example-generation workflow or adding a schema-first example authoring step rather than fixing each instance manually. Store the conformance report alongside your spec version so downstream consumers can assess example reliability.

This prompt template performs a structured conformance audit of every example payload in an OpenAPI specification against its corresponding schema definition. It is designed to be dropped into an automated documentation pipeline, a CI check, or a manual review workflow. The template expects the full OpenAPI spec as input and produces a machine-readable conformance report that flags type mismatches, missing required fields, enum violations, and structural inconsistencies at the exact JSON path where they occur.

textCopy
You are an OpenAPI specification auditor. Your task is to check every example payload in the provided OpenAPI specification against its declared schema and produce a conformance report.

[INPUT]

For each example found in the spec (request body examples, response examples, and schema-level examples), perform the following checks:

1. **Type conformance**: Verify that each value matches the declared type (string, integer, number, boolean, array, object). Flag implicit type coercion risks.
2. **Required field presence**: Confirm that all fields listed in the `required` array are present in the example. Flag missing required fields.
3. **Enum constraint**: Verify that any field with an `enum` constraint contains a value from the allowed set. Flag values outside the enum.
4. **Pattern constraint**: Check that string fields with a `pattern` constraint match the regex. Flag non-matching values.
5. **Nested schema conformance**: Recursively check all nested objects and array items against their sub-schemas.
6. **oneOf/anyOf/allOf resolution**: For polymorphic schemas, verify that the example matches at least one variant and identify which variant was matched.
7. **readOnly/writeOnly**: Flag examples that include `readOnly` fields in a request body or `writeOnly` fields in a response body.

[OUTPUT_SCHEMA]

Return a JSON object with this structure:
{
  "spec_title": "string (from info.title)",
  "total_examples_checked": "integer",
  "conformant_examples": "integer",
  "non_conformant_examples": "integer",
  "findings": [
    {
      "severity": "ERROR | WARNING | INFO",
      "location": "string (JSON path to the example, e.g., paths./users.get.responses.200.content.application/json.example)",
      "schema_ref": "string ($ref path or inline schema location)",
      "check_type": "TYPE_MISMATCH | MISSING_REQUIRED | ENUM_VIOLATION | PATTERN_VIOLATION | NESTED_SCHEMA_ERROR | POLYMORPHIC_MISMATCH | READONLY_IN_REQUEST | WRITEONLY_IN_RESPONSE",
      "field_path": "string (JSON path to the violating field within the example)",
      "expected": "string (description of what the schema requires)",
      "actual": "string (description of what the example contains)",
      "suggestion": "string (actionable fix recommendation)"
    }
  ],
  "summary_by_check_type": {
    "TYPE_MISMATCH": "integer",
    "MISSING_REQUIRED": "integer",
    "ENUM_VIOLATION": "integer",
    "PATTERN_VIOLATION": "integer",
    "NESTED_SCHEMA_ERROR": "integer",
    "POLYMORPHIC_MISMATCH": "integer",
    "READONLY_IN_REQUEST": "integer",
    "WRITEONLY_IN_RESPONSE": "integer"
  }
}

[CONSTRAINTS]
- Do not skip any example in the spec. Check request body examples, response examples, and schema-level examples.
- If an example references an external value via $ref, note it as an INFO finding and skip deep validation.
- If a schema uses `additionalProperties: false`, flag any example fields not declared in `properties`.
- If a schema has no example, do not fabricate one. Only audit existing examples.
- For arrays, check every item in the example array against the `items` schema.
- Report the exact JSON path for every finding so the result is machine-actionable.
- If the spec is invalid or unparseable, return a single finding with severity ERROR and describe the parse failure.

To adapt this template, replace [INPUT] with the raw OpenAPI YAML or JSON content. If your pipeline already parses the spec into a structured object, you can replace [INPUT] with a pre-parsed representation and adjust the instructions accordingly. The [OUTPUT_SCHEMA] block defines the exact JSON structure the model must return; keep this strict to enable downstream automated remediation. The [CONSTRAINTS] block prevents common failure modes like skipping nested examples or fabricating data. For high-stakes API surfaces where example accuracy directly impacts developer integration success, wire the output into a CI check that blocks deployment on ERROR-severity findings and requires human review for WARNING-level findings before merging spec changes.

This prompt is designed to be called programmatically, not used as a one-off chat interaction. The typical integration point is a CI check that runs after an OpenAPI spec is updated, or a pre-release documentation audit. The harness should extract each request body and response example from the spec, pair it with its resolved schema (following all $ref pointers), and invoke the prompt once per example. Batching multiple examples into a single prompt call is acceptable for latency reduction, but keep batches small (3–5 examples) to avoid the model losing precision on individual mismatches. The prompt expects a fully resolved schema object and a single example object as its two primary inputs.

Validation and retry logic: Parse the model's output as JSON and validate it against a strict schema: { example_path: string, conformance: "conformant"|"non-conformant", issues: [{ location: string, expected: string, actual: string, severity: "error"|"warning" }] }. If the output fails to parse or doesn't match this schema, retry once with a stronger constraint instruction appended to the prompt. If the retry also fails, log the raw output and flag the example for human review. Model choice: Use a model with strong JSON-following behavior (GPT-4o, Claude 3.5 Sonnet, or equivalent). Avoid smaller models for this task—schema conformance checking requires precise type comparison and enum validation that smaller models frequently hallucinate. Logging: Record every invocation with the spec version, example path, schema hash, model output, and final conformance verdict. This audit trail is essential when a false negative blocks a release.

Integration with governance tools: Wire the harness output into your existing linting pipeline (Spectral, vacuum, or custom validators). Treat the prompt's non-conformant verdict as a lint error with the location field mapped to a JSON Pointer for the offending example. What to avoid: Do not use this prompt as a replacement for structural schema validation—a standard OpenAPI validator should catch missing $ref targets and invalid schema keywords before this prompt runs. This prompt is specifically for semantic conformance: does the example value actually match what the schema declares? Also avoid running this on every commit if your spec is large; gate it on changes to examples or example fields, or run it only on the release branch.