What is the Apicurio Data Models 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.

Apicurio Data Models Key Features

Parsing into a formal model

OpenAPI and AsyncAPI content, typically JSON or YAML, 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 a single node in the model, and also an up or down traversal of the full or partial document.

Validation of the model

Validate all or part of the data model against all of the rules defined in the OpenAPI or 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 or validate documents with external references. Also includes 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 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 because it enables 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 heavily used in both forms and is not just a novelty.