OpenAPI Specification v1.0.0

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Status of This Document

The source-of-truth for the specification is the GitHub markdown file referenced above.

Workflows Specification

Version 1.0.0

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 an API definition(s). 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 definitions (such as OpenAPI documents).

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

Definitions

Workflows Document

A self-contained or composite resource which defines or describes API workflows (specific sequence of calls to achieve a particular goal in the context of an API definition). The workflows document MUST contain a valid Workflows Specification version field (workflowsSpec), an Info field, a sources field with at least one defined Source, and there MUST be at least one Workflow defined in the workflows fixed field. A Workflows document uses and conforms to the Workflows Specification.

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 document 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:

Document Structure

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

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 document.

Fixed Fields

Field Name Type Description
workflowsSpec string REQUIRED. This string MUST be the version number of the Workflows Specification that the Workflows document uses. The workflowsSpec field SHOULD be used by tooling to interpret the Workflows document.
info Info Object REQUIRED. Provides metadata about the Workflows. The metadata MAY be used by tooling as required.
sources [Source Object] REQUIRED. A list of source documents (such as an OpenAPI document) 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.

This object MAY be extended with Specification Extensions.

Workflows Specification Object Example


workflowsSpec: 1.0.0
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
sources:
- name: petStoreDefinition
  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
      - $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://petstore3.swagger.io/api/v3/openapi.json#/paths/users/~findbystatus~1{status}/get
    dependsOn: loginStep
    parameters:
      - name: status
        in: query
        value: 'available'
      - name: Authorization
        in: header
        value: $steps.loginUser.outputs.sessionToken
    successCriteria:
      - $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 document.
summary string A short summary of the Workflows document.
description string A description of the purpose of the Workflows document. CommonMark syntax MAY be used for rich text representation.
version string REQUIRED. A version identifier for indicating changes to 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 Object

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

An object storing a map between named document keys and location URLs to the source documents (such as an OpenAPI document) 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 document.
url string REQUIRED. A URL to a source document 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 document. Possible values are "openapi", "asyncapi", or "workflowsSpec".

This object MAY be extended with Specification Extensions.

Source Object Example


name: petStoreDefinition
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 document. 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.
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 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 (see open question 3 in Appendix B)
        $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 AsyncAPI 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 id SHOULD 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.
operationId string The name of an existing, resolvable operation, as defined with a unique operationId and existing within one of the source documents. The referenced operation will be invoked by this workflow step. If more than one source document is defined within a Workflows document, then the operationId specified MUST be prefixed with the source name 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. Relative operationRef values MAY be used to locate an existing. See OpenAPI relative reference resolution rules for guidance. A complete URI Template can also be used.
workflowId string The workflowId referencing an existing workflow within the Workflows document. The field is mutually exclusive of the operationId and operationRef fields respectively.
parameters [Parameter Object] A list of parameters to pass to an operation or workflow as referenced by operationId, operationRef, or workflowId.
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 [{expression}] A list of assertions to determine the success of the step
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.
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.
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
    $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
      - $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://petstore3.swagger.io/api/v3/openapi.json#/paths/users/~findbystatus~1{status}/get
    parameters:
      - name: status
        in: query
        value: 'available'
      - name: Authorization
        in: header
        value: $steps.loginUser.outputs.sessionToken
    successCriteria:
      - $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.
  • workflow - Parameters to be passed into a referenced workflow

Fixed Fields

Field Name Type Description
name string REQUIRED. The name of the parameter. Parameter names are case sensitive.
in string REQUIRED. The name location of the parameter. Possible values are "path", "query", "header", "cookie", "body", or "workflow".
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 source when applicable.
target {JSON Pointer} A JSON Pointer expression identifying locations to inject the value. Can be useful for targeting specific request body part.
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.

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

This object MAY be extended with Specification Extensions.

Success Action Object

A single success action which describes an action to take upon success of a workflow step.

Fixed Fields

Field Name Type Description
type string REQUIRED. The type of action to take. Possible values are "end" or "goto"
stepId string The stepId to jump to based on the success of the step. This field is only relevant when the type field value is goto. The value of the stepId MAY be within any workflow defined in the Workflows document. For convenience, the value MAY be formatted as workflowId.stepId.
criteria [{expression}] A list of assertions to determine if this action SHALL be executed.

Note - should multiple success actions have similar criteria, the first sequential action matching the criteria SHALL be the action executed.

Success Action Object Example


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

Failure Action Object

A single failure action which describes an action to take upon success of a workflow step.

Fixed Fields

Field Name Type Description
type string REQUIRED. The type of action to take. Possible values are "end", "goto" or "retry"
stepId string The stepId to jump to based on the failure of the step. This field is only relevant when the type field value is goto. The value of the stepId MAY be within any workflow defined in the Workflows document. For convenience, the value MAY be formatted as workflowId.stepId.
retryAfter number A non-negative decimal indicating the milliseconds 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.
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 [{expression}] A list of assertions to determine if this action SHALL be executed.

Note - should multiple success actions have similar criteria, the first sequential action matching the criteria SHALL be the action executed.

Failure Action Object Example


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

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)
      source = ( header-reference / query-reference / path-reference / body-reference / message-header-reference / message-payload-reference )
      header-reference = "header." token
      query-reference = "query." name
      path-reference = "path." name
      body-reference = "body" ["#" json-pointer ]
      message-header-reference = "header" ["#" json-pointer]
      message-payload-reference = "payload" ["#" 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).

Appendix A: Revision History

Version Date Notes
1.0.0 TBD First release of the Workflows Specification

Appendix B: Open Questions and Ideas

  1. What Expression syntax should be used? Initial framing leverages OpenAPI expression syntax as used by Link Object and extend to cover also AsyncAPI needs as well as workflow specific needs.
  2. For success criteria, JSONPath or JSON Pointer and/or custom evaluation rules (similar to GitHub action expressions)? Should we combine with runtime expressions or handle separately?

Appendix C: 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

Contextual Access Scope