OpenAPI Error Schema Standardization Prompt Template

Platform teams and API designers use this prompt to enforce a single, consistent error response structure across every endpoint in an OpenAPI specification. The goal is to produce error objects that include machine-readable error codes, human-readable messages, and trace IDs, making debugging and client-side error handling predictable. This prompt is designed for spec-first workflows where downstream tools, SDK generators, and API gateways consume the OpenAPI document directly. It assumes you already have an OpenAPI spec with paths and operations defined, and you need to audit or inject standardized error schemas into every response definition.

Use this prompt when you need to retrofit error consistency onto an existing spec or when you are building a new spec and want to prevent drift from the start. The prompt works best when you provide a target error schema—such as an object with error_code, message, trace_id, and optional details array—and a list of operations to process. It is not a general-purpose spec generator; it focuses narrowly on error response standardization. If your spec lacks operation definitions or uses an unrecognized structure, the prompt will produce unreliable results. For brand-new specs, start with the OpenAPI Specification Scaffold prompt instead.

Do not use this prompt when you need to design the error taxonomy itself—that is a product and domain modeling decision that requires human judgment about error categories, retryability, and client impact. This prompt standardizes the shape of errors, not the business logic of which errors exist. Also avoid this prompt for real-time gateway enforcement; it produces a spec artifact, not runtime validation. After running the prompt, always validate the output with an OpenAPI linter and review the injected schemas to ensure they match your organization's error contract. For high-risk APIs where error codes trigger automated remediation, add a human review step before publishing the spec.

This prompt template is the core instruction you'll send to a large language model to audit and standardize error response schemas across an entire OpenAPI specification. It is designed to be copied directly into your AI harness, with placeholders for the specific inputs your workflow requires. The template instructs the model to act as an API governance engineer, analyzing every defined operation for error response consistency, machine-readable error codes, and the presence of trace identifiers. Use this as the foundation for a linting and standardization pass before publishing or updating your API contract.

markdownCopy
You are an API governance engineer responsible for standardizing error response schemas across an entire OpenAPI specification. Your task is to analyze the provided [OPENAPI_SPEC] and produce a standardized, consistent error schema for every endpoint.

## Input
- OpenAPI Specification: [OPENAPI_SPEC]
- Target Error Schema Standard: [ERROR_SCHEMA_STANDARD] (e.g., RFC 9457 Problem Details, JSON:API errors, or a custom schema defined below)
- Custom Error Schema (if applicable): [CUSTOM_ERROR_SCHEMA]
- Required Fields: [REQUIRED_FIELDS] (e.g., `code`, `message`, `trace_id`)
- Optional Fields: [OPTIONAL_FIELDS] (e.g., `details`, `links`)
- Operations to Process: [OPERATIONS] (e.g., 'all', or a list of `operationId` values)

## Task
1.  **Audit:** For each operation in [OPERATIONS], identify every response with a 4XX or 5XX status code. Note if the response has a `content` schema defined. If it does, check if it conforms to the [ERROR_SCHEMA_STANDARD] and contains all [REQUIRED_FIELDS].
2.  **Standardize:** For any non-conforming or missing error response, generate a new response object that adheres to the standard. Use the `operationId` and the HTTP status code to generate a meaningful, human-readable `message` and a unique, machine-readable `code` (e.g., `INVALID_PARAMETER`, `RESOURCE_NOT_FOUND`).
3.  **Add Trace ID:** Ensure every generated error response schema includes a `trace_id` field (UUID format) as specified in [REQUIRED_FIELDS].
4.  **Generate Linting Report:** Create a structured report detailing every change made or recommended.

## Output Schema
Return your response as a single JSON object with the following structure:
{
  "standardized_spec": { ... }, // The complete, modified OpenAPI specification object.
  "linting_report": {
    "summary": {
      "total_operations_processed": <int>,
      "errors_standardized": <int>,
      "errors_added": <int>,
      "errors_already_conforming": <int>
    },
    "changes": [
      {
        "path": "<string>",
        "method": "<string>",
        "status_code": "<string>",
        "action": "added" | "modified",
        "reason": "<string>",
        "new_schema": { ... }
      }
    ]
  }
}

