{
"$id": "https://spec.openapis.org/arazzo/1.1/schema/2026-04-15",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"description": "The description of Arazzo v1.1.x documents",
"type": "object",
"properties": {
"arazzo": {
"description": "The version number of the Arazzo Specification",
"type": "string",
"pattern": "^1\\.1\\.\\d+(-.+)?$"
},
"$self": {
"type": "string",
"format": "uri-reference",
"$comment": "MUST NOT contain a fragment",
"pattern": "^[^#]*$"
},
"info": {
"$ref": "#/$defs/info"
},
"sourceDescriptions": {
"description": "A list of source descriptions such as Arazzo or OpenAPI",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/source-description-object"
}
},
"workflows": {
"description": "A list of workflows",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/workflow-object"
}
},
"components": {
"$ref": "#/$defs/components-object"
}
},
"required": [
"arazzo",
"info",
"sourceDescriptions",
"workflows"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false,
"$defs": {
"info": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#info-object",
"description": "Provides metadata about the Arazzo description",
"type": "object",
"properties": {
"title": {
"description": "A human readable title of the Arazzo Description",
"type": "string"
},
"summary": {
"description": "A short summary of the Arazzo Description",
"type": "string"
},
"description": {
"description": "A description of the purpose of the workflows defined. CommonMark syntax MAY be used for rich text representation",
"type": "string"
},
"version": {
"description": "The version identifier of the Arazzo document (which is distinct from the Arazzo Specification version)",
"type": "string"
}
},
"required": [
"title",
"version"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"source-description-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#source-description-object",
"description": "Describes a source description (such as an OpenAPI description)\nthat will be referenced by one or more workflows described within\nan Arazzo description",
"type": "object",
"properties": {
"name": {
"description": "A unique name for the source description",
"type": "string",
"pattern": "^[A-Za-z0-9_\\-]+$"
},
"url": {
"description": "A URL to a source description to be used by a workflow",
"type": "string",
"format": "uri-reference"
},
"type": {
"description": "The type of source description",
"enum": [
"arazzo",
"openapi",
"asyncapi"
]
}
},
"required": [
"name",
"url"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"workflow-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#workflow-object",
"description": "Describes the steps to be taken across one or more APIs to achieve an objective",
"type": "object",
"properties": {
"workflowId": {
"description": "Unique string to represent the workflow",
"$anchor": "workflowId",
"type": "string"
},
"summary": {
"description": "A summary of the purpose or objective of the workflow",
"type": "string"
},
"description": {
"description": "A description of the workflow. CommonMark syntax MAY be used for rich text representation",
"type": "string"
},
"inputs": {
"description": "A JSON Schema 2020-12 object representing the input parameters used by this workflow",
"$ref": "#/$defs/schema"
},
"dependsOn": {
"description": "A list of workflows that MUST be completed before this workflow can be processed",
"type": "array",
"uniqueItems": true,
"items": {
"type": "string"
}
},
"steps": {
"description": "An ordered list of steps where each step represents a call to an API operation or to another workflow",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/step-object"
}
},
"successActions": {
"description": "A list of success actions that are applicable for all steps described under this workflow",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/success-action-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
},
"failureActions": {
"description": "A list of failure actions that are applicable for all steps described under this workflow",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/failure-action-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
},
"outputs": {
"description": "A map between a friendly name and a dynamic output value defined using a Runtime Expression or Selector Object. Keys must match the regex: ^[a-zA-Z0-9\\.\\-_]+$\n",
"type": "object",
"patternProperties": {
"^[a-zA-Z0-9\\.\\-_]+$": {
"oneOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/selector-object"
}
]
}
}
},
"parameters": {
"description": "A list of parameters that are applicable for all steps described under this workflow",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/parameter-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
}
},
"required": [
"workflowId",
"steps"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"step-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#step-object'",
"description": "Describes a single workflow step which MAY be a call to an\nAPI operation (OpenAPI Operation Object or AsyncAPI Operation Object or another Workflow Object)",
"oneOf": [
{
"$ref": "#/$defs/openapi-step-object"
},
{
"$ref": "#/$defs/asyncapi-step-object"
},
{
"$ref": "#/$defs/workflow-step-object"
}
]
},
"step-object-base": {
"type": "object",
"properties": {
"stepId": {
"description": "Unique string to represent the step",
"$anchor": "stepId",
"type": "string"
},
"description": {
"description": "A description of the step. CommonMark syntax MAY be used for rich text representation",
"type": "string"
},
"timeout": {
"description": "The duration in milliseconds to wait before timing out the step",
"type": "integer"
},
"dependsOn": {
"description": "Specifies a list of step identifiers that must complete (or be waited for) before the current step can begin execution. `dependsOn` only establishes a prerequisite relationship for the current step and does not trigger execution of the referenced steps. Steps referred by dependsOn SHOULD be non-blocking/async steps. Steps in the current workflow MUST be referenced directly by stepId. Steps in another workflow in the same Arazzo document MUST use $workflows.<workflowId>.steps.<stepId>. Steps in another Arazzo document MUST use $sourceDescriptions.<name>.<workflowId>.steps.<stepId>.",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"oneOf": [
{
"type": "string",
"pattern": "^(?!\\$).+$"
},
{
"type": "string",
"pattern": "^\\$workflows\\.[^.]+\\.steps\\.[^.]+$"
},
{
"type": "string",
"pattern": "^\\$sourceDescriptions\\.[^.]+\\.[^.]+\\.steps\\.[^.]+$"
}
]
}
},
"parameters": {
"description": "A list of parameters that MUST be passed to an operation or workflow as referenced by operationId, operationPath, or workflowId",
"type": "array",
"uniqueItems": true,
"items": true
},
"requestBody": {
"$ref": "#/$defs/request-body-object"
},
"successCriteria": {
"description": "A list of assertions to determine the success of the step",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/criterion-object"
}
},
"onSuccess": {
"description": "An array of success action objects that specify what to do upon step success",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/success-action-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
},
"onFailure": {
"description": "An array of failure action objects that specify what to do upon step failure",
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/failure-action-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
},
"outputs": {
"description": "A map between a friendly name and a dynamic output value defined using a Runtime Expression or Selector Object. Keys must match the regex: ^[a-zA-Z0-9\\.\\-_]+$\n",
"type": "object",
"patternProperties": {
"^[a-zA-Z0-9\\.\\-_]+$": {
"oneOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/selector-object"
}
]
}
}
}
},
"required": [
"stepId"
]
},
"operation-step-parameters": {
"type": "array",
"uniqueItems": true,
"items": {
"oneOf": [
{
"$ref": "#/$defs/reusable-object"
},
{
"$ref": "#/$defs/parameter-object",
"required": [
"in"
]
}
]
}
},
"openapi-step-object": {
"allOf": [
{
"$ref": "#/$defs/step-object-base"
},
{
"type": "object",
"properties": {
"operationId": {
"description": "The name of an existing, resolvable operation, as defined with a unique operationId and existing within one of the sourceDescriptions",
"type": "string"
},
"operationPath": {
"description": "A reference to a Source combined with a JSON Pointer to reference an operation",
"type": "string"
},
"parameters": {
"$ref": "#/$defs/operation-step-parameters"
}
}
},
{
"oneOf": [
{
"required": [
"operationId"
]
},
{
"required": [
"operationPath"
]
}
]
}
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"asyncapi-step-object": {
"allOf": [
{
"$ref": "#/$defs/step-object-base"
},
{
"type": "object",
"properties": {
"operationId": {
"description": "The name of an existing, resolvable operation, as defined with a unique operationId and existing within one of the sourceDescriptions",
"type": "string"
},
"channelPath": {
"description": "A reference to a Source combined with a JSON Pointer to reference an async channel",
"type": "string"
},
"correlationId": {
"description": "ID to correlate async responses with their requests, only specified for async receive steps",
"type": [
"string",
"number",
"boolean",
"object",
"array"
]
},
"action": {
"description": "Specifies the intended operation on the async channel, indicating whether the action is sending data to the channel or receiving data from the channel",
"enum": [
"send",
"receive"
]
},
"parameters": {
"$ref": "#/$defs/operation-step-parameters"
}
},
"required": [
"action"
]
},
{
"if": {
"required": [
"correlationId"
]
},
"then": {
"properties": {
"action": {
"const": "receive"
}
},
"required": [
"action"
]
}
},
{
"oneOf": [
{
"required": [
"operationId"
]
},
{
"required": [
"channelPath"
]
}
]
}
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"workflow-step-object": {
"allOf": [
{
"$ref": "#/$defs/step-object-base"
},
{
"type": "object",
"properties": {
"workflowId": {
"description": "The workflowId referencing an existing workflow within the Arazzo description",
"$ref": "#workflowId"
},
"parameters": {
"items": {
"oneOf": [
{
"$ref": "#/$defs/parameter-object"
},
{
"$ref": "#/$defs/reusable-object"
}
]
}
}
},
"required": [
"workflowId"
]
}
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"request-body-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#request-body-object",
"description": "The request body to pass to an operation as referenced by operationId or operationPath or channelPath",
"type": "object",
"properties": {
"contentType": {
"description": "The Content-Type for the request content",
"type": "string"
},
"payload": true,
"replacements": {
"description": "A list of locations and values to set within a payload",
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#/$defs/payload-replacement-object"
}
}
},
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"criterion-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#criterion-object",
"description": "An object used to specify the context, conditions, and condition types\nthat can be used to prove or satisfy assertions specified in Step Object successCriteria,\nSuccess Action Object criteria, and Failure Action Object criteria",
"type": "object",
"properties": {
"context": {
"description": "A runtime expression used to set the context for the condition to be applied on",
"type": "string"
},
"condition": {
"description": "The condition to apply",
"type": "string"
},
"type": {
"description": "The type of condition to be applied or a reference to an expression type object",
"oneOf": [
{
"type": "string",
"enum": [
"simple",
"regex",
"jsonpath",
"xpath"
],
"default": "simple"
},
{
"$ref": "#/$defs/expression-type-object"
}
]
}
},
"required": [
"condition"
],
"dependentRequired": {
"type": [
"context"
]
},
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"expression-type-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#expression-type-object",
"description": "An object used to describe the type and version of an expression used within a Criterion Object or Selector Object. If the `version` is omitted, a default value is assumed based on the expression `type`",
"type": "object",
"properties": {
"type": {
"description": "The type of selector to use",
"enum": [
"jsonpath",
"xpath",
"jsonpointer"
]
},
"version": {
"description": "A short hand string representing the version of the expression type. If omitted, the default for the selected type will be used.\n",
"type": "string"
}
},
"required": [
"type",
"version"
],
"allOf": [
{
"if": {
"required": [
"type"
],
"properties": {
"type": {
"const": "jsonpath"
}
}
},
"then": {
"properties": {
"version": {
"enum": [
"rfc9535",
"draft-goessner-dispatch-jsonpath-00"
]
}
}
}
},
{
"if": {
"required": [
"type"
],
"properties": {
"type": {
"const": "xpath"
}
}
},
"then": {
"properties": {
"version": {
"enum": [
"xpath-10",
"xpath-20",
"xpath-30",
"xpath-31"
]
}
}
}
},
{
"if": {
"properties": {
"type": {
"const": "jsonpointer"
}
}
},
"then": {
"properties": {
"version": {
"const": "rfc6901"
}
}
}
}
],
"$ref": "#/$defs/specification-extensions"
},
"success-action-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#success-action-object",
"description": "A single success action which describes an action to take upon success of a workflow step",
"type": "object",
"properties": {
"name": {
"description": "The name of the success action",
"type": "string"
},
"type": {
"description": "The type of action to take",
"enum": [
"end",
"goto"
]
},
"workflowId": {
"description": "The workflowId referencing an existing workflow within the Arazzo description to transfer to upon success of the step",
"$ref": "#workflowId"
},
"stepId": {
"description": "The stepId to transfer to upon success of the step",
"$ref": "#stepId"
},
"parameters": {
"description": "A list of parameters that MUST be passed to a workflow as referenced by workflowId",
"type": "array",
"uniqueItems": true,
"items": true
},
"criteria": {
"description": "A list of assertions to determine if this action SHALL be executed",
"type": "array",
"uniqueItems": true,
"minItems": 1,
"items": {
"$ref": "#/$defs/criterion-object"
}
}
},
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "goto"
}
}
},
"then": {
"oneOf": [
{
"required": [
"workflowId"
]
},
{
"required": [
"stepId"
]
}
]
}
},
{
"if": {
"required": [
"parameters"
]
},
"then": {
"required": [
"workflowId"
]
}
}
],
"required": [
"name",
"type"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"failure-action-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#failure-action-object",
"description": "A single failure action which describes an action to take upon failure of a workflow step",
"type": "object",
"properties": {
"name": {
"description": "The name of the failure action",
"type": "string"
},
"type": {
"description": "The type of action to take",
"enum": [
"end",
"goto",
"retry"
]
},
"workflowId": {
"description": "The workflowId referencing an existing workflow within the Arazzo description to transfer to upon failure of the step",
"$ref": "#workflowId"
},
"stepId": {
"description": "The stepId to transfer to upon failure of the step",
"$ref": "#stepId"
},
"parameters": {
"description": "A list of parameters that MUST be passed to a workflow as referenced by workflowId",
"type": "array",
"uniqueItems": true,
"items": true
},
"retryAfter": {
"description": "A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made",
"type": "number",
"minimum": 0
},
"retryLimit": {
"description": "A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step",
"type": "integer",
"minimum": 0
},
"criteria": {
"description": "A list of assertions to determine if this action SHALL be executed",
"type": "array",
"uniqueItems": true,
"items": {
"$ref": "#/$defs/criterion-object"
}
}
},
"allOf": [
{
"if": {
"properties": {
"type": {
"enum": [
"goto"
]
}
}
},
"then": {
"oneOf": [
{
"required": [
"workflowId"
]
},
{
"required": [
"stepId"
]
}
]
}
},
{
"if": {
"required": [
"parameters"
]
},
"then": {
"required": [
"workflowId"
]
}
}
],
"required": [
"name",
"type"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"reusable-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#reusable-object",
"description": "A simple object to allow referencing of objects contained within the Components Object",
"type": "object",
"properties": {
"reference": {
"description": "A runtime expression used to reference the desired object",
"type": "string"
},
"value": {
"description": "Sets a value of the referenced parameter",
"type": [
"string",
"boolean",
"object",
"array",
"number",
"null"
]
}
},
"required": [
"reference"
],
"unevaluatedProperties": false
},
"parameter-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#parameter-object",
"description": "Describes a single step parameter",
"type": "object",
"properties": {
"name": {
"description": "The name of the parameter",
"type": "string"
},
"in": {
"description": "The named location of the parameter",
"enum": [
"path",
"query",
"querystring",
"header",
"cookie",
"channel"
]
},
"value": {
"description": "The value to pass in the parameter",
"oneOf": [
{
"type": [
"string",
"boolean",
"array",
"number",
"null"
]
},
{
"$ref": "#/$defs/selector-object"
}
]
}
},
"required": [
"name",
"value"
],
"$ref": "#/$defs/specification-extensions",
"unevaluatedProperties": false
},
"payload-replacement-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#payload-replacement-object",
"description": "Describes a location within a payload (e.g., a request body) and a value to set within the location",
"type": "object",
"properties": {
"target": {
"description": "A JSONPath, JSON Pointer, or XPath Expression which MUST be resolved against the request body",
"type": "string"
},
"targetSelectorType": {
"description": "The selector expression type to use (e.g., `jsonpath`, `xpath`, or `jsonpointer`). Should an alternate version be required, the Expression Type Object may be used instead. If omitted, defaults to JSON Pointer for `application/json` or XPath for XML-based media types.\n",
"$ref": "#/$defs/selector-type"
},
"value": {
"description": "The value to set at the location defined by the target. May be a literal, a runtime expression string, or a selector object.\n",
"oneOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/selector-object"
}
]
}
},
"required": [
"target",
"value"
],
"unevaluatedProperties": false,
"$ref": "#/$defs/specification-extensions"
},
"selector-type": {
"description": "A selector expression type that may be a simple string enum or an Expression Type Object for version-specific support",
"oneOf": [
{
"type": "string",
"enum": [
"jsonpointer",
"jsonpath",
"xpath"
]
},
{
"$ref": "#/$defs/expression-type-object"
}
]
},
"selector-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#selector-object",
"description": "An object which enables fine-grained traversal and precise data selection from structured data",
"type": "object",
"properties": {
"context": {
"description": "A valid Runtime Expression which MUST evaluate to structured data (e.g., `$response.body`), and sets the context for the selector to be applied on",
"type": "string"
},
"selector": {
"description": "A selector expression (e.g., `$.items[0].id`, `/Envelope/Item`) in the form of JSONPath expression, XPath expression, or JSON Pointer expression",
"type": "string"
},
"type": {
"description": "The selector expression type to use (e.g., `jsonpath`, `xpath`, or `jsonpointer`) or an Expression Type Object for older version support",
"$ref": "#/$defs/selector-type"
}
},
"required": [
"context",
"selector",
"type"
],
"unevaluatedProperties": false,
"$ref": "#/$defs/specification-extensions"
},
"components-object": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#components-object",
"description": "Holds a set of reusable objects for different aspects of the Arazzo Specification",
"type": "object",
"properties": {
"inputs": {
"description": "An object to hold reusable JSON Schema 2020-12 schemas to be referenced from workflow inputs",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/schema"
}
},
"parameters": {
"description": "An object to hold reusable Parameter Objects",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/parameter-object"
}
},
"successActions": {
"description": "An object to hold reusable Success Actions Objects",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/success-action-object"
}
},
"failureActions": {
"description": "An object to hold reusable Failure Actions Objects",
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/failure-action-object"
}
}
},
"patternProperties": {
"^(inputs|parameters|successActions|failureActions)$": {
"$comment": "Enumerating all of the property names in the regex is necessary for unevaluatedProperties to work as expected",
"propertyNames": {
"pattern": "^[a-zA-Z0-9\\.\\-_]+$"
}
}
},
"unevaluatedProperties": false,
"$ref": "#/$defs/specification-extensions"
},
"specification-extensions": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#specification-extensions",
"description": "While the Arazzo Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points",
"patternProperties": {
"^x-": true
}
},
"schema": {
"$comment": "https://spec.openapis.org/arazzo/v1.1#schema-object",
"$ref": "https://json-schema.org/draft/2020-12/schema"
}
}
}