Workflows Specification

Version 1.0.0-prerelease

Work is progressing well on this specification. Formally, we are still in a prerelease status

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

This document is licensed under The Apache License, Version 2.0.

Introduction

Being able to express specific sequences of calls and articulate the dependencies between them to achieve a particular goal is desirable in the context of API descriptions. The aim of the Workflows Specification is to provide a mechanism that can define sequences of calls and their dependencies to be expressed in the context of delivering a particular outcome or set of outcomes when dealing with API descriptions (such as OpenAPI descriptions).

The Workflows Specification can articulate these workflows in a human-readable and machine-readable manner, thus improving the capability of API specifications to tell the story of the API in a manner that can improve the consuming developer experience.

Definitions

Workflows 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). A Workflows Description (WD) uses and conforms to the Workflows Specification, and MUST contain a valid Workflows Specification version field (workflowsSpec), an Info field, a sourceDescriptions field with at least one defined Source, and there MUST be at least one Workflow defined in the workflows fixed field.

Specification

Versions

The Workflows Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 1.0) SHALL designate the Workflows feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. The patch version SHOULD NOT be considered by tooling, making no distinction between 1.0.0 and 1.0.1 for example.

Format

A Workflows Description that conforms to the Workflows Specification is itself a JSON object, which may be represented either in JSON or YAML format.

All field names in the specification are case sensitive. This includes all fields that are used as keys in a map, except where explicitly noted that keys are case insensitive.

In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints:

Tags MUST be limited to those allowed by the JSON Schema ruleset.
Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.

Workflows Description Structure

It is RECOMMENDED that the entry Workflows document be named: workflows.json or workflows.yaml.

A Workflows Description MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, Reference Objects are used. In a multi-document description, the document containing the Workflows Specification Object is known as the entry Workflows document.

Data Types

Data types in the Workflows Specification are based on the types supported by the JSON Schema Specification Draft 2020-12. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part.

As defined by the JSON Schema Validation vocabulary, data types can have an optional modifier property: format. Workflows additionally supports the formats (similar to the OpenAPI specification) to provide fine detail for primitive data types.

The formats defined are:

`type`	`format`	Comments
`integer`	`int32`	signed 32 bits
`integer`	`int64`	signed 64 bits (a.k.a long)
`number`	`float`
`number`	`double`
`string`	`password`	A hint to UIs to obscure input.

Relative References in URLs

Unless specified otherwise, all properties that are URLs MAY be relative references as defined by RFC3986. Unless specified otherwise, relative references are resolved using the URL of the referring document.

Schema

In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.

Workflows Specification Object

This is the root object of the Workflows Description.

Fixed Fields

Field Name	Type	Description
workflowsSpec	`string`	REQUIRED. This string MUST be the version number of the Workflows Specification that the Workflows Description uses. The `workflowsSpec` field MUST be used by tooling to interpret the Workflows Description.
info	Info Object	REQUIRED. Provides metadata about the Workflows. The metadata MAY be used by tooling as required.
sourceDescriptions	[Source Description Object]	REQUIRED. A list of source descriptions (such as an OpenAPI description) this workflow SHALL apply to. The list MUST have at least one entry.
workflows	[Workflow Object]	REQUIRED. A list of workflows. The list MUST have at least one entry.
components	Components Object	An element to hold various schemas for the Workflows Description.

This object MAY be extended with Specification Extensions.

Workflows Specification Object Example

workflowsSpec: 1.0.0-prerelease
info:
  title: A pet purchasing workflow
  summary: This workflow showcases how to purchase a pet through a sequence of API calls
  description: |
      This workflow walks you through the steps of `searching` for, `selecting`, and `purchasing` an available pet.
  version: 1.0.1
sourceDescriptions:
- name: petStoreDescription
  url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
  type: openapi

