Unifying OpenAPI & AsyncAPI : Designing JSON Schemas+Examples

Unifying OpenAPI and AsyncAPI: Designing JSON Schemas and Examples for Maximum Reuse

In today’s API-driven world, organizations are increasingly adopting both synchronous and asynchronous communication patterns to build scalable and responsive applications. However, managing these APIs often leads to duplicated efforts, especially when defining API specifications separately for RESTful (OpenAPI) and event-driven (AsyncAPI) architectures. This article dives deep into the challenges and best practices of unifying OpenAPI and AsyncAPI specifications by designing reusable JSON schemas and examples, based on insights shared by experts in the API community.

We will explore how to avoid duplication, maintain consistency, and streamline the API lifecycle—from design to implementation and evolution—while providing developers with tools to ensure conformance and sandbox testing. Along the way, practical examples and demonstrations will illustrate how to leverage shared schemas to accelerate development and improve API quality.

Understanding the Scenario: Combining Synchronous and Asynchronous APIs

Let’s begin with a relatable, real-world example that encapsulates the integration between synchronous and asynchronous APIs. Imagine an order processing system where a user places an order through an order application. The order request is sent synchronously to an Order Backend-For-Frontend (BFF) service, which validates the request, persists the data in a database, and then publishes a message to a “new orders” topic for asynchronous processing.

Once the message is published, the Order BFF responds to the order application with a 202 (Accepted) status and an order ID. This ID enables the application to track the order status later. On the asynchronous side, an Order Service subscribes to the “new orders” topic, processes the order, and periodically publishes status updates on relevant topics. The Order BFF subscribes to these topics to update its database with the latest order state, ensuring that when the user queries the order status, the response reflects the current state.

This scenario illustrates the coexistence and interaction of synchronous REST APIs and asynchronous event-driven APIs, highlighting the need for unified and consistent API specifications.

The Challenge: Duplication in OpenAPI and AsyncAPI Specifications

Typically, synchronous APIs are defined using the OpenAPI specification, capturing endpoints, HTTP methods, request and response schemas, and more. Asynchronous APIs leverage the AsyncAPI specification to describe message channels, message payloads, and operations like sending or receiving messages over protocols such as Kafka, MQTT, or Google Pub/Sub.

Despite their differences, these specifications often share common elements such as JSON schemas for data models and example payloads. However, a common pitfall is the duplication of schemas and examples across OpenAPI and AsyncAPI documents, a pattern known as the WET (Write Everything Twice) approach.

Duplication increases the risk of specification drift, where changes in one spec are not reflected in the other, leading to inconsistencies, confusion, and maintenance overhead. As APIs evolve, this problem compounds, making it harder to keep documentation and implementations aligned.

Applying the DRY Principle: Extracting Common Schemas

To address duplication, the best practice is to apply the DRY (Don’t Repeat Yourself) principle by extracting common components into shared JSON schema files. Both OpenAPI and AsyncAPI specifications can reference these shared schemas, ensuring a single source of truth for data models.

For example, in the order processing scenario, the schemas defining a “NewOrder” and an “Order” are extracted into a common JSON schema file. The OpenAPI spec references this file in its components.schemas section, and the AsyncAPI spec does the same in its components.schemas. This approach effectively eliminates redundancy and guarantees consistency.

This strategy not only prevents drift but also simplifies schema management, making it easier to update and extend APIs without worrying about breaking changes in multiple places.

Beyond Schemas: Reusing Examples and Other Components

While schema reuse is critical, duplication issues extend beyond schemas. Examples, parameters, and other reusable components are equally important to unify across specifications.

Examples play a vital role in API documentation and developer education—often more so than the formal schema definitions. If examples are out of sync, they can mislead developers, causing implementation errors or misunderstandings about the API’s behavior.

Therefore, sharing example payloads between OpenAPI and AsyncAPI specifications ensures that users receive consistent and accurate information, regardless of the communication paradigm.

Comparing OpenAPI and AsyncAPI Specifications

To understand what can be reused, it’s helpful to compare the structural components of OpenAPI and AsyncAPI specifications:

• Information Section: Both have metadata about the API.
• Server and Security: These sections are usually protocol-specific and less reusable.
• Paths vs Channels: OpenAPI uses paths to define REST endpoints, while AsyncAPI uses channels for message topics or queues.
• Operations: OpenAPI defines HTTP methods like GET, POST; AsyncAPI defines actions like send and receive.
• Request/Response vs Headers/Payload: Both define message content, often via schemas.
• Components: Includes schemas, examples, parameters, and other reusable definitions.

Among these, the components section offers the most promising opportunities for reuse, especially schemas, examples, and parameters, as they are based on JSON schema or compatible formats.

Designing APIs for Maximum Reuse and Consistency

The key to unifying OpenAPI and AsyncAPI lies in designing specifications in a way that encourages reuse and reduces duplication by design. Here are the core principles to follow:

1. Standardization: Consistent naming conventions, casing (camelCase, snake_case), pluralization, and formatting across API specs improve predictability and developer experience.
2. DRY Approach: Extract common schemas and examples into shared files, referenced by both OpenAPI and AsyncAPI specs.
3. Comprehensive Examples: Provide rich, accurate examples for all API operations to aid understanding and reduce implementation errors.
4. Validation and Consistency: Validate schemas and examples to avoid contradictions, such as mismatched formats or inconsistent regex patterns.
5. Specificity: Define data types and formats explicitly (e.g., UUID, email) to enable tooling support like code generation and validation.

