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:
![](https://portle.io/wp-content/uploads/2024/06/Screenshot-2024-06-22-at-09.51.20-1024x621.png)
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:
![](https://portle.io/wp-content/uploads/2024/06/Screenshot-2024-06-20-at-11.02.22.png)
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
:
![](https://portle.io/wp-content/uploads/2024/06/Screenshot-2024-06-20-at-10.30.18-1.png)
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 theGET
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