workflows:
- workflowId: loginUserAndRetrievePet
  summary: Login User and then retrieve pets
  description: This workflow lays out the steps to login a user and then retrieve pets
  inputs:
      type: object
      properties:
          username:
              type: string
          password:
              type: string
  steps:
  - stepId: loginStep
    description: This step demonstrates the user login step
    operationId: loginUser
    parameters:
      # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
      - name: username
        in: query
        value: $inputs.username
      - name: password
        in: query
        value: $inputs.password
    successCriteria:
      # assertions to determine step was successful
      - condition: $statusCode == 200
    outputs:
      # outputs from this step
      tokenExpires: $response.header.X-Expires-After
      rateLimit: $response.header.X-Rate-Limit
      sessionToken: $response.body
  - stepId: getPetStep
    description: retrieve a pet by status from the GET pets endpoint
    operationRef: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml#/paths/~1pet~1findByStatus/get
    dependsOn: loginStep
    parameters:
      - name: status
        in: query
        value: 'available'
      - name: Authorization
        in: header
        value: $steps.loginUser.outputs.sessionToken
    successCriteria:
      - condition: $statusCode == 200
    outputs:
      # outputs from this step
      availablePets: $response.body
  outputs:
      available: $steps.getPetStep.availablePets

Info Object

The object provides metadata about the API Workflows defined in this document. The metadata MAY be used by the clients if needed.

Fixed Fields

