Skip to content

Commit

Permalink
chore: fix missing fixed field and table layout (#197)
Browse files Browse the repository at this point in the history
* chore: fix missing fixed field and table layout

* chore: use JSONPath consistently

* chore: fix respec workflow to use Arazzo in PR body

* chore: missing parentheses in step object description. Fixing RFC links
  • Loading branch information
frankkilcommins authored Jun 5, 2024
1 parent 65faff2 commit 6edb1ae
Show file tree
Hide file tree
Showing 3 changed files with 19 additions and 19 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/respec.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,6 @@ jobs:
body: |
This pull request is automatically triggered by GitHub action `respec`.
The versions/v*.md files of the API Tapestry Specification have changed, so the HTML files are automatically being regenerated.
The versions/v*.md files of the Arazzo Specification have changed, so the HTML files are automatically being regenerated.
8 changes: 4 additions & 4 deletions examples/1.0.0/oauth.arazzo.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ workflows:
- condition: $statusCode == 200
- context: $response.body
condition: $.access_token != null
type: JSONPath
type: jsonpath
outputs:
access_token: $response.body.access_token
refresh_token: $response.body.refresh_token
Expand Down Expand Up @@ -101,7 +101,7 @@ workflows:
- condition: $statusCode == 200
- context: $response.body
condition: $.access_token != null
type: JSONPath
type: jsonpath
outputs:
access_token: $response.body.access_token

Expand Down Expand Up @@ -151,7 +151,7 @@ workflows:
- condition: $statusCode == 200
- context: $response.body
condition: $.access_token != null
type: JSONPath
type: jsonpath
outputs:
code: $response.body.code # Not really, this is a query parameter

Expand All @@ -171,7 +171,7 @@ workflows:
- condition: $statusCode == 200
- context: $response.body
condition: $.access_token != null
type: JSONPath
type: jsonpath
outputs:
access_token: $response.body.access_token
refresh_token: $response.body.refresh_token
Expand Down
28 changes: 14 additions & 14 deletions versions/1.0.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,14 +210,14 @@ version: 1.0.1

Describes a source description (such as an OpenAPI description) that will be referenced by one or more workflows described within an Arazzo Description.

An object storing a map between named description keys and location URLs to the source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. Each source location `string` MUST be in the form of a URI-reference as defined by [RFC3986 section 4.1](https://datatracker.ietf.org/doc/html/rfc3986#section-4.1).
An object storing a map between named description keys and location URLs to the source descriptions (such as an OpenAPI description) this Arazzo Description SHALL apply to. Each source location `string` MUST be in the form of a URI-reference as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.1).

##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="sourceName"></a>name | `string` | **REQUIRED**. A unique name for the source description. Tools and libraries MAY use the `name` to uniquely identify a source description, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`.
<a name="sourceURL"></a>url | `string` | **REQUIRED**. A URL to a source description to be used by a workflow. If a relative reference is used, it MUST be in the form of a URI-reference as defined by [RFC3986 section 4.2](https://datatracker.ietf.org/doc/html/rfc3986#section-4.2).
<a name="sourceURL"></a>url | `string` | **REQUIRED**. A URL to a source description to be used by a workflow. If a relative reference is used, it MUST be in the form of a URI-reference as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
<a name="sourceType"></a>type | `string` | The type of source description. Possible values are `"openapi"` or `"arazzo"`.


Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -439,7 +439,7 @@ criteria:
# assertions to determine if this success action should be executed
- context: $response.body
condition: $[?count(@.pets) > 0]
type: JSONPath
type: jsonpath
```

#### Failure Action Object
Expand All @@ -456,7 +456,7 @@ Field Name | Type | Description
<a name="failureActionType"></a> type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`.
<a name="failureWorkflowId"></a> 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.<name>.<workflowId>`) 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.
<a name="failureStepId"></a> 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.
<a name="failureRetryAfter"></a> 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://www.rfc-editor.org/rfc/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"`.
<a name="failureRetryAfter"></a> 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"`.
<a name="failureRetryLimit"></a> 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.
<a name="failureCriteria"></a> 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).

Expand Down Expand Up @@ -585,6 +585,7 @@ A simple object to allow referencing of objects contained within the [Components
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="reusableObjectReference"></a>reference | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired object.
<a name="reusableObjectValue"></a>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.
Expand Down Expand Up @@ -620,7 +621,7 @@ An object used to specify the context, conditions, and condition types that can
There are four flavors of conditions supported:
- simple - where basic literals, operators, and loose comparisons are used in combination with [Runtime Expressions](#runtime-expressions).
- regex - where a regex pattern is applied on the supplied context. The context is defined by a [Runtime Expression](#runtime-expressions).
- jsonpath - where a JSON Path expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions).
- jsonpath - where a JSONPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions).
- xpath - where an XPath expression is applied. The root node context is defined by a [Runtime Expression](#runtime-expressions).

##### Literals
Expand Down Expand Up @@ -655,8 +656,8 @@ String comparisons `MUST` be case insensitive.
Field Name | Type | Description
---|:---:|---
<a name="criterionContext"></a>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).
<a name="criterionCondition"></a>condition | `string` | **REQUIRED**. The condition to apply. Conditions can be simple (e.g. `$statusCode == 200` which applies a operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex and [JSONPath](https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base/21/), the `type` and `context` MUST be specified.
<a name="criterionType"></a>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 [JSON Path](https://www.rfc-editor.org/rfc/rfc9535.html). If `xpath` the expression MUST conform to [XML Path Language 3.1](https://www.w3.org/TR/xpath-31/#d2e24229). Should other variants of JSON Path or XPath be required, then a [Criterion Expression Type Object](#criterion-expression-type-object) MUST be specified.
<a name="criterionCondition"></a>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.
<a name="criterionType"></a>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.


This object MAY be extended with [Specification Extensions](#specification-extensions).
Expand Down Expand Up @@ -686,22 +687,22 @@ This object MAY be extended with [Specification Extensions](#specification-exten
#### Criterion Expression Type Object

An object used to describe the type and version of an expression used within a [Criterion Object](#criterion-object). If this object is not defined, then the following defaults apply:
- JSON Path as described by [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535.html)
- JSONPath as described by [RFC9535](https://tools.ietf.org/html/rfc9535)
- XPath as described by [XML Path Language 3.1](https://www.w3.org/TR/xpath-31)

Defining this object gives the ability to utilize tooling compatible with older versions of either JSON Path or XPath.
Defining this object gives the ability to utilize tooling compatible with older versions of either JSONPath or XPath.

##### Fixed Fields
Field Name | Type | Description
---|:---:|---
<a name="criterionExpressionType"></a>type | `string` | **REQUIRED**. The type of condition to be applied. The options allowed are `jsonpath` or `xpath`.
<a name="criterionExpressionVersion"></a>version | `string` | **REQUIRED**. A short hand string representing the version of the expression type being used. The allowed values for JSON Path are `draft-goessner-dispatch-jsonpath-00`. The allowed values for XPath are `xpath-30`, `xpath-20`, or `xpath-10`.
<a name="criterionExpressionVersion"></a>version | `string` | **REQUIRED**. A short hand string representing the version of the expression type being used. The allowed values for JSONPath are `draft-goessner-dispatch-jsonpath-00`. The allowed values for XPath are `xpath-30`, `xpath-20`, or `xpath-10`.

This object MAY be extended with [Specification Extensions](#specification-extensions).

##### Criterion Expression Type Example

**JSON Path Example**
**JSONPath Example**
```yaml
type: jsonpath
version: draft-goessner-dispatch-jsonpath-00
Expand All @@ -722,7 +723,6 @@ Field Name | Type | Description
---|:---:|---
<a name="requestBodyContentType"></a>contentType | `string` | The Content-Type for the request content. If omitted then refer to Content-Type specified at the targeted operation to understand serialization requirements.
<a name="requestBodyPayload"></a>payload | Any | A value representing the request body payload. The value can be a literal value or can contain [Runtime Expressions](#runtime-expressions) which MUST be evaluated prior to calling the referenced operation. To represent examples of media types that cannot be naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.

<a name="requestBodyReplacements"></a>replacements | [[Payload Replacement Object](#payload-replacement-object)] | A list of locations and values to set within a payload.

This object MAY be extended with [Specification Extensions](#specification-extensions).
Expand Down Expand Up @@ -879,7 +879,7 @@ The extensions may or may not be supported by the available tooling, but those m

The Arazzo Specification does not enforce a security mechanism. Security is left to the implementer, though TLS, specifically HTTPS may be recommended for exchanging sensitive workflows.

Arazzo Descriptions can be JSON or YAML values. As such, all security considerations defined in [RFC 8259](https://www.rfc-editor.org/info/rfc8259) and within YAML version [1.2](https://yaml.org/spec/1.2/spec.html) apply.
Arazzo Descriptions can be JSON or YAML values. As such, all security considerations defined in [RFC8259](https://tools.ietf.org/html/rfc8259) and within YAML version [1.2](https://yaml.org/spec/1.2/spec.html) apply.

Arazzo Descriptions are frequently written by untrusted third parties, to be deployed on public Internet servers. Processing an Arazzo Description can cause both safe and unsafe operations to be performed on arbitrary network resources. It is the responsibility of the description consumer to ensure that the operations performed are not harmful.

Expand Down

0 comments on commit 6edb1ae

Please sign in to comment.