From 81427ed1184139184d4fccaa50ad7abe4cfb8945 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Mon, 26 Aug 2024 09:55:21 +0100 Subject: [PATCH 01/13] V1.0.0-dev (#230) * chore: fix double pipe rendering for respec * chore: remove erroneous mention of 'function' in failureActions --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index df55813..ef9d999 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -456,7 +456,7 @@ Field Name | Type | Description type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`. workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. When used with `"retry"`, context transfers back upon completion of the specified workflow. stepId | `string` | The `stepId` to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. When used with `"retry"`, context transfers back upon completion of the specified step. - retryAfter | `number` | A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://tools.ietf.org/html/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `"retry"` or `"function"`. + retryAfter | `number` | A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://tools.ietf.org/html/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `"retry"`. retryLimit | `integer` | A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step. If not specified then a single retry SHALL be attempted. This field only applies when the `type` field value is `"retry"`. The `retryLimit` MUST be exhausted prior to executing subsequent failure actions. criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). From eb6066b12635a90c7ce1efdba98a118feb688385 Mon Sep 17 00:00:00 2001 From: Jeremy Fiel <32110157+jeremyfiel@users.noreply.github.com> Date: Mon, 26 Aug 2024 04:57:36 -0400 Subject: [PATCH 02/13] fix(typo): in parameter object description (#232) * update casing of Runtime Expression text --- versions/1.0.0.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index ef9d999..b2706a4 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -243,7 +243,7 @@ Field Name | Type | Description summary | `string` | A summary of the purpose or objective of the workflow. description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. -dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. The values provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Arazzo Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. +dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. The values provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Arazzo Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. successActions | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to success actions defined in the [components/successActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. failureActions | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to failure actions defined in the [components/failureActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. @@ -299,15 +299,15 @@ Field Name | Type | Description ---|:---:|--- description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. stepId | `string` | **REQUIRED**. Unique string to represent the step. The `stepId` MUST be unique amongst all steps described in the workflow. The `stepId` value is **case-sensitive**. Tools and libraries MAY use the `stepId` to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. -operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `sourceDescriptions`. The referenced operation will be invoked by this workflow step. If multiple (non `arazzo` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively. -operationPath | `string` | A reference to a [Source](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [runtime expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`. -workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively. +operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `sourceDescriptions`. The referenced operation will be invoked by this workflow step. If multiple (non `arazzo` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively. +operationPath | `string` | A reference to a [Source](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [Runtime Expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`. +workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively. parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible. successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object). All assertions `MUST` be satisfied for the step to be deemed successful. onSuccess | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a success action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a success action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. onFailure | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a failure action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a failure action defined in the [components](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. -outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value defined using a [runtime expression](#runtime-expressions). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. +outputs | Map[`string`, {expression}] | A map between a friendly name and a dynamic output value defined using a [Runtime Expression](#runtime-expressions). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -388,8 +388,8 @@ Describes a single step parameter. A unique parameter is defined by the combinat Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. - in | `string` | The name location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, `"cookie"`, or `"body"`. When the step in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. - value | Any \| {expression} | **REQUIRED**. The value to pass in the parameter. The value can be a constant or an [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. + in | `string` | The location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, `"cookie"`, or `"body"`. When the step in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. + value | Any \| {expression} | **REQUIRED**. The value to pass in the parameter. The value can be a constant or a [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. This object MAY be extended with [Specification Extensions](#specification-extensions). @@ -421,7 +421,7 @@ Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_. type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"`. - workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. + workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. stepId | `string` | The `stepId` to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. criteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine if this action SHALL be executed. Each assertion is described using a [Criterion Object](#criterion-object). All criteria assertions `MUST` be satisfied for the action to be executed. @@ -454,7 +454,7 @@ Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_. type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`. - workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. When used with `"retry"`, context transfers back upon completion of the specified workflow. + workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive to `stepId`. When used with `"retry"`, context transfers back upon completion of the specified workflow. stepId | `string` | The `stepId` to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. When used with `"retry"`, context transfers back upon completion of the specified step. retryAfter | `number` | A non-negative decimal indicating the seconds to delay after the step failure before another attempt SHALL be made. **Note:** if an HTTP [Retry-After](https://tools.ietf.org/html/rfc9110.html#name-retry-after) response header was returned to a step from a targeted operation, then it SHOULD overrule this particular field value. This field only applies when the `type` field value is `"retry"`. retryLimit | `integer` | A non-negative integer indicating how many attempts to retry the step MAY be attempted before failing the overall step. If not specified then a single retry SHALL be attempted. This field only applies when the `type` field value is `"retry"`. The `retryLimit` MUST be exhausted prior to executing subsequent failure actions. @@ -585,7 +585,7 @@ A simple object to allow referencing of objects contained within the [Components ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -reference | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired object. +reference | `{expression}` | **REQUIRED**. A [Runtime Expression](#runtime-expressions) used to reference the desired object. value | `string` | Sets a value of the referenced parameter. This is only applicable for parameter object references. This object cannot be extended with additional properties and any properties added MUST be ignored. @@ -655,7 +655,7 @@ String comparisons `MUST` be case insensitive. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -context | `{expression}` | A [runtime expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query expression could be applied to). +context | `{expression}` | A [Runtime Expression](#runtime-expressions) used to set the context for the condition to be applied on. If `type` is specified, then the `context` MUST be provided (e.g. `$response.body` would set the context that a JSONPath query expression could be applied to). condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies an operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex or JSONPath, the `type` and `context` MUST be specified. type | `string` \| [Criterion Expression Type Object](#criterion-expression-type-object) | The type of condition to be applied. If specified, the options allowed are `simple`, `regex`, `jsonpath` or `xpath`. If omitted, then the condition is assumed to be `simple`, which at most combines literals, operators and [Runtime Expressions](#runtime-expressions). If `jsonpath`, then the expression MUST conform to [JSONPath](https://tools.ietf.org/html/rfc9535). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSONPath or XPath be required, then a [Criterion Expression Type Object](#criterion-expression-type-object) MUST be specified. From 7a1bbdd8fd53bcbb5816fc4a92b8374a796cf8e3 Mon Sep 17 00:00:00 2001 From: Jeremy Fiel <32110157+jeremyfiel@users.noreply.github.com> Date: Mon, 26 Aug 2024 04:59:28 -0400 Subject: [PATCH 03/13] chore: sourceDescription typo and emphasis on MUST (#234) * Minor example updates from linter (#215) * Update ReadMe images (#229) * chore: fix double pipe rendering for respec * chore: update images on the repo ReadMe * chore: typo closes #233 --------- Co-authored-by: Lorna Jane Mitchell Co-authored-by: Frank Kilcommins --- versions/1.0.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index b2706a4..84de4eb 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -71,7 +71,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA It is RECOMMENDED that the entry Arazzo document be named: `arazzo.json` or `arazzo.yaml`. -An Arazzo Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. If workflows from other documents are being referenced, they must by included as a [Source Description Object](#source-description-object). In a multi-document description, the document containing the [Arazzo Specification Object](#arazzo-specification-object) is known as the **entry Arazzo document**. +An Arazzo Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. If workflows from other documents are being referenced, they MUST be included as a [Source Description Object](#source-description-object). In a multi-document description, the document containing the [Arazzo Specification Object](#arazzo-specification-object) is known as the **entry Arazzo document**. ### Data Types From f3cbf1fc159b5ae5dd926d65106223b8d027cd2e Mon Sep 17 00:00:00 2001 From: Jeremy Fiel <32110157+jeremyfiel@users.noreply.github.com> Date: Wed, 28 Aug 2024 12:19:21 -0400 Subject: [PATCH 04/13] feat(spec): JSON Schema 2020-12 definition for Arazzo descriptions (#224) applied feedback 2024/08/02 applied feedback 2024/08/04 constrain `inputs` to JSON Schema 2020-12 metaschema closes #176 Co-authored-by: handrews <2358015+handrews@users.noreply.github.com> Co-authored-by: Jason Desrosiers <716571+jdesrosiers@users.noreply.github.com> --- schemas/v1.0/schema.json | 808 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 808 insertions(+) create mode 100644 schemas/v1.0/schema.json diff --git a/schemas/v1.0/schema.json b/schemas/v1.0/schema.json new file mode 100644 index 0000000..fc213e3 --- /dev/null +++ b/schemas/v1.0/schema.json @@ -0,0 +1,808 @@ +{ + "$id": "https://spec.openapis.org/arazzo/1.0/schema/2024-08-01", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "The description of OpenAPI Initiative Arazzo v1.0.0 documents without schema validation, as defined by https://spec.openapis.org/arazzo/v1.0.0", + "type": "object", + "properties": { + "arazzo": { + "description": "The version number of the Arazzo Specification", + "type": "string", + "pattern": "^1\\.0\\.\\d+(-.+)?$" + }, + "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.0.0#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.0.0#source-description-object", + "description": "Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an 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" + ] + } + }, + "required": [ + "name", + "url" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "workflow-object": { + "$comment": "https://spec.openapis.org/arazzo/v1.0.0#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", + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "type": "string" + } + } + }, + "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.0.0#step-object'", + "description": "Describes a single workflow step which MAY be a call to an API operation (OpenAPI Operation Object or another Workflow Object)", + "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" + }, + "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" + }, + "workflowId": { + "description": "The workflowId referencing an existing workflow within the Arazzo description", + "$ref": "#workflowId" + }, + "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", + "type": "object", + "patternProperties": { + "^[a-zA-Z0-9\\.\\-_]+$": { + "type": "string" + } + } + } + }, + "required": [ + "stepId" + ], + "oneOf": [ + { + "required": [ + "operationId" + ] + }, + { + "required": [ + "operationPath" + ] + }, + { + "required": [ + "workflowId" + ] + } + ], + "allOf": [ + { + "if": { + "oneOf": [ + { + "required": [ + "operationPath" + ] + }, + { + "required": [ + "operationId" + ] + } + ] + }, + "then": { + "properties": { + "parameters": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/reusable-object" + }, + { + "$ref": "#/$defs/parameter-object", + "required": [ + "in" + ] + } + ] + } + } + } + } + }, + { + "if": { + "required": [ + "workflowId" + ] + }, + "then": { + "properties": { + "parameters": { + "items": { + "oneOf": [ + { + "$ref": "#/$defs/parameter-object" + }, + { + "$ref": "#/$defs/reusable-object" + } + ] + } + } + } + } + } + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "request-body-object": { + "$comment": "https://spec.openapis.org/arazzo/v1.0.0#request-body-object", + "description": "The request body to pass to an operation as referenced by operationId or operationPath", + "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.0.0#criterion-object", + "description": "An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in Step Object successCriteria, Success 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" + } + }, + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "description": "The type of condition to be applied", + "enum": [ + "simple", + "regex", + "jsonpath", + "xpath" + ], + "default": "simple" + } + } + }, + { + "$ref": "#/$defs/criterion-expression-type-object" + } + ], + "required": [ + "condition" + ], + "dependentRequired": { + "type": [ + "context" + ] + }, + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "criterion-expression-type-object": { + "$comment": "https://spec.openapis.org/arazzo/v1.0.0#criterion-expression-type-object", + "description": "An object used to describe the type and version of an expression used within a Criterion Object", + "type": "object", + "properties": { + "type": { + "description": "The type of condition to be applied", + "enum": [ + "jsonpath", + "xpath" + ] + }, + "version": { + "description": "A short hand string representing the version of the expression type", + "type": "string" + } + }, + "required": [ + "type", + "version" + ], + "allOf": [ + { + "if": { + "required": [ + "type" + ], + "properties": { + "type": { + "const": "jsonpath" + } + } + }, + "then": { + "properties": { + "version": { + "const": "draft-goessner-dispatch-jsonpath-00" + } + } + } + }, + { + "if": { + "required": [ + "type" + ], + "properties": { + "type": { + "const": "xpath" + } + } + }, + "then": { + "properties": { + "version": { + "enum": [ + "xpath-10", + "xpath-20", + "xpath-30" + ] + } + } + } + } + ], + "$ref": "#/$defs/specification-extensions" + }, + "success-action-object": { + "$comment": "https://spec.openapis.org/arazzo/v1.0.0#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" + }, + "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" + ] + } + ] + } + } + ], + "required": [ + "name", + "type" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "failure-action-object": { + "$comment": "https://spec.openapis.org/arazzo/v1.0.0#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" + }, + "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", + "retry" + ] + } + } + }, + "then": { + "oneOf": [ + { + "required": [ + "workflowId" + ] + }, + { + "required": [ + "stepId" + ] + } + ] + } + }, + { + "if": { + "properties": { + "type": { + "const": "retry" + } + } + }, + "then": { + "required": [ + "retryAfter" + ] + } + } + ], + "required": [ + "name", + "type" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "reusable-object": { + "$comment": "https://spec.openapis.org/arazzo/v1.0.0#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.0.0#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", + "header", + "cookie", + "body" + ] + }, + "value": { + "description": "The value to pass in the parameter", + "type": [ + "string", + "boolean", + "object", + "array", + "number", + "null" + ] + } + }, + "required": [ + "name", + "value" + ], + "$ref": "#/$defs/specification-extensions", + "unevaluatedProperties": false + }, + "payload-replacement-object": { + "$comment": "https://spec.openapis.org/arazzo/v1.0.0#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 JSON Pointer or XPath Expression which MUST be resolved against the request body", + "type": "string" + }, + "value": { + "description": "The value set within the target location", + "type": "string" + } + }, + "required": [ + "target", + "value" + ], + "unevaluatedProperties": false, + "$ref": "#/$defs/specification-extensions" + }, + "components-object": { + "$comment": "https://spec.openapis.org/arazzo/v1.0.0#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.0.0#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.0.0#schema-object", + "$ref": "https://json-schema.org/draft/2020-12/schema" + } + } +} \ No newline at end of file From dda6820255d025aef80a3dbeb2d25fbba0ec1f11 Mon Sep 17 00:00:00 2001 From: Bruno Pedro Date: Wed, 11 Sep 2024 11:34:23 +0200 Subject: [PATCH 05/13] Update 1.0.0.md (#249) --- versions/1.0.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 84de4eb..8ef437a 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -291,7 +291,7 @@ outputs: #### Step Object -Describes a single workflow step which MAY be a call to an API operation ([OpenAPI Operation Object](https://spec.openapis.org/oas/latest.html#operation-object) or another [Workflow Object](#workflow-object)). +Describes a single workflow step which MAY be a call to an API operation ([OpenAPI Operation Object](https://spec.openapis.org/oas/latest.html#operation-object)) or another [Workflow Object](#workflow-object). ##### Fixed Fields @@ -948,4 +948,4 @@ The proposed MIME media type for Arazzo documents (e.g. workflows) that require Version | Date | Notes --- | --- | --- -1.0.0 | 2024-05-29 | First release of the Arazzo Specification \ No newline at end of file +1.0.0 | 2024-05-29 | First release of the Arazzo Specification From 4413d7a4922373b60deb636c693c3816aadd946b Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Wed, 23 Oct 2024 14:32:59 +0100 Subject: [PATCH 06/13] Merge main into dev (#258) * Minor example updates from linter (#215) * Update ReadMe images (#229) * chore: fix double pipe rendering for respec * chore: update images on the repo ReadMe * Use latest respec (#239) --------- Co-authored-by: Lorna Jane Mitchell Co-authored-by: Ralf Handl From 939423becb41d98427d3089b34b7de8d1fafc210 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Tue, 12 Nov 2024 10:19:26 +0000 Subject: [PATCH 07/13] Remove mentions of event message from Runtime Expressions (#269) * chore: fix double pipe rendering for respec * chore: remove erroneous mention of 'function' in failureActions * remove reference to event messages from ABNF expressions --- versions/1.0.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 8ef437a..2e59799 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -820,12 +820,12 @@ This object MAY be extended with [Specification Extensions](#specification-exten ### Runtime Expressions -A runtime expression allows values to be defined based on information that will be available within an HTTP message, an event message, and within objects serialized from the Arazzo document such as [workflows](#workflow-object) or [steps](#step-object). +A runtime expression allows values to be defined based on information that will be available within the HTTP message in an actual API call, or within objects serialized from the Arazzo document such as [workflows](#workflow-object) or [steps](#step-object). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: ```abnf - expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$message." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name / "$components." name / "$components.parameters." parameter-name) + expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name / "$components." name / "$components.parameters." parameter-name) parameter-name = name ; Reuses 'name' rule for parameter names source = ( header-reference / query-reference / path-reference / body-reference ) header-reference = "header." token From 8f0b33c4bdcdd0da11c449a427c0321d273e3263 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Fri, 22 Nov 2024 09:48:34 +0000 Subject: [PATCH 08/13] Fix(docs): Address typo in Parameter `in` description, and improve clarity on Source Description Object links (#284) * fix(spec): improve clarity and fix Parameter `in` description * chore(spec): fix typo --- versions/1.0.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 2e59799..8a385d2 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -47,7 +47,7 @@ The Arazzo Specification can articulate these workflows in a human-readable and ## Definitions ##### Arazzo Description -A self-contained document (or set of documents) which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). An Arazzo Description uses and conforms to the Arazzo Specification, and `MUST` contain a valid Arazzo Specification version field (`arazzo`), an [Info](#info-object) field, a `sourceDescriptions` field with at least one defined [Source](#source-description-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the `workflows` fixed field. +A self-contained document (or set of documents) which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). An Arazzo Description uses and conforms to the Arazzo Specification, and `MUST` contain a valid Arazzo Specification version field (`arazzo`), an [info](#info-object) field, a `sourceDescriptions` field with at least one defined [Source Description](#source-description-object), and there `MUST` be at least one [Workflow](#workflow-object) defined in the `workflows` fixed field. ## Specification @@ -300,7 +300,7 @@ Field Name | Type | Description description | `string` | A description of the step. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. stepId | `string` | **REQUIRED**. Unique string to represent the step. The `stepId` MUST be unique amongst all steps described in the workflow. The `stepId` value is **case-sensitive**. Tools and libraries MAY use the `stepId` to uniquely identify a workflow step, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`. operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `sourceDescriptions`. The referenced operation will be invoked by this workflow step. If multiple (non `arazzo` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively. -operationPath | `string` | A reference to a [Source](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [Runtime Expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`. +operationPath | `string` | A reference to a [Source Description Object](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [Runtime Expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`. workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Arazzo Description. If multiple `arazzo` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively. parameters | [[Parameter Object](#parameter-object) \| [Reusable Object](#reusable-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Arazzo document. The list MUST NOT include duplicate parameters. requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible. @@ -388,7 +388,7 @@ Describes a single step parameter. A unique parameter is defined by the combinat Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the parameter. Parameter names are _case sensitive_. - in | `string` | The location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, `"cookie"`, or `"body"`. When the step in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. + in | `string` | The location of the parameter. Possible values are `"path"`, `"query"`, `"header"`, or `"cookie"`. When the step in context specifies a `workflowId`, then all parameters map to workflow inputs. In all other scenarios (e.g., a step specifies an `operationId`), the `in` field MUST be specified. value | Any \| {expression} | **REQUIRED**. The value to pass in the parameter. The value can be a constant or a [Runtime Expression](#runtime-expressions) to be evaluated and passed to the referenced operation or workflow. This object MAY be extended with [Specification Extensions](#specification-extensions). From 937cbca17151a275c540606a7b30ffc2d87bfabd Mon Sep 17 00:00:00 2001 From: Ethan <133719+notEthan@users.noreply.github.com> Date: Fri, 22 Nov 2024 01:53:13 -0800 Subject: [PATCH 09/13] Minor edits (#283) * Fix plural `dependsOn` values in Workflow Object * Put code-ish identifiers in code format --- versions/1.0.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index 8a385d2..d629203 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -243,7 +243,7 @@ Field Name | Type | Description summary | `string` | A summary of the purpose or objective of the workflow. description | `string` | A description of the workflow. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow. -dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. The values provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Arazzo Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. +dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. Each value provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Arazzo Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [Runtime Expression](#runtime-expressions) (e.g., `$sourceDescriptions..`) to avoid ambiguity or potential clashes. steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow. successActions | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to success actions defined in the [components/successActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate success actions. failureActions | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. If a Reusable Object is provided, it MUST link to failure actions defined in the [components/failureActions](#components-object) of the current Arazzo document. The list MUST NOT include duplicate failure actions. @@ -379,7 +379,7 @@ steps: #### Parameter Object Describes a single step parameter. A unique parameter is defined by the combination of a `name` and `in` fields. There are four possible locations specified by the `in` field: - - path - Used together with OpenAPI style [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId. + - path - Used together with OpenAPI style [Path Templating](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. - query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`. - header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. - cookie - Used to pass a specific cookie value to the source API. From 962fa45e100cc93fe3b65ce9696f99fe73168195 Mon Sep 17 00:00:00 2001 From: Jeremy Fiel <32110157+jeremyfiel@users.noreply.github.com> Date: Mon, 16 Dec 2024 07:18:03 -0500 Subject: [PATCH 10/13] feat(spec): update `$comment` symlinks and root description (#285) --- schemas/v1.0/schema.json | 32 +-- schemas/v1.0/schema.yaml | 544 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 557 insertions(+), 19 deletions(-) diff --git a/schemas/v1.0/schema.json b/schemas/v1.0/schema.json index fc213e3..d4905a1 100644 --- a/schemas/v1.0/schema.json +++ b/schemas/v1.0/schema.json @@ -1,7 +1,7 @@ { "$id": "https://spec.openapis.org/arazzo/1.0/schema/2024-08-01", "$schema": "https://json-schema.org/draft/2020-12/schema", - "description": "The description of OpenAPI Initiative Arazzo v1.0.0 documents without schema validation, as defined by https://spec.openapis.org/arazzo/v1.0.0", + "description": "The description of Arazzo v1.0.x documents", "type": "object", "properties": { "arazzo": { @@ -44,7 +44,7 @@ "unevaluatedProperties": false, "$defs": { "info": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#info-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#info-object", "description": "Provides metadata about the Arazzo description", "type": "object", "properties": { @@ -73,7 +73,7 @@ "unevaluatedProperties": false }, "source-description-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#source-description-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#source-description-object", "description": "Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo description", "type": "object", "properties": { @@ -103,7 +103,7 @@ "unevaluatedProperties": false }, "workflow-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#workflow-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#workflow-object", "description": "Describes the steps to be taken across one or more APIs to achieve an objective", "type": "object", "properties": { @@ -204,7 +204,7 @@ "unevaluatedProperties": false }, "step-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#step-object'", + "$comment": "https://spec.openapis.org/arazzo/v1.0#step-object'", "description": "Describes a single workflow step which MAY be a call to an API operation (OpenAPI Operation Object or another Workflow Object)", "type": "object", "properties": { @@ -371,7 +371,7 @@ "unevaluatedProperties": false }, "request-body-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#request-body-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#request-body-object", "description": "The request body to pass to an operation as referenced by operationId or operationPath", "type": "object", "properties": { @@ -393,7 +393,7 @@ "unevaluatedProperties": false }, "criterion-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#criterion-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-object", "description": "An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in Step Object successCriteria, Success Action Object criteria, and Failure Action Object criteria", "type": "object", "properties": { @@ -438,7 +438,7 @@ "unevaluatedProperties": false }, "criterion-expression-type-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#criterion-expression-type-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-expression-type-object", "description": "An object used to describe the type and version of an expression used within a Criterion Object", "type": "object", "properties": { @@ -505,7 +505,7 @@ "$ref": "#/$defs/specification-extensions" }, "success-action-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#success-action-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#success-action-object", "description": "A single success action which describes an action to take upon success of a workflow step", "type": "object", "properties": { @@ -571,7 +571,7 @@ "unevaluatedProperties": false }, "failure-action-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#failure-action-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#failure-action-object", "description": "A single failure action which describes an action to take upon failure of a workflow step", "type": "object", "properties": { @@ -664,7 +664,7 @@ "unevaluatedProperties": false }, "reusable-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#reusable-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#reusable-object", "description": "A simple object to allow referencing of objects contained within the Components Object", "type": "object", "properties": { @@ -690,7 +690,7 @@ "unevaluatedProperties": false }, "parameter-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#parameter-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#parameter-object", "description": "Describes a single step parameter", "type": "object", "properties": { @@ -728,7 +728,7 @@ "unevaluatedProperties": false }, "payload-replacement-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#payload-replacement-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#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": { @@ -749,7 +749,7 @@ "$ref": "#/$defs/specification-extensions" }, "components-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#components-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#components-object", "description": "Holds a set of reusable objects for different aspects of the Arazzo Specification", "type": "object", "properties": { @@ -794,14 +794,14 @@ "$ref": "#/$defs/specification-extensions" }, "specification-extensions": { - "$comment": "https://spec.openapis.org/arazzo/v1.0.0#specification-extensions", + "$comment": "https://spec.openapis.org/arazzo/v1.0#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.0.0#schema-object", + "$comment": "https://spec.openapis.org/arazzo/v1.0#schema-object", "$ref": "https://json-schema.org/draft/2020-12/schema" } } diff --git a/schemas/v1.0/schema.yaml b/schemas/v1.0/schema.yaml index 41283b3..ecc6afd 100644 --- a/schemas/v1.0/schema.yaml +++ b/schemas/v1.0/schema.yaml @@ -1,6 +1,544 @@ $id: 'https://spec.openapis.org/arazzo/1.0/schema/WORK-IN-PROGRESS' $schema: 'https://json-schema.org/draft/2020-12/schema' - -description: The description of Arazzo v1.0.x documents - +description: |- + The description of Arazzo v1.0.x documents type: object +properties: + arazzo: + description: The version number of the Arazzo Specification + type: string + pattern: '^1\.0\.\d+(-.+)?$' + 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.0#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.0#source-description-object + description: |- + Describes a source description (such as an OpenAPI description) + that will be referenced by one or more workflows described within + an 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 + required: + - name + - url + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + workflow-object: + $comment: https://spec.openapis.org/arazzo/v1.0#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 + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + type: string + 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.0#step-object' + description: |- + Describes a single workflow step which MAY be a call to an + API operation (OpenAPI Operation Object or another Workflow Object) + 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 + 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 + workflowId: + description: The workflowId referencing an existing workflow within the Arazzo description + $ref: '#workflowId' + 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 + type: object + patternProperties: + '^[a-zA-Z0-9\.\-_]+$': + type: string + required: + - stepId + oneOf: + - required: + - operationId + - required: + - operationPath + - required: + - workflowId + allOf: + - if: + oneOf: + - required: + - operationPath + - required: + - operationId + then: + properties: + parameters: + items: + oneOf: + - $ref: '#/$defs/reusable-object' + - $ref: '#/$defs/parameter-object' + required: + - in + - if: + required: + - workflowId + then: + properties: + parameters: + items: + oneOf: + - $ref: '#/$defs/parameter-object' + - $ref: '#/$defs/reusable-object' + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + request-body-object: + $comment: https://spec.openapis.org/arazzo/v1.0#request-body-object + description: The request body to pass to an operation as referenced by operationId or operationPath + 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.0#criterion-object + description: |- + An object used to specify the context, conditions, and condition types + that can be used to prove or satisfy assertions specified in Step Object successCriteria, + Success 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 + anyOf: + - type: object + properties: + type: + description: The type of condition to be applied + enum: + - simple + - regex + - jsonpath + - xpath + default: simple + - $ref: '#/$defs/criterion-expression-type-object' + required: + - condition + dependentRequired: + type: + - context + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + criterion-expression-type-object: + $comment: https://spec.openapis.org/arazzo/v1.0#criterion-expression-type-object + description: An object used to describe the type and version of an expression used within a Criterion Object + type: object + properties: + type: + description: The type of condition to be applied + enum: + - jsonpath + - xpath + version: + description: A short hand string representing the version of the expression type + type: string + required: + - type + - version + allOf: + - if: + required: + - type + properties: + type: + const: jsonpath + then: + properties: + version: + const: draft-goessner-dispatch-jsonpath-00 + - if: + required: + - type + properties: + type: + const: xpath + then: + properties: + version: + enum: + - xpath-10 + - xpath-20 + - xpath-30 + $ref: '#/$defs/specification-extensions' + success-action-object: + $comment: https://spec.openapis.org/arazzo/v1.0#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' + 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 + required: + - name + - type + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + failure-action-object: + $comment: https://spec.openapis.org/arazzo/v1.0#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' + 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 + - retry + then: + oneOf: + - required: + - workflowId + - required: + - stepId + - if: + properties: + type: + const: retry + then: + required: + - retryAfter + required: + - name + - type + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + reusable-object: + $comment: https://spec.openapis.org/arazzo/v1.0#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.0#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 + - header + - cookie + - body + value: + description: The value to pass in the parameter + type: + - string + - boolean + - object + - array + - number + - 'null' + required: + - name + - value + $ref: '#/$defs/specification-extensions' + unevaluatedProperties: false + payload-replacement-object: + $comment: https://spec.openapis.org/arazzo/v1.0#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 JSON Pointer or XPath Expression which MUST be resolved against the request body + type: string + value: + description: The value set within the target location + type: string + required: + - target + - value + unevaluatedProperties: false + $ref: '#/$defs/specification-extensions' + components-object: + $comment: https://spec.openapis.org/arazzo/v1.0#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.0#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.0#schema-object + $ref: 'https://json-schema.org/draft/2020-12/schema' From 29ac21638847505dec8664dfe5ac8c571c7f2e31 Mon Sep 17 00:00:00 2001 From: Jeremy Fiel <32110157+jeremyfiel@users.noreply.github.com> Date: Mon, 16 Dec 2024 07:45:45 -0500 Subject: [PATCH 11/13] fix(schema): remove `body` from parameter object (#287) fixes #281 --- schemas/v1.0/schema.json | 3 +-- schemas/v1.0/schema.yaml | 1 - 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/schemas/v1.0/schema.json b/schemas/v1.0/schema.json index d4905a1..47bc21c 100644 --- a/schemas/v1.0/schema.json +++ b/schemas/v1.0/schema.json @@ -704,8 +704,7 @@ "path", "query", "header", - "cookie", - "body" + "cookie" ] }, "value": { diff --git a/schemas/v1.0/schema.yaml b/schemas/v1.0/schema.yaml index ecc6afd..c48b83d 100644 --- a/schemas/v1.0/schema.yaml +++ b/schemas/v1.0/schema.yaml @@ -471,7 +471,6 @@ $defs: - query - header - cookie - - body value: description: The value to pass in the parameter type: From e5ac108ebb69f119633b8d6b6857c5c6c7c1fca0 Mon Sep 17 00:00:00 2001 From: Frank Kilcommins Date: Mon, 16 Dec 2024 21:22:01 +0000 Subject: [PATCH 12/13] chore(spec): fix example used within spec (#288) * chore(spec): improve runtime expression examples and fix typo --- versions/1.0.0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/1.0.0.md b/versions/1.0.0.md index d629203..d676439 100644 --- a/versions/1.0.0.md +++ b/versions/1.0.0.md @@ -176,7 +176,7 @@ workflows: # outputs from this step availablePets: $response.body outputs: - available: $steps.getPetStep.availablePets + available: $steps.getPetStep.outputs.availablePets ``` #### Info Object @@ -856,8 +856,8 @@ Request URL | `$url` | Response value | `$response.body#/status` | In operations which return payloads, references may be made to portions of the response body or the entire body. Response header | `$response.header.Server` | Single header values only are available workflow input | `$inputs.username` or `$workflows.foo.inputs.username` | Single input values only are available -Step output value | `$steps.someStep.pets` | In situations where the output named property return payloads, references may be made to portions of the response body or the entire body. -Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | Single input values only are available +Step output value | `$steps.someStepId.outputs.pets` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$steps.someStepId.outputs.pets#/0/id`) or the entire body. +Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` | In situations where the output named property return payloads, references may be made to portions of the response body (e.g., `$workflows.foo.outputs.mappedResponse#/name`) or the entire body. Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object. Runtime expressions preserve the type of the referenced value. From d8bcae4d2ff5f5625930b3b69e2717a662584c60 Mon Sep 17 00:00:00 2001 From: Jeremy Fiel <32110157+jeremyfiel@users.noreply.github.com> Date: Mon, 16 Dec 2024 23:28:08 +0000 Subject: [PATCH 13/13] chore(schemas): remove json version, it will auto-publish relates to #286 --- schemas/v1.0/schema.json | 807 --------------------------------------- 1 file changed, 807 deletions(-) delete mode 100644 schemas/v1.0/schema.json diff --git a/schemas/v1.0/schema.json b/schemas/v1.0/schema.json deleted file mode 100644 index 47bc21c..0000000 --- a/schemas/v1.0/schema.json +++ /dev/null @@ -1,807 +0,0 @@ -{ - "$id": "https://spec.openapis.org/arazzo/1.0/schema/2024-08-01", - "$schema": "https://json-schema.org/draft/2020-12/schema", - "description": "The description of Arazzo v1.0.x documents", - "type": "object", - "properties": { - "arazzo": { - "description": "The version number of the Arazzo Specification", - "type": "string", - "pattern": "^1\\.0\\.\\d+(-.+)?$" - }, - "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.0#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.0#source-description-object", - "description": "Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an 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" - ] - } - }, - "required": [ - "name", - "url" - ], - "$ref": "#/$defs/specification-extensions", - "unevaluatedProperties": false - }, - "workflow-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0#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", - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "type": "string" - } - } - }, - "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.0#step-object'", - "description": "Describes a single workflow step which MAY be a call to an API operation (OpenAPI Operation Object or another Workflow Object)", - "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" - }, - "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" - }, - "workflowId": { - "description": "The workflowId referencing an existing workflow within the Arazzo description", - "$ref": "#workflowId" - }, - "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", - "type": "object", - "patternProperties": { - "^[a-zA-Z0-9\\.\\-_]+$": { - "type": "string" - } - } - } - }, - "required": [ - "stepId" - ], - "oneOf": [ - { - "required": [ - "operationId" - ] - }, - { - "required": [ - "operationPath" - ] - }, - { - "required": [ - "workflowId" - ] - } - ], - "allOf": [ - { - "if": { - "oneOf": [ - { - "required": [ - "operationPath" - ] - }, - { - "required": [ - "operationId" - ] - } - ] - }, - "then": { - "properties": { - "parameters": { - "items": { - "oneOf": [ - { - "$ref": "#/$defs/reusable-object" - }, - { - "$ref": "#/$defs/parameter-object", - "required": [ - "in" - ] - } - ] - } - } - } - } - }, - { - "if": { - "required": [ - "workflowId" - ] - }, - "then": { - "properties": { - "parameters": { - "items": { - "oneOf": [ - { - "$ref": "#/$defs/parameter-object" - }, - { - "$ref": "#/$defs/reusable-object" - } - ] - } - } - } - } - } - ], - "$ref": "#/$defs/specification-extensions", - "unevaluatedProperties": false - }, - "request-body-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0#request-body-object", - "description": "The request body to pass to an operation as referenced by operationId or operationPath", - "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.0#criterion-object", - "description": "An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in Step Object successCriteria, Success 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" - } - }, - "anyOf": [ - { - "type": "object", - "properties": { - "type": { - "description": "The type of condition to be applied", - "enum": [ - "simple", - "regex", - "jsonpath", - "xpath" - ], - "default": "simple" - } - } - }, - { - "$ref": "#/$defs/criterion-expression-type-object" - } - ], - "required": [ - "condition" - ], - "dependentRequired": { - "type": [ - "context" - ] - }, - "$ref": "#/$defs/specification-extensions", - "unevaluatedProperties": false - }, - "criterion-expression-type-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0#criterion-expression-type-object", - "description": "An object used to describe the type and version of an expression used within a Criterion Object", - "type": "object", - "properties": { - "type": { - "description": "The type of condition to be applied", - "enum": [ - "jsonpath", - "xpath" - ] - }, - "version": { - "description": "A short hand string representing the version of the expression type", - "type": "string" - } - }, - "required": [ - "type", - "version" - ], - "allOf": [ - { - "if": { - "required": [ - "type" - ], - "properties": { - "type": { - "const": "jsonpath" - } - } - }, - "then": { - "properties": { - "version": { - "const": "draft-goessner-dispatch-jsonpath-00" - } - } - } - }, - { - "if": { - "required": [ - "type" - ], - "properties": { - "type": { - "const": "xpath" - } - } - }, - "then": { - "properties": { - "version": { - "enum": [ - "xpath-10", - "xpath-20", - "xpath-30" - ] - } - } - } - } - ], - "$ref": "#/$defs/specification-extensions" - }, - "success-action-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0#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" - }, - "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" - ] - } - ] - } - } - ], - "required": [ - "name", - "type" - ], - "$ref": "#/$defs/specification-extensions", - "unevaluatedProperties": false - }, - "failure-action-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0#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" - }, - "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", - "retry" - ] - } - } - }, - "then": { - "oneOf": [ - { - "required": [ - "workflowId" - ] - }, - { - "required": [ - "stepId" - ] - } - ] - } - }, - { - "if": { - "properties": { - "type": { - "const": "retry" - } - } - }, - "then": { - "required": [ - "retryAfter" - ] - } - } - ], - "required": [ - "name", - "type" - ], - "$ref": "#/$defs/specification-extensions", - "unevaluatedProperties": false - }, - "reusable-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0#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.0#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", - "header", - "cookie" - ] - }, - "value": { - "description": "The value to pass in the parameter", - "type": [ - "string", - "boolean", - "object", - "array", - "number", - "null" - ] - } - }, - "required": [ - "name", - "value" - ], - "$ref": "#/$defs/specification-extensions", - "unevaluatedProperties": false - }, - "payload-replacement-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0#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 JSON Pointer or XPath Expression which MUST be resolved against the request body", - "type": "string" - }, - "value": { - "description": "The value set within the target location", - "type": "string" - } - }, - "required": [ - "target", - "value" - ], - "unevaluatedProperties": false, - "$ref": "#/$defs/specification-extensions" - }, - "components-object": { - "$comment": "https://spec.openapis.org/arazzo/v1.0#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.0#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.0#schema-object", - "$ref": "https://json-schema.org/draft/2020-12/schema" - } - } -} \ No newline at end of file