Field Name	Type	Description
title	`string`	REQUIRED. A human readable title of the Workflows Description.
summary	`string`	A short summary of the Workflows Description.
description	`string`	A description of the purpose of the workflows defined. CommonMark syntax MAY be used for rich text representation.
version	`string`	REQUIRED. The version identifier of the Workflows document (which is distinct from the Workflows Specification version.

This object MAY be extended with Specification Extensions.

Info Object Example

title: A pet purchasing workflow
summary: This workflow showcases how to purchase a pet through a sequence of API calls
description: |
    This workflow walks you through the steps of searching for, selecting, and purchasing an available pet.
version: 1.0.1

Source Description Object

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

An object storing a map between named description keys and location URLs to the source descriptions (such as an OpenAPI description) this workflow SHALL apply to. Each source location string MUST be in the form of a URL. MAY be defined using relative references as defined by RFC3986.

Fixed Fields

Field Name	Type	Description
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_\-]+`.
url	`string`	REQUIRED. A URL to a source description to be used by a Workflow. MUST be in the form of a URL. MAY be defined using relative references as defined by RFC3986.
type	`string`	The type of source description. Possible values are `"openapi"` or `"workflowsSpec"`.

This object MAY be extended with Specification Extensions.

Source Description Object Example

name: petStoreDescription
url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
type: openapi

Workflow Object

Describes the steps to be taken across one or more APIs to achieve an objective. The workflow object MAY define inputs needed in order to execute workflow steps, where the defined steps represent a call to an API operation or another workflow, and a set of outputs.

Fixed Fields

Field Name	Type	Description
workflowId	`string`	REQUIRED. Unique string to represent the workflow. The id MUST be unique amongst all workflows describe in the Workflows Description. The `workflowId` value is case-sensitive. Tools and libraries MAY use the `workflowId` to uniquely identify a workflow, therefore, it is RECOMMENDED to follow common programming naming conventions. SHOULD conform to the regular expression `[A-Za-z0-9_\-]+`.
summary	`string`	A summary of the purpose or objective of the workflow.
description	`string`	A description of the workflow. CommonMark syntax MAY be used for rich text representation.
inputs	`JSON Schema`	A JSON Schema 2020-12 object representing the input parameters used by this workflow.
steps	[Step Object]	REQUIRED. An ordered list of steps where each step represents a call to an API operation or to another workflow.
outputs	Map[`string`, {expression}]	A map between a friendly name and a dynamic output value. The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.

This object MAY be extended with Specification Extensions.

Workflow Object Example

workflowId: loginUser
summary: Login User
description: This workflow lays out the steps to login a user
inputs:
    type: object
    properties:
        username:
            type: string
        password:
            type: string
steps:
  - stepId: loginStep
    description: This step demonstrates the user login step
    operationId: loginUser
    parameters:
      # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
      - name: username
        in: query
        value: $inputs.username
      - name: password
        in: query
        value: $inputs.password
    successCriteria:
        # assertions to determine step was successful 
        - condition: $statusCode == 200
    outputs:
        # outputs from this step
        tokenExpires: $response.header.X-Expires-After
        rateLimit: $response.header.X-Rate-Limit
outputs:
    tokenExpires: $steps.loginStep.outputs.tokenExpires

Step Object

Describes a single workflow step which MAY be a call to an API operation (OpenAPI Operation Object or another Workflow Object.

Fixed Fields

Field Name	Type	Description
description	`string`	A description of the step. CommonMark syntax 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 `workflowsSpec` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a runtime expression (e.g., `$sourceDescriptions.<name>.<operationId>`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationRef` and `workflowId` fields respectively.
operationRef	`string`	A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. A complete URI Template SHOULD be used. The operation being referenced MUST be described within one of the `source` descriptions.
workflowId	`string`	The workflowId referencing an existing workflow within the Workflows Description. If multiple `workflowsSpec` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a runtime expression (e.g., `$sourceDescriptions.<name>.<workflowId>`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationRef` fields respectively.
parameters	[Parameter Object \| Reference Object]	A list of parameters to pass to an operation or workflow as referenced by `operationId`, `operationRef`, or `workflowId`. If a Reference Object is provided, it MUST link to parameters defined in components/parameters.
dependsOn	[`string`]	A list of steps that MUST be completed before this step can be processed. This helps to ensure workflow steps are executed in the correct order and that dependent steps are not processed in parallel. The values provided MUST be the be the `stepId` which uniquely references a step.
successCriteria	[Criterion Object]	A list of assertions to determine the success of the step. Each assertion is described using a Criterion Object. All assertions `MUST` be satisfied for the step to be deemed successful.
onSuccess	[Success Action 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.
onFailure	[Failure Action 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.
outputs	Map[`string`, {expression}]	A map between a friendly name and a dynamic output value defined using a runtime expression. The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.

This object MAY be extended with Specification Extensions.

Step Object Example

Single step

stepId: loginStep
description: This step demonstrates the user login step
operationId: loginUser
parameters:
    # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
    - name: username
      in: query
      value: $inputs.username
    - name: password
      in: query
      value: $inputs.password
successCriteria:
    # assertions to determine step was successful
    - condition: $statusCode == 200
outputs:
    # outputs from this step
    tokenExpires: $response.header.X-Expires-After
    rateLimit: $response.header.X-Rate-Limit

Multiple steps

steps:
  - stepId: loginStep
    description: This step demonstrates the user login step
    operationId: loginUser
    parameters:
        # parameters to inject into the loginUser operation (parameter name must be resolvable at the referenced operation and the value is determined using {expression} syntax)
      - name: username
        in: query
        value: $inputs.username
      - name: password
        in: query
        value: $inputs.password
    successCriteria:
        # assertions to determine step was successful
      - condition: $statusCode == 200
    outputs:
        # outputs from this step
        tokenExpires: $response.header.X-Expires-After
        rateLimit: $response.header.X-Rate-Limit
        sessionToken: $response.body
  - stepId: getPetStep
    description: retrieve a pet by status from the GET pets endpoint
    operationRef: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml#/paths/~1pet~1findByStatus/get
    parameters:
      - name: status
        in: query
        value: 'available'
      - name: Authorization
        in: header
        value: $steps.loginUser.outputs.sessionToken
    successCriteria:
      - condition: $statusCode == 200
    outputs:
        # outputs from this step
        availablePets: $response.body

Parameter Object

Describes a single step parameter. A unique parameter is defined by the combination of a name and in fields. There are five possible locations specified by the in field:

path - Used together with OpenAPI style 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 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the source API.
body - The request, message or form body to be sent to the referenced operation.

Fixed Fields

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.
style	`string`	Describes how the parameter value will be serialized depending on the location of parameter value. This fixed field is predominately used to express how a request body is to be serialized. For example, when request data (`in` with value `"body"`) is to be serialized as `x-www-form-urlencoded`, the style SHOULD be `"form"`. `in` parameters with values of `"query"`, `"header"`, or `"cookie"` MUST derive their style from the referenced `sourceDescriptions` operation when applicable.
target	`string`	A JSON Pointer which MUST be resolved against the request body. Used to identify the location to inject the `value`.
value	Any \| {expression}	REQUIRED. The value to pass in the parameter. The value can be a constant or an expression to be evaluated and passed to the referenced operation or workflow.

This object MAY be extended with Specification Extensions.

Parameter Object Example

Query Example

- name: username
  in: query
  value: $inputs.username

Encoded Body Example

- name: client_id
  in: body
  style: form
  value: $inputs.clientId
- name: grant_type
  in: body
  style: form
  value: authorization_code
- name: redirect_uri
  in: body
  style: form
  value: $inputs.redirectUri
- name: client_secret
  in: body
  style: form
  value: $inputs.clientSecret
- name: code
  in: body
  style: form
  value: $steps.browser-authorize.outputs.code
- name: scope
  in: body
  style: form
  value: $inputs.scope

Success Action Object

A single success action which describes an action to take upon success of a workflow step. There are two possible values for the type field.

end - The workflow ends, and context returns to the caller with applicable outputs
goto - A one-way transfer of workflow control to the specified label (either a workflowId or stepId)

Fixed Fields

Field Name	Type	Description
type	`string`	REQUIRED. The type of action to take. Possible values are `"end"` or `"goto"`.
workflowId	`string`	The workflowId referencing an existing workflow within the Workflows Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If multiple `workflowsSpec` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a runtime expression (e.g., `$sourceDescriptions.<name>.<workflowId>`) 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]	A list of assertions to determine if this action SHALL be executed. Each assertion is described using a Criterion Object. All criteria assertions `MUST` be satisfied for the action to be executed.

This object MAY be extended with Specification Extensions.

Success Action Object Example

type: goto
stepId: joinWaitingListStep
criteria:
    # assertions to determine if this success action should be executed
    - context: $response.body
      condition: $.Pets.length() > 0
      type: JSONPath

Failure Action Object

A single failure action which describes an action to take upon failure of a workflow step. There are three possible values for the type field.

end - The workflow ends, and context returns to the caller with applicable outputs
retry - The current step will be retried. The retry will be constrained by the retryAfter and retryLimit fields. If a stepId or workflowId are specified, then the reference is executed and the context is returned, after which the current step is retried.
goto - A one-way transfer of workflow control to the specified label (either a workflowId or stepId)

Fixed Fields

Field Name	Type	Description
type	`string`	REQUIRED. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`.
workflowId	`string`	The workflowId referencing an existing workflow within the Workflows 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 `workflowsSpec` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a runtime expression (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.
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 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"`.
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]	A list of assertions to determine if this action SHALL be executed. Each assertion is described using a Criterion Object.

This object MAY be extended with Specification Extensions.

Failure Action Object Example

type: retry
retryAfter: 1
retryLimit: 5
criteria:
    # assertions to determine if this action should be executed
    - condition: $statusCode == 503

Components Object

Holds a set of reusable objects for different aspects of the Workflows Specification. All objects defined within the components object will have no effect on the workflow unless they are explicitly referenced from properties outside the components object.

Fixed Fields

Field Name	Type	Description
inputs	Map[`string`, `JSON Schema`]	An object to hold reusable JSON Schema objects to be referenced from workflow inputs.
parameters	Map[`string`, Parameter Object]	An object to hold reusable Parameter Objects

This object MAY be extended with Specification Extensions.

All the fixed fields declared above are objects that MUST use keys that match the regular expression: ^[a-zA-Z0-9\.\-_]+$. The key is used to refer to the input or parameter in other parts of the Workflow Description.

Field Name Examples:

User
User_1
User_Name
user-name
my.org.User

Components Object Example

components:
  parameters:
    storeId:
      name: storeId
      in: header
      value: $inputs.x-store-id
  inputs:
    pagination:
      type: object
      properties:
        page:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32

"components": {
  "parameters": {
    "storeId": {
      "name": "storeId",
      "in": "header",
      "value": "$inputs.x-store-id"
    }
  },
  "inputs": {
    "pagination": {
      "type": "object",
      "properties": {
        "page": {
          "type": "integer",
          "format": "int32"
        },
        "pageSize": {
          "type": "integer",
          "format": "int32"
        }
      }
    }
  }
}

Reference Object

A simple object to allow referencing other components in the Workflows Description.

Note - This section is derived from the OpenAPI Specification, and is intended to be implemented in similar fashion.

The $ref string value contains a URI RFC3986, which identifies the location of the value being referenced.

See the rules for resolving Relative References.

Fixed Fields

Field Name	Type	Description
$ref	`string`	REQUIRED. The reference identifier. This MUST be in the form of a URI.
value	`string`	A value by default MUST override that of the referenced component. If the referenced object-type does not have a `value` field, then it has no effect.

This object cannot be extended with additional properties and any properties added SHALL be ignored.

Reference Object Example

  $ref: "#/components/parameters/page"
  value: 1

  {
    "$ref": "#/components/parameters/page",
    "value": 1
  }

Criterion Object

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.

There are three flavors of conditions supported:

simple - where basic literals, operators, and loose comparisons are used in combination with Runtime Expressions.
regex - where a regex pattern is applied on the supplied context. The context is defined by a Runtime Expression.
JSONPath - where a JSONPath expression is applied. The root node context is defined by a Runtime Expression.

Literals

As part of a condition expression, you can use boolean, null, number, or string data types.

Type	Literal value
`boolean`	`true` or `false`
`null`	`null`
`number`	Any number format supported in Data Types
`string`	Strings MUST use single quotes (') around the string. To use a literal single quote, escape the literal single quote using an additional single quote ('').

Operators

Operator	Description
`<`	Less than
`<=`	Less than or equal
`>`	Greater than
`>=`	Greater than or equal
`==`	Equal
`!=`	Not equal
`!`	Not
`&&`	And
`\|\|`	Or
`()`	Logical Grouping
`[]`	Index (0-based)
`.`	Property de-reference

String comparisons MUST be case insensitive.

Fixed Fields

Field Name	Type	Description
context	`{expression}`	A runtime expression 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 a operator on a value obtained from a runtime expression), or a regex, or a JSONPath expression. For regex and JSONPath, the `type` and `context` MUST be specified.
type	`string`	The type of condition to be applied. If specified, the options allowed are `simple`, `regex` or `JSONPath`. If omitted, then the condition is assumed to be `simple`, which at most combines literals, operators and Runtime Expressions.

This object MAY be extended with Specification Extensions.

Criterion Object Example

Simple Condition Example

- condition: $statusCode == 200

Regex Condition Example

- context: $statusCode
  condition: '^200$'
  type: regex

JSONPath Condition Example

- context: $response.body
  condition: $[?length(@.pets) > 0]
  type: JSONPath

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 Workflows document such as workflows or steps.

The runtime expression is defined by the following ABNF syntax:

      expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$message." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name)
      source = ( header-reference / query-reference / path-reference / body-reference )
      header-reference = "header." token
      query-reference = "query." name
      path-reference = "path." name
      body-reference = "body" ["#" json-pointer ]
      json-pointer    = *( "/" reference-token )
      reference-token = *( unescaped / escaped )
      unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
         ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
      escaped         = "~" ( "0" / "1" )
        ; representing '~' and '/', respectively
      name = *( CHAR )
      token = 1*tchar
      tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
        "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA

Examples

Source Location	example expression	notes
HTTP Method	`$method`	The allowable values for the `$method` will be those for the HTTP operation.
Requested media type	`$request.header.accept`
Request parameter	`$request.path.id`	Request parameters MUST be declared in the `parameters` section of the parent operation or they cannot be evaluated. This includes request headers.
Request body property	`$request.body#/user/uuid`	In operations which accept payloads, references may be made to portions of the `requestBody` or the entire body.
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

Runtime expressions preserve the type of the referenced value. Expressions can be embedded into string values by surrounding the expression with {} curly braces.

Specification Extensions

While the Workflows Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

The extension properties are implemented as patterned fields that are always prefixed by "x-".

Field Pattern	Type	Description
^x-	Any	Allows extensions to the Workflows Specification. The field name MUST begin with `x-`, for example, `x-internal-id`. Field names beginning `x-oai-` and `x-oas-` are reserved for uses defined by the OpenAPI Initiative. The value MAY be `null`, a primitive, an array or an object.

The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).