## Constraints
- Do not modify any response with a 2XX or 3XX status code.
- Preserve all existing descriptions, summaries, parameters, and request bodies.
- Ensure all generated `code` values are uppercase snake_case.
- The `trace_id` field must be a string with `format: uuid`.
- If [OPERATIONS] is 'all', process every path and method in the spec.

To adapt this template, replace the square-bracket placeholders with your concrete data. For a simple use case, you might provide the raw OpenAPI YAML/JSON string for [OPENAPI_SPEC], set [ERROR_SCHEMA_STANDARD] to 'RFC 9457', and define [REQUIRED_FIELDS] as ["type", "title", "status", "detail", "trace_id"]. For a custom internal standard, provide the schema object directly in [CUSTOM_ERROR_SCHEMA]. The [OPERATIONS] placeholder allows you to scope the work to a subset of your API, which is useful for incremental adoption. After running the prompt, you must validate the standardized_spec against the OpenAPI 3.x specification using a tool like swagger-parser or spectral to ensure the model did not introduce structural errors. For high-risk APIs, a human reviewer should sign off on the linting_report before the new spec is merged.

This prompt is designed to run as a batch governance step, not a real-time request path. Feed it one or more OpenAPI operation objects (paths, methods, and existing responses) plus your organization's error schema standard. The model returns a revised OpenAPI fragment with standardized error response objects. The harness should extract the model's output, merge it back into the spec, and validate the result before accepting the change. Do not run this prompt on every API call—it belongs in a CI check, a pre-merge lint gate, or a periodic spec audit job.

Integration pattern: Store your error schema standard as a reusable [ERROR_SCHEMA_STANDARD] variable—either a JSON Schema object or a plain-text description of required fields like code, message, trace_id, and details. For each endpoint in the spec, extract the operation object and pass it as [OPENAPI_OPERATION]. The model should return only the modified operation object with standardized error responses. Validation step: After receiving the output, run a structural check: (1) every operation must have at least a 4XX and 5XX response; (2) every error response must conform to your standard schema; (3) no existing non-error responses were altered. Use an OpenAPI parser to validate the merged spec. If validation fails, feed the errors back into the prompt as [VALIDATION_ERRORS] and request a targeted fix—limit retries to 2 attempts before flagging for human review.

Model choice and tool use: This task requires strong schema-following behavior. Use a model with reliable JSON mode or structured output support (e.g., GPT-4o with response_format, Claude 3.5 Sonnet with tool-use-shaped output). Do not use tool-calling for the error schema itself—the output is a modified OpenAPI fragment, not a function call. Logging: Record the input operation ID, the model version, the output diff, validation results, and whether human approval was required. This audit trail is essential when governance teams ask why a particular error format was applied to a specific endpoint six months later. Human review gate: For APIs in production or regulated contexts, require a human to approve the diff before merging. The harness should generate a side-by-side comparison of the original and standardized error responses and post it to a review queue (PR comment, Slack notification, or governance dashboard).

Failure modes to handle: The model may (a) drop existing non-error responses, (b) apply the wrong HTTP status code for a given error scenario, (c) invent error conditions not present in the original spec, or (d) produce valid OpenAPI that doesn't match your standard's field names. Your harness must catch each of these. Implement a diff safety check: if the model removes any existing response object that isn't an error response, block the change and request a correction. If the model adds new error status codes that weren't in the original operation, flag them for human review—they may be valid improvements, but they shouldn't slip in silently. Next step: After the harness produces a clean, validated spec fragment, merge it into the canonical spec and run your full OpenAPI linting suite (Spectral rules, breaking change detection) before the change reaches production docs or SDK generation.