Tools to Enforce Best Practices and Speed Up Development

To implement these principles effectively, leveraging automation and validation tools is critical. Two popular tools for standardizing and validating API specifications are:

• Spectral: A flexible JSON/YAML linter that enforces style guides and best practices on OpenAPI and AsyncAPI specs.
• Vacuum: Another tool for validating and standardizing API specifications to maintain quality and consistency.

Additionally, Specmatic offers powerful capabilities for contract testing, mocking, and conformance verification, enabling teams to:

• Run API specifications as executable tests to verify implementation against the spec.
• Generate virtualized or mock servers that simulate API behavior for consumer testing.
• Validate examples against the schema to ensure accuracy and consistency.
• Perform backward compatibility checks to support API evolution and versioning.

Accelerating API Lifecycle: From Design to Implementation and Evolution

The API lifecycle can be broadly divided into four stages:

• Discovery: Understanding user needs, defining acceptance criteria, and setting success metrics for the API.
• Design: Creating API specifications with focus on developer experience, security, domain requirements, and regulatory compliance.
• Implementation: Writing code, deploying services, and making APIs available to users.
• Evolution: Enhancing APIs based on user feedback, ensuring backward compatibility, and managing versioning.

The design and implementation phases are crucial for time-to-market and quality. By unifying OpenAPI and AsyncAPI specifications with shared schemas and examples, teams can avoid redundant work and speed up delivery.

During implementation, Specmatic allows providers to run conformance verification tests against the API specification, catching deviations early. Consumers benefit from sandbox environments that simulate real API behavior, enabling independent development and testing.

This approach fosters a robust feedback loop, similar to test-driven development, but driven entirely by the API specification itself.

Live Demo Insights: Practical Application of Schema Reuse and Contract Testing

In a demonstration of these concepts, a mock server was started using Specmatic based on the OpenAPI specification that references a common JSON schema file. The Swagger UI was used to interact with the mock API, showcasing the importance of examples for developers to understand and test API behavior.

On the provider side, running Specmatic tests against the mock server produced an API coverage report detailing which operations were tested successfully, providing concrete feedback on conformance.

Similarly, for the asynchronous API, the AsyncAPI specification also referenced the shared schema. Specmatic virtualized this API using Kafka as the messaging protocol, and an observability dashboard (CAF drop) was used to monitor messages in real-time.

Contract tests validated the request-reply pattern, sending messages to topics and verifying responses, again ensuring strict adherence to the shared schema.

This demo highlighted how a unified schema and contract testing framework can seamlessly support both synchronous and asynchronous APIs, improving developer experience and reducing errors.

Evolution Phase: Managing Backward Compatibility and Versioning

Beyond implementation, API evolution requires careful management of backward compatibility and versioning. Specmatic supports this by enabling:

• Running newer API versions as mocks while testing older versions against them to detect breaking changes.
• Automated backward compatibility checks to inform versioning decisions.

This capability ensures that as APIs grow and change, existing consumers are not adversely impacted, and developers have clear guidance on integration.

Summary and Best Practices for Unifying OpenAPI and AsyncAPI

To recap the key takeaways:

• Standardize your API design to maintain consistency and predictability.
• Don’t Repeat Yourself (DRY): Extract shared schemas and examples into common files to avoid duplication.
• Provide rich examples to educate and guide API consumers effectively.
• Validate for consistency and specificity to ensure your API specs are accurate and tooling-friendly.
• Leverage tools like Spectral, Vacuum, and Specmatic to automate standardization, mocking, testing, and verification.
• Support the full API lifecycle with conformance checks, sandbox environments, and backward compatibility testing.

By following these principles, organizations can unify their OpenAPI and AsyncAPI efforts, accelerating development, reducing errors, and delivering robust APIs that serve both synchronous and asynchronous needs.

Looking Forward: Expanding Reuse into API Workflows

While this article focused on schema and example reuse between OpenAPI and AsyncAPI, there’s an exciting frontier ahead: composing independent operations into workflows. The emerging Arazo specification aims to define API workflows, enabling even greater reuse and orchestration of APIs. This promises to further streamline API design and implementation across complex distributed systems.

Stay tuned to the API community’s innovations and explore how unifying API specifications continues to evolve.

Frequently Asked Questions (FAQ)

What is the main benefit of unifying OpenAPI and AsyncAPI specifications?

The main benefit is eliminating duplication of schemas and examples, which reduces inconsistencies, simplifies maintenance, and speeds up API development by having a single source of truth for shared components.

How can I share schemas between OpenAPI and AsyncAPI?

You can extract common JSON schemas into separate files and reference them in both OpenAPI and AsyncAPI specifications using JSON Reference ($ref). This allows both specs to use the same definitions without duplication.

Why are examples important in API specifications?

Examples help developers understand how to use the API correctly. They serve as practical guides beyond formal schema definitions and can reduce implementation errors when accurate and consistent.

What tools can help maintain consistency in API specifications?

Tools like Spectral and Vacuum can lint and enforce style guides on API specs. Specmatic helps with contract testing, mocking, and conformance verification to ensure implementations align with specifications.

How does Specmatic improve API provider and consumer experience?

Specmatic provides conformance verification tests for API providers to catch deviations early and sandbox environments for consumers to independently develop and test against a realistic API mock, improving feedback loops and reducing dependencies.

Can this approach support API versioning and evolution?

Yes, Specmatic supports backward compatibility checks and testing newer API versions as mocks against older tests, helping teams manage breaking changes and decide on versioning strategies effectively.