Security Considerations

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

Workflows can be JSON or YAML values. As such, all security considerations defined in RFC 8259 and within YAML version 1.2 apply.

Workflows are frequently written by untrusted third parties, to be deployed on public Internet servers. Processing a workflow 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.

IANA Considerations

The proposed MIME media types for Workflows are described below.

application/vnd.oai.workflows

The default (or general) MIME type for Workflows is defined as follows:

Media type name: application

Media subtype name: vnd.oai.workflows

Required parameters: N/A

Optional parameters: version (e.g. version=1.0.0 to indicate that the type of workflow conforms to version 1.0.0 of the Workflows Specification).

Encoding considerations: Encoding considerations are identical to those specified for the application/json and application/yaml media types, respectively.

Security considerations: See security considerations above.

Interoperability considerations: N/A

Note: When using the application/vnd.oai.workflows media type the consumer should be prepared to receive YAML formatted content

application/vnd.oai.workflows+json

The proposed MIME media type for Workflows that require a JSON-specific media type is defined as follows:

Media type name: application

Media subtype name: vnd.oai.workflows+json

Required parameters: N/A

Optional parameters: version (e.g. version=1.0.0 to indicate that the type of workflow conforms to version 1.0.0 of the Workflows Specification).

Encoding considerations: Encoding considerations are identical to those specified for the application/json media type.

