Data modeling library
for OpenAPI and AsyncAPI
Version: v1.1.5
Clone or fork on GitHub

What is this library?

The Apicurio Data Models library is a Java and Typescript compatible library that provides reading, writing, analysis, modification, and validation of OpenAPI and AsyncAPI documents. Use this library if you need to support either OpenAPI or AsyncAPI specifications in your own projects.

Key Features

Parsing into a formal model
OpenAPI and AsyncAPI content (typically JSON or YAML content) can be parsed into a formal, structured (tree-like) data model, much like XML or other structured content.
Visitor + Traverser patterns
Full support for the Visitor design pattern, for both a single Node in the model and also a traversal (up or down) of the full (or partial) document.
Validation of the model
Validate all, or only part, of the data model against all of the rules defined in the OpenAPI/AsyncAPI specifications.
Supports both Java and Typescript
Use this library in your Java, node.js, or browser based applications! It works the same no matter how you use it.
Convert OpenAPI 2.0 to OpenAPI 3.0
Includes a built-in transformer for easily converting older "Swagger" documents into the newer OpenAPI 3 format.
Robust $ref support
Provide your own $ref resolver so that the library can properly analyze/validate documents with external references. Also included is a built-in "dereferencer" which can transform a document with external references into one without any (by internalizing all of the refs)!

Java and Typescript? What?!

The Apicurio Data Models library is written in Java and then transpiled to Typescript using the very nice JSweet Utility. This results in the library being released both as a standard Maven library (and released into Maven Central) as well as a javascript module released into npmjs.com.

The JSweet tool does a great job with the transpilation, allowing us to have a very thin "compatibility" layer (check out the io.apicurio.datamodels.compat Java package) to isolate functionality that cannot be transpiled from Java to Typescript. In addition, we have a very comprehensive set of unit tests that are designed to run in both the Java and Typescript builds. This is critical as it allows us to be very confident that the library behaves the same in both runtime environments.

The motivation for writing this library in this way is because the Apicurio Studio project requires this data modeling functionality in both the Java back-end layer and the browser front-end layer. As a result, this library is actually heavily used in both forms and is not just a novelty.