AsyncAPI Specification Review Prompt

This prompt is designed for API designers and platform engineers who need to catch contract defects early in the development cycle. It acts as a design-time gate, analyzing an AsyncAPI specification for completeness and correctness across channel definitions, message schemas, security schemes, and protocol bindings. The primary job-to-be-done is accelerating the review cycle by producing a categorized findings report that flags issues like missing error responses, undocumented headers, and binding gaps—problems that would otherwise surface as costly production integration failures. The ideal user has a draft AsyncAPI document and needs a consistent, automated baseline review before requesting manual architecture or peer review.

You should use this prompt when you have a complete or near-complete AsyncAPI specification in JSON or YAML format and want to identify structural gaps, missing required fields, or deviations from best practices. It is particularly effective as a pre-commit or pre-review gate in a CI/CD pipeline, where it can block merges that introduce regressions in contract completeness. The prompt requires the full specification text as input, along with optional context about the intended protocol (e.g., Kafka, MQTT, HTTP) and any organizational standards that should be enforced. The output is a structured findings report that categorizes issues by severity and component, making it actionable for the specification author.

Do not use this prompt as a replacement for manual architecture review, security threat modeling, or runtime behavior validation. It will not catch logical errors in message flow design, performance bottlenecks, or subtle semantic mismatches between producer intent and consumer expectation. It is also not suitable for reviewing specifications that are intentionally incomplete early drafts, as it will generate noise from missing sections that are not yet scoped. After running this prompt, you should review the findings, dismiss false positives, and escalate critical issues to a human reviewer. For high-risk systems, always pair this automated review with a manual approval step before publishing the specification to a public or partner-facing registry.

This prompt template is designed to be pasted directly into your AI workflow. It instructs the model to act as an API design reviewer, systematically evaluating an AsyncAPI specification against a set of defined criteria. The template uses square-bracket placeholders for all variable inputs, such as the specification itself, the desired output format, and any specific constraints or risk levels. This ensures the prompt is reusable across different specifications and review contexts without modification to its core instructions.

markdownCopy
You are an expert API architect reviewing an AsyncAPI specification for correctness, completeness, and consistency. Your review must be structured, evidence-based, and practical.

## Input Specification
[ASYNCAPI_SPECIFICATION]

## Review Criteria
Evaluate the specification against the following dimensions. For each finding, cite the specific line or object path from the specification.

1.  **Channel Definitions:** Verify that all channels are clearly named, have a defined `description`, and include a `publish` or `subscribe` operation. Flag any channels that are ambiguous or missing a description.
2.  **Message Schemas:** For every message, check that the `payload` references a defined schema in the `components.messages` section. Ensure schemas include `type`, `properties`, and `required` fields where appropriate. Flag any inline schemas that should be extracted as reusable components.
3.  **Security Schemes:** Confirm that all security requirements in `servers` are defined in `components.securitySchemes`. Check that the scheme `type` (e.g., `userPassword`, `apiKey`) is valid and includes necessary `description` and `bearerFormat` or `in` fields.
4.  **Binding Completeness:** Identify any protocol-specific bindings (e.g., `kafka`, `mqtt`, `http`) on servers, channels, or operations. Verify that the binding objects contain the minimum required fields for that protocol. Flag missing bindings where they are expected.
5.  **Error Handling:** Check for the presence of error responses or error message definitions. Flag any operation that lacks a defined error response, as this is a critical gap for robust client design.
6.  **Undocumented Headers:** Review message headers. Flag any custom headers that are used but not formally documented in the message's `headers` schema.

## Output Format
[OUTPUT_SCHEMA]

## Constraints
- [CONSTRAINTS]
- If no constraints are provided, default to: "Be concise. Group findings by severity (Critical, Warning, Suggestion)."

## Risk Level
[RISK_LEVEL]

## Review
Proceed with the review based on the criteria and constraints above.

To adapt this template, replace the placeholders with your specific context. For [ASYNCAPI_SPECIFICATION], paste the full YAML or JSON document. For [OUTPUT_SCHEMA], you can request a structured format like a JSON array of findings or a markdown report. The [CONSTRAINTS] placeholder allows you to add project-specific rules, such as naming conventions or required extensions. The [RISK_LEVEL] input (e.g., high, medium, low) can be used to adjust the strictness of the review. After running the prompt, always validate the output against your expected schema and have a human architect review critical findings before accepting changes to the specification.

This prompt is designed to be called programmatically, not just used in a chat interface. The primary integration point is a CI pipeline or a developer CLI tool that runs on every pull request touching an asyncapi.yaml or asyncapi.json file. The harness should read the specification file, inject its contents into the [ASYNCAPI_SPEC] placeholder, and pass the full prompt to the model. Because the prompt asks the model to produce a structured review with specific sections (channel definitions, message schemas, security schemes, bindings), the output must be parsed and validated before it is surfaced to the developer.

Validation and retries: After receiving the model response, the harness must validate that the output contains all required review sections. A simple JSON schema or a set of regex checks can confirm the presence of headings like ## Channel Review, ## Message Schema Review, ## Security Scheme Review, and ## Binding Completeness Review. If any required section is missing, the harness should retry the prompt once with an explicit instruction appended: Your previous response was missing the [MISSING_SECTION] section. Please regenerate the full review including all required sections. If the retry also fails, the harness should log the failure and surface a partial review with a clear warning that automated analysis was incomplete.

Model choice and tool use: This is a zero-shot analysis task that benefits from a model with strong reasoning and structured output capabilities. GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro are appropriate defaults. The prompt does not require tool calls or RAG because the entire specification document is provided inline. However, for large specifications exceeding the model's context window, the harness should implement a pre-processing step that extracts and summarizes the most critical sections (channels, schemas, security) before passing them to the prompt. The harness should log the token count of the specification and warn if it exceeds 80% of the model's context limit.

Human review and approval gates: This prompt produces a review, not a final decision. The output should be posted as a comment on the pull request or surfaced in a review dashboard, never auto-merged. For high-risk specifications—those defining production event flows, PII-carrying payloads, or external-facing APIs—the harness should require a human reviewer to explicitly approve the review before the PR can be merged. The harness can enforce this by setting a CI status check that only passes when a designated reviewer comments /approve-asyncapi-review on the PR.

Logging and observability: Every invocation should log the specification file path, the model used, the token count, the validation result, and whether a retry was required. If the model flags a critical issue (e.g., missing security scheme, undocumented error responses), the harness should emit a structured event that can be routed to the team's monitoring or alerting system. This turns the prompt from a one-off review into an observable quality gate that improves over time as the team tunes the eval criteria and failure thresholds.