The Arazzo Specification is an add-on to the OpenAPI Specification. If you have no idea what Arazzo is, start with this article first: What is the Arazzo Specification?

Introduction

An Arazzo Specification can refer to multiple OpenAPI Specs as well as other Arazzo Specs. Using these references it can do the following:

• Reference endpoints within external OpenAPI Specs

• Reference workflows within itself or external Arazzo Specs

How to reference external specs from within Arazzo?

The Arazzo Specification schema defines a field called sourceDescriptions that can contain multiple Source Description Objects with the following keys: name, url and type.

Here is an illustration of an Arazzo Spec with a Source Description:

Example: Reference OpenAPI Spec from within Arazzo

Assume there exists a service called Weatherly whose APIs you can use to fetch global weather data. The following two YAML files are associated with this service and live within different folders:

• OpenAPI Spec: src/specs/main/weatherly.openapi.yaml

• Arazzo Spec: src/specs/add-ons/weatherly.arazzo.yaml

This diagram illustrates how the OpenAPI Spec can be referenced within the Arazzo Spec:

How does Arazzo reference endpoints within the OpenAPI Spec?

An Arazzo Spec can reference OpenAPI Spec endpoints in Step Objects within the steps field using operationId or operationPath. operationId and operationPath are mutually exclusive i.e. only one if these is needed to reference an endpoint. In case both are added, operationId takes precedence. The following diagram illustrates the use of operationPath:

Let’s break down the operationPath value:

• $sourceDescriptions: A reference to the sourceDescriptions object that contains references to external specs

• $sourceDescriptions.weatherly-apis.url: This resolves to the url of a sourceDescription with name weatherly-apis that points to an external OpenAPI spec.

• $sourceDescriptions.weatherly-apis.url}#/paths/~1getCityTemperature/get: Points to the GET operation of /getCityTemperature endpoint within the external OpenAPI Spec. Please note that in JSON Pointer syntax, ~1 is used to represent a forward slash (/) within a key.

For more information, check out the detailed Arazzo Specification here