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:

Key	Description
name*	This is a unique identifier for a source description.
url*	A url to a referred OpenAPI/Arazzo spec. It is allowed to be either relative or absolute.
type	“openapi” or “arazzo” (Note: This field is not marked required within the Arazzo Definition which leads me to conclude that if this field is not set, it should be inferred based on the referenced spec in the url)

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