Security considerations: See security considerations above.

Interoperability considerations: N/A

application/vnd.oai.workflows+yaml

The proposed MIME media type for Workflows that require a YAML-specific media type is defined as follows:

Media type name: application

Media subtype name: vnd.oai.workflows+yaml

Required parameters: N/A

Optional parameters: version (e.g. version=1.0.0 to indicate that the type of workflow conforms to version 1.0.0 of the Workflows Specification).

Encoding considerations: Encoding considerations are identical to those specified for the application/yaml media type.

Security considerations: See security considerations above.

Interoperability considerations: N/A

Appendix A: Revision History

Version	Date	Notes
1.0.0	TBD	Not yet released

Appendix B: Contextual scope / access for inputs and outputs

This quick image is to add some context / scope access overview for inputs, step parameters, step outputs and workflow outputs

Files

1.0.0.md

Latest commit

History

1.0.0.md

File metadata and controls

Workflows Specification

Version 1.0.0-prerelease

Introduction

Table of Contents

Definitions

Workflows Description

Specification

Versions

Format

Workflows Description Structure

Data Types

Relative References in URLs

Schema

Workflows Specification Object

Fixed Fields

Workflows Specification Object Example

Info Object

Fixed Fields

Info Object Example

Source Description Object

Fixed Fields

Source Description Object Example

Workflow Object

Fixed Fields

Workflow Object Example

Step Object

Fixed Fields

Step Object Example

Parameter Object

Fixed Fields

Parameter Object Example

Success Action Object

Fixed Fields

Success Action Object Example

Failure Action Object

Fixed Fields

Failure Action Object Example

Components Object

Fixed Fields

Components Object Example

Reference Object

Fixed Fields

Reference Object Example

Criterion Object

Literals

Operators

Fixed Fields

Criterion Object Example

Runtime Expressions

Examples

Specification Extensions

Security Considerations

IANA Considerations

application/vnd.oai.workflows

application/vnd.oai.workflows+json

application/vnd.oai.workflows+yaml

Appendix A: Revision History

Appendix B: Contextual scope / access for inputs and outputs