OpenAPI Specification Validation Against 3.0/3.1 Rules Prompt

API platform engineers and governance teams use this prompt to perform a structural review of an OpenAPI specification against the rules of version 3.0 or 3.1. The job-to-be-done is a fast, human-readable first pass that catches missing required fields, invalid $ref targets, schema keyword misuse, and version-specific constraint violations before the spec reaches a deterministic linter like Spectral. The ideal user is an API designer or platform engineer who has a raw or draft OpenAPI document and needs categorized feedback with fix suggestions, not just a pass/fail result.

This prompt is most effective when you need explanations alongside validation output. For example, if a $ref points to a missing component, the report should identify the broken reference path and suggest the correct component name, rather than just emitting a generic error code. Use this when you are iterating on a spec and want guidance on why something is invalid under the 3.0 or 3.1 structural rules. The prompt expects a complete OpenAPI document as input and produces a structured report with errors, warnings, and fix_suggestions arrays, each entry referencing the exact JSON path and the violated rule.

Do not use this prompt as a replacement for deterministic validation in CI/CD pipelines. It is not suitable for enforcing organization-specific style rules, checking example payload conformance, or validating runtime behavior. After running this prompt, always follow up with a deterministic linter and schema validator to catch any remaining mechanical violations. For high-risk API surfaces, require human review of the categorized report before accepting automated fix suggestions.

This prompt template is designed to be pasted directly into your AI harness or orchestration layer. It instructs the model to act as a strict OpenAPI specification validator, analyzing the provided spec for structural compliance against version 3.0 or 3.1 rules. The prompt is structured to produce a machine-readable JSON report, making it suitable for integration into CI/CD pipelines, pre-commit hooks, or API governance workflows. Before execution, you must replace all square-bracket placeholders with the actual spec content, target version, and any custom organizational rules you want enforced.

textCopy
You are an expert OpenAPI specification validator. Your task is to analyze the provided OpenAPI specification for strict compliance with the structural rules of version [TARGET_VERSION].

# INPUT SPECIFICATION
[OPENAPI_SPEC]

# CUSTOM RULES (Optional)
[CUSTOM_RULES]

# VALIDATION INSTRUCTIONS
1. Parse the specification and confirm its declared OpenAPI version.
2. Validate every object, property, and structure against the [TARGET_VERSION] specification rules. Pay special attention to:
   - Missing required fields (e.g., `info`, `paths`, `openapi`).
   - Invalid `$ref` targets and circular references.
   - Incorrect data types and format values.
   - Schema keyword misuse (e.g., `nullable` in 3.1, `example` vs `examples`).
   - Security scheme and scope definition errors.
   - Parameter and request body structural violations.
   - Response and header object schema errors.
3. Apply any provided [CUSTOM_RULES] as additional checks.
4. Categorize every finding as either `error` (spec is invalid) or `warning` (best practice violation or deprecation).
5. For each finding, provide the exact JSON path, a clear description of the problem, the relevant spec rule reference, and a suggested fix.

# OUTPUT FORMAT
Return a single JSON object with the following structure. Do not include any text outside the JSON object.
{
  "spec_version_detected": "string",
  "target_version": "[TARGET_VERSION]",
  "summary": {
    "total_errors": number,
    "total_warnings": number,
    "is_valid": boolean
  },
  "findings": [
    {
      "severity": "error | warning",
      "path": "$.paths./users.get.responses.200",
      "rule_reference": "OpenAPI 3.1 Section 4.8.9",
      "description": "string",
      "suggested_fix": "string"
    }
  ]
}

To adapt this template, replace [TARGET_VERSION] with either 3.0.3 or 3.1.0 to control which rule set the model applies. The [OPENAPI_SPEC] placeholder should be replaced with the full YAML or JSON string of your specification. The [CUSTOM_RULES] placeholder is optional; you can inject organizational standards like 'All paths must use kebab-case' or 'Every operation must have a 429 response for rate limiting.' If you have no custom rules, remove that section or replace it with 'None.' For high-stakes validation in CI/CD, always pair this prompt with a deterministic linter like Spectral to catch any model hallucinations in the rule reference field.

This prompt is designed to operate as a deterministic linting and review step inside a broader API governance pipeline. It should not be the only validation gate. Instead, wire it after structural parsing (e.g., YAML/JSON syntax checks) and before Spectral or custom lint rules. The model receives a raw OpenAPI 3.0 or 3.1 spec string and returns a structured JSON report of categorized errors, warnings, and fix suggestions. The application layer is responsible for extracting that JSON, validating its schema, and deciding which findings block a merge or deploy.

Integration pattern: Wrap the prompt in a function that accepts [OPENAPI_SPEC_STRING] and [OPENAPI_VERSION] (either 3.0.x or 3.1.x). Set [CONSTRAINTS] to enforce the output schema and limit the report to structural rule violations only—no stylistic opinions unless explicitly requested. On the model side, use a low-temperature setting (0.0–0.1) and request JSON output with a defined schema. On the application side, parse the response and validate it against a JSON Schema that expects errors and warnings arrays, each containing path, rule_id, message, and suggestion fields. If the model output fails schema validation, retry once with a repair prompt that includes the raw response and the schema violation details. After two failures, log the raw output and escalate for human review.

Tool use and RAG considerations: For OpenAPI 3.0 vs 3.1 rule differences, embed the relevant specification excerpts directly in [CONTEXT] rather than relying on the model's training data. Include the exact rules for $ref sibling handling (allowed in 3.1, forbidden in 3.0), exclusiveMinimum/exclusiveMaximum type changes, nullable deprecation, and path-level summary/description requirements. If your organization has additional internal rules (e.g., required x- extensions, naming conventions), add those as explicit constraints. Do not use RAG for the spec rules themselves—they are small enough to inline. For large specs exceeding context windows, chunk by path item or schema component and run validation per chunk, then merge results in the application layer.

Failure modes to instrument: Watch for (1) the model hallucinating rule violations that don't exist in the spec, (2) missing real violations because the spec section wasn't in the model's attention window, (3) producing valid JSON that doesn't match the expected output schema, and (4) timing out on very large specs. Log every validation run with the spec version, spec size in bytes, number of findings, and whether the output passed schema validation. For high-risk API surfaces (auth endpoints, payment paths, PII-carrying schemas), require a human to confirm any error marked as severity: critical before the spec is published. This prompt is a fast first pass, not a replacement for deterministic schema validation or security review.