Serverless Workflow DSL - Reference

Abstract
Definitions
- Workflow
  - Document
  - Use
  - Schedule
- Task
  - Call
    - AsyncAPI
    - gRPC
    - HTTP
    - OpenAPI
  - Do
  - Emit
  - For
  - Fork
  - Listen
  - Raise
  - Run
    - Container
    - Shell
    - Script
    - Workflow
  - Set
  - Switch
  - Try
  - Wait
- Flow Directive
- External Resource
- Authentication
  - Basic
  - Bearer
  - Certificate
  - Digest
  - OAUTH2
  - OpenIdConnect
- Catalog
- Extension
- Error
  - Standard Error Types
- Event Consumption Strategy
- Event Filter
- Event Properties
- Retry
- Input
- Output
- Export
- Timeout
- Duration
- Endpoint
- HTTP Response
- HTTP Request
- URI Template

Abstract

This document provides comprehensive definitions and detailed property tables for all the concepts discussed in the Serverless Workflow DSL. It serves as a reference guide, explaining the structure, components, and configurations available within the DSL. By exploring this document, users will gain a thorough understanding of how to define, configure, and manage workflows, including task definitions, flow directives, and state transitions. This foundational knowledge will enable users to effectively utilize the DSL for orchestrating serverless functions and automating processes.

Definitions

Workflow

A workflow serves as a blueprint outlining the series of tasks required to execute a specific business operation. It details the sequence in which tasks must be completed, guiding users through the process from start to finish, and helps streamline operations, ensure consistency, and optimize efficiency within an organization.

Properties

Name	Type	Required	Description
document	`document`	`yes`	Documents the defined workflow.
input	`input`	`no`	Configures the workflow's input.
use	`use`	`no`	Defines the workflow's reusable components, if any.
do	`map[string, task][]`	`yes`	The task(s) that must be performed by the workflow.
timeout	`string` `timeout`	`no`	The configuration, if any, of the workflow's timeout. If a `string`, must be the name of a timeout defined in the workflow's reusable components.
output	`output`	`no`	Configures the workflow's output.
schedule	`schedule`	`no`	Configures the workflow's schedule, if any.
evaluate	`evaluate`	`no`	Configures runtime expression evaluation.

Document

Documents the workflow definition.

Name	Type	Required	Description
dsl	`string`	`yes`	The version of the DSL used to define the workflow.
namespace	`string`	`yes`	The workflow's namespace.
name	`string`	`yes`	The workflow's name.
version	`string`	`yes`	The workflow's semantic version
title	`string`	`no`	The workflow's title.
summary	`string`	`no`	The workflow's Markdown summary.
tags	`map[string, string]`	`no`	A key/value mapping of the workflow's tags, if any.
metadata	`map`	`no`	Additional information about the workflow.

Use

Defines the workflow's reusable components.

Name	Type	Required	Description
authentications	`map[string, authentication]`	`no`	A name/value mapping of the workflow's reusable authentication policies.
catalogs	[`map[string, catalog]`(#catalog)]	`no`	A name/value mapping of the workflow's reusable resource catalogs.
errors	`map[string, error]`	`no`	A name/value mapping of the workflow's reusable errors.
extensions	`map[string, extension][]`	`no`	A list of the workflow's reusable extensions.
functions	`map[string, task]`	`no`	A name/value mapping of the workflow's reusable tasks.
retries	`map[string, retryPolicy]`	`no`	A name/value mapping of the workflow's reusable retry policies.
secrets	`string[]`	`no`	A list containing the workflow's secrets.
timeouts	`map[string, timeout]`	`no`	A name/value mapping of the workflow's reusable timeouts.

Schedule

Configures the schedule of a workflow.

Name	Type	Required	Description
every	`duration`	`no`	Specifies the duration of the interval at which the workflow should be executed. Unlike `after`, this option will run the workflow regardless of whether the previous run is still in progress. Required when no other property has been set.
cron	`string`	`no`	Specifies the schedule using a CRON expression, e.g., '0 0 * * ' for daily at midnight. Required when no other property has been set.*
after	`duration`	`no`	Specifies a delay duration that the workflow must wait before starting again after it completes. In other words, when this workflow completes, it should run again after the specified amount of time. Required when no other property has been set.
on	`eventConsumptionStrategy`	`no`	Specifies the events that trigger the workflow execution. Required when no other property has been set.

Evaluate

Configures a workflow's runtime expression evaluation.

Name	Type	Required	Description
language	`string`	`yes`	The language used for writting runtime expressions. Defaults to `jq`.
mode	`string`	`yes`	The runtime expression evaluation mode. Supported values are: - `strict`: requires all expressions to be enclosed within `${ }` for proper identification and evaluation. - `loose`: evaluates any value provided. If the evaluation fails, it results in a string with the expression as its content. Defaults to `strict`.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: order-pet
  version: '0.1.0'
  title: Order Pet - 1.0.0
  summary: >
    # Order Pet - 1.0.0
    ## Table of Contents
    - [Description](#description)
    - [Requirements](#requirements)
    ## Description
    A sample workflow used to process an hypothetic pet order using the [PetStore API](https://petstore.swagger.io/)
    ## Requirements
    ### Secrets
    - my-oauth2-secret
use:
  authentications:
    petStoreOAuth2:
      oauth2: 
        authority: https://petstore.swagger.io/.well-known/openid-configuration
        grant: client_credentials
        client:
          id: workflow-runtime
          secret: "**********"
        scopes: [ api ]
        audiences: [ runtime ]
  extensions:
    - externalLogging:
        extend: all
        before:
          - sendLog:
              call: http
              with:
                method: post
                endpoint: https://fake.log.collector.com
                body:
                  message: ${ "Executing task '\($task.reference)'..." }
        after:
          - sendLog:
              call: http
              with:
                method: post
                endpoint: https://fake.log.collector.com
                body:
                  message: ${ "Executed task '\($task.reference)'..." }
  functions:
    getAvailablePets:
      call: openapi
      with:
        document:
          endpoint: https://petstore.swagger.io/v2/swagger.json
        operationId: findByStatus
        parameters:
          status: available
  secrets:
    - my-oauth2-secret
do:
  - getAvailablePets:
      call: getAvailablePets
      output:
        as: "$input + { availablePets: [.[] | select(.category.name == \"dog\" and (.tags[] | .breed == $input.order.breed))] }"
  - submitMatchesByMail:
      call: http
      with:
        method: post
        endpoint:
          uri: https://fake.smtp.service.com/email/send
          authentication: 
            use: petStoreOAuth2
        body:
          from: noreply@fake.petstore.com
          to: ${ .order.client.email }
          subject: Candidates for Adoption
          body: >
            Hello ${ .order.client.preferredDisplayName }!

            Following your interest to adopt a dog, here is a list of candidates that you might be interested in:

            ${ .pets | map("-\(.name)") | join("\n") }

            Please do not hesistate to contact us at info@fake.petstore.com if your have questions.

            Hope to hear from you soon!

            ----------------------------------------------------------------------------------------------
            DO NOT REPLY
            ----------------------------------------------------------------------------------------------

Task

A task within a workflow represents a discrete unit of work that contributes to achieving the overall objectives defined by the workflow.

It encapsulates a specific action or set of actions that need to be executed in a predefined order to advance the workflow towards its completion.

Tasks are designed to be modular and focused, each serving a distinct purpose within the broader context of the workflow.

By breaking down the workflow into manageable tasks, organizations can effectively coordinate and track progress, enabling efficient collaboration and ensuring that work is completed in a structured and organized manner.

The Serverless Workflow DSL defines a list of tasks that must be supported by all runtimes:

Call, used to call services and/or functions.
Do, used to define one or more subtasks to perform in sequence.
Fork, used to define one or more subtasks to perform concurrently.
Emit, used to emit events.
For, used to iterate over a collection of items, and conditionally perform a task for each of them.
Listen, used to listen for an event or more.
Raise, used to raise an error and potentially fault the workflow.
Run, used to run a container, a script , a shell command or even another workflow.
Switch, used to dynamically select and execute one of multiple alternative paths based on specified conditions
Set, used to dynamically set or update the workflow's data during the its execution.
Try, used to attempt executing a specified task, and to handle any resulting errors gracefully, allowing the workflow to continue without interruption.
Wait, used to pause or wait for a specified duration before proceeding to the next task.

Properties

Name	Type	Required	Description
if	`string`	`no`	A `runtime expression`, if any, used to determine whether or not the task should be run. The task is considered skipped if not run, and the raw task input becomes the task's output. The expression is evaluated against the raw task input before any other expression of the task.
input	`input`	`no`	An object used to customize the task's input and to document its schema, if any.
output	`output`	`no`	An object used to customize the task's output and to document its schema, if any.
export	`export`	`no`	An object used to customize the content of the workflow context.
timeout	`string` `timeout`	`no`	The configuration of the task's timeout, if any. If a `string`, must be the name of a timeout defined in the workflow's reusable components.
then	`flowDirective`	`no`	The flow directive to execute next. If not set, defaults to `continue`.
metadata	`map`	`no`	Additional information about the task.

Call

Enables the execution of a specified function within a workflow, allowing seamless integration with custom business logic or external services.

Properties

Name	Type	Required	Description
call	`string`	`yes`	The name of the function to call.
with	`map`	`no`	A name/value mapping of the parameters to call the function with

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: call-example
  version: '0.1.0'
do:
  - getPet:
      call: http
      with:
        method: get
        endpoint: https://petstore.swagger.io/v2/pet/{petId}

Serverless Workflow defines several default functions that MUST be supported by all implementations and runtimes:

AsyncAPI
gRPC
HTTP
OpenAPI

AsyncAPI Call

The AsyncAPI Call enables workflows to interact with external services described by AsyncAPI.

Properties

Name	Type	Required	Description
document	`externalResource`	`yes`	The AsyncAPI document that defines the operation to call.
operationRef	`string`	`yes`	A reference to the AsyncAPI operation to call.
server	`string`	`no`	A reference to the server to call the specified AsyncAPI operation on. If not set, default to the first server matching the operation's channel.
message	`string`	`no`	The name of the message to use. If not set, defaults to the first message defined by the operation.
binding	`string`	`no`	The name of the binding to use. If not set, defaults to the first binding defined by the operation
payload	`any`	`no`	The operation's payload, as defined by the configured message
authentication	`string` `authentication`	`no`	The authentication policy, or the name of the authentication policy, to use when calling the AsyncAPI operation.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: asyncapi-example
  version: '0.1.0'
do:
  - findPet:
      call: asyncapi
      with:
        document:
          endpoint: https://fake.com/docs/asyncapi.json
        operationRef: findPetsByStatus
        server: staging
        message: getPetByStatusQuery
        binding: http
        payload:
          petId: ${ .pet.id }

gRPC Call

The gRPC Call enables communication with external systems via the gRPC protocol, enabling efficient and reliable communication between distributed components.

Properties

Name	Type	Required	Description
proto	`externalResource`	`yes`	The proto resource that describes the GRPC service to call.
service.name	`string`	`yes`	The name of the GRPC service to call.
service.host	`string`	`yes`	The hostname of the GRPC service to call.
service.port	`integer`	`no`	The port number of the GRPC service to call.
service.authentication	`authentication`	`no`	The authentication policy, or the name of the authentication policy, to use when calling the GRPC service.
method	`string`	`yes`	The name of the GRPC service method to call.
arguments	`map`	`no`	A name/value mapping of the method call's arguments, if any.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: grpc-example
  version: '0.1.0'
do:
  - greet:
      call: grpc
      with:
        proto: 
          endpoint: file://app/greet.proto
        service:
          name: GreeterApi.Greeter
          host: localhost
          port: 5011
        method: SayHello
        arguments:
          name: ${ .user.preferredDisplayName }

HTTP Call

The HTTP Call enables workflows to interact with external services over HTTP.

Properties

Name	Type	Required	Description
method	`string`	`yes`	The HTTP request method.
endpoint	`string`\|`endpoint`	`yes`	An URI or an object that describes the HTTP endpoint to call.
headers	`map`	`no`	A name/value mapping of the HTTP headers to use, if any.
body	`any`	`no`	The HTTP request body, if any.
query	`map[string, any]`	`no`	A name/value mapping of the query parameters to use, if any.
output	`string`	`no`	The http call's output format. Supported values are: - `raw`, which output's the base-64 encoded http response content, if any. - `content`, which outputs the content of http response, possibly deserialized. - `response`, which outputs the http response. Defaults to `content`.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: http-example
  version: '0.1.0'
do:
  - getPet:
      call: http
      with:
        method: get
        endpoint: https://petstore.swagger.io/v2/pet/{petId}

OpenAPI Call

The OpenAPI Call enables workflows to interact with external services described by OpenAPI.

Properties

Name	Type	Required	Description
document	`externalResource`	`yes`	The OpenAPI document that defines the operation to call.
operationId	`string`	`yes`	The id of the OpenAPI operation to call.
arguments	`map`	`no`	A name/value mapping of the parameters, if any, of the OpenAPI operation to call.
authentication	`authentication`	`no`	The authentication policy, or the name of the authentication policy, to use when calling the OpenAPI operation.
output	`string`	`no`	The OpenAPI call's output format. Supported values are: - `raw`, which output's the base-64 encoded http response content, if any. - `content`, which outputs the content of http response, possibly deserialized. - `response`, which outputs the http response. Defaults to `content`.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: openapi-example
  version: '0.1.0'
do:
  - findPet:
      call: openapi
      with:
        document: 
          endpoint: https://petstore.swagger.io/v2/swagger.json
        operationId: findPetsByStatus
        parameters:
          status: available

Do

Serves as a fundamental building block within workflows, enabling the sequential execution of multiple subtasks. By defining a series of subtasks to perform in sequence, the Do task facilitates the efficient execution of complex operations, ensuring that each subtask is completed before the next one begins.

Properties

Name	Type	Required	Description
do	`map[string, task][]`	`no`	The tasks to perform sequentially.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: do-example
  version: '0.1.0'
use:
  authentications:
    fake-booking-agency-oauth2:
      oauth2:
        authority: https://fake-booking-agency.com
        grant: client_credentials
        client:
          id: serverless-workflow-runtime
          secret: secret0123456789
do:
  - bookHotel:
      call: http
      with:
        method: post
        endpoint: 
          uri: https://fake-booking-agency.com/hotels/book
          authentication: 
            use: fake-booking-agency-oauth2
        body:
          name: Four Seasons
          city: Antwerp
          country: Belgium
  - bookFlight:
      call: http
      with:
        method: post
        endpoint: 
          uri: https://fake-booking-agency.com/flights/book
          authentication: 
            use: fake-booking-agency-oauth2
        body:
          departure:
            date: '01/01/26'
            time: '07:25:00'
            from:
              airport: BRU
              city: Zaventem
              country: Belgium
          arrival:
            date: '01/01/26'
            time: '11:12:00'
            to:
              airport: LIS
              city: Lisbon
              country: Portugal

Emit

Allows workflows to publish events to event brokers or messaging systems, facilitating communication and coordination between different components and services. With the Emit task, workflows can seamlessly integrate with event-driven architectures, enabling real-time processing, event-driven decision-making, and reactive behavior based on incoming events.

Properties

Name	Type	Required	Description
emit.event	`eventProperties`	`yes`	Defines the event to emit.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: emit-example
  version: '0.1.0'
do:
  - emitEvent:
      emit:
        event:
          with:
            source: https://petstore.com
            type: com.petstore.order.placed.v1
            data:
              client:
                firstName: Cruella
                lastName: de Vil
              items:
                - breed: dalmatian
                  quantity: 101

For

Allows workflows to iterate over a collection of items, executing a defined set of subtasks for each item in the collection. This task type is instrumental in handling scenarios such as batch processing, data transformation, and repetitive operations across datasets.

Properties

Name	Type	Required	Description
for.each	`string`	`no`	The name of the variable used to store the current item being enumerated. Defaults to `item`.
for.in	`string`	`yes`	A runtime expression used to get the collection to enumerate.
for.at	`string`	`no`	The name of the variable used to store the index of the current item being enumerated. Defaults to `index`.
while	`string`	`no`	A runtime expression that represents the condition, if any, that must be met for the iteration to continue.
do	`task`	`yes`	The task to perform for each item in the collection.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: for-example
  version: '0.1.0'
do:
  - checkup:
      for:
        each: pet
        in: .pets
        at: index
      while: .vet != null
      do:
        - waitForCheckup:
            listen:
              to:
                one:
                  with:
                    type: com.fake.petclinic.pets.checkup.completed.v2
            output:
              as: '.pets + [{ "id": $pet.id }]'

Fork

Allows workflows to execute multiple subtasks concurrently, enabling parallel processing and improving the overall efficiency of the workflow. By defining a set of subtasks to perform concurrently, the Fork task facilitates the execution of complex operations in parallel, ensuring that multiple tasks can be executed simultaneously.

Properties

Name	Type	Required	Description
fork.branches	`map[string, task][]`	`no`	The tasks to perform concurrently.
fork.compete	`boolean`	`no`	Indicates whether or not the concurrent `tasks` are racing against each other, with a single possible winner, which sets the composite task's output. Defaults to `false`.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: fork-example
  version: '0.1.0'
do:
  - raiseAlarm:
      fork:
        compete: true
        branches:
          - callNurse:
              call: http
              with:
                method: put
                endpoint: https://fake-hospital.com/api/v3/alert/nurses
                body:
                  patientId: ${ .patient.fullName }
                  room: ${ .room.number }
          - callDoctor:
              call: http
              with:
                method: put
                endpoint: https://fake-hospital.com/api/v3/alert/doctor
                body:
                  patientId: ${ .patient.fullName }
                  room: ${ .room.number }

Listen

Provides a mechanism for workflows to await and react to external events, enabling event-driven behavior within workflow systems.

Properties

Name	Type	Required	Description
listen.to	`eventConsumptionStrategy`	`yes`	Configures the event(s) the workflow must listen to.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: listen-example
  version: '0.1.0'
do:
  - callDoctor:
      listen:
        to:
          any:
          - with:
              type: com.fake-hospital.vitals.measurements.temperature
              data:
                temperature: ${ .temperature > 38 }
          - with:
              type: com.fake-hospital.vitals.measurements.bpm
              data:
                temperature: ${ .bpm < 60 or .bpm > 100 }

Raise

Intentionally triggers and propagates errors. By employing the "Raise" task, workflows can deliberately generate error conditions, allowing for explicit error handling and fault management strategies to be implemented.

Properties

Name	Type	Required	Description
raise.error	`string` `error`	`yes`	Defines the error to raise. If a `string`, must be the name of an error defined in the workflow's reusable components.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: raise-example
  version: '0.1.0'
do:
  - processTicket:
      switch:
        - highPriority:
            when: .ticket.priority == "high"
            then: escalateToManager
        - mediumPriority:
            when: .ticket.priority == "medium"
            then: assignToSpecialist
        - lowPriority:
            when: .ticket.priority == "low"
            then: resolveTicket
        - default:
            then: raiseUndefinedPriorityError
  - raiseUndefinedPriorityError:
      raise:
        error:
          type: https://fake.com/errors/tickets/undefined-priority
          status: 400
          instance: /raiseUndefinedPriorityError
          title: Undefined Priority
  - escalateToManager:
      call: http
      with:
        method: post
        endpoint: https://fake-ticketing-system.com/tickets/escalate
        body:
          ticketId: ${ .ticket.id }
  - assignToSpecialist:
      call: http
      with:
        method: post
        endpoint: https://fake-ticketing-system.com/tickets/assign
        body:
          ticketId: ${ .ticket.id }
  - resolveTicket:
      call: http
      with:
        method: post
        endpoint: https://fake-ticketing-system.com/tickets/resolve
        body:
          ticketId: ${ .ticket.id }

Run

Provides the capability to execute external containers, shell commands, scripts, or workflows.

Properties

Name	Type	Required	Description
run.container	`container`	`no`	The definition of the container to run. Required if `script`, `shell` and `workflow` have not been set.
run.script	`script`	`no`	The definition of the script to run. Required if `container`, `shell` and `workflow` have not been set.
run.shell	`shell`	`no`	The definition of the shell command to run. Required if `container`, `script` and `workflow` have not been set.
run.workflow	`workflow`	`no`	The definition of the workflow to run. Required if `container`, `script` and `shell` have not been set.
await	`boolean`	`no`	Determines whether or not the process to run should be awaited for. Defaults to `true`.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: run-example
  version: '0.1.0'
do:
  - runContainer:
      run:
        container:
          image: fake-image

  - runScript:
      run:
        script:
          language: js
          code: >
            Some cool multiline script

  - runShell:
      run:
        shell:
          command: 'echo "Hello, ${ .user.name }"'

  - runWorkflow:
      run:
        workflow:
          namespace: another-one
          name: do-stuff
          version: '0.1.0'
          input: {}

Container Process

Enables the execution of external processes encapsulated within a containerized environment, allowing workflows to interact with and execute complex operations using containerized applications, scripts, or commands.

Properties

Name	Type	Required	Description
image	`string`	`yes`	The name of the container image to run
command	`string`	`no`	The command, if any, to execute on the container
ports	`map`	`no`	The container's port mappings, if any
volumes	`map`	`no`	The container's volume mappings, if any
environment	`map`	`no`	A key/value mapping of the environment variables, if any, to use when running the configured process

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: run-container-example
  version: '0.1.0'
do:
  - runContainer:
      run:
        container:
          image: fake-image

Script Process

Enables the execution of custom scripts or code within a workflow, empowering workflows to perform specialized logic, data processing, or integration tasks by executing user-defined scripts written in various programming languages.

Properties

Name	Type	Required	Description
language	`string`	`yes`	The language of the script to run
code	`string`	`no`	The script's code. Required if `source` has not been set.
source	externalResource	`no`	The script's resource. Required if `code` has not been set.
arguments	`map`	`no`	A list of the arguments, if any, of the script to run
environment	`map`	`no`	A key/value mapping of the environment variables, if any, to use when running the configured script process

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: run-script-example
  version: '0.1.0'
do:
  - runScript:
      run:
        script:
          language: js
          arguments:
            greetings: Hello, world!
          code: >
            console.log(greetings)

Shell Process

Enables the execution of shell commands within a workflow, enabling workflows to interact with the underlying operating system and perform system-level operations, such as file manipulation, environment configuration, or system administration tasks.

Properties

Name	Type	Required	Description
command	`string`	`yes`	The shell command to run
arguments	`map`	`no`	A list of the arguments of the shell command to run
environment	`map`	`no`	A key/value mapping of the environment variables, if any, to use when running the configured process

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: run-shell-example
  version: '0.1.0'
do:
  - runShell:
      run:
        shell:
          command: 'echo "Hello, ${ .user.name }"'

Workflow Process

Enables the invocation and execution of nested workflows within a parent workflow, facilitating modularization, reusability, and abstraction of complex logic or business processes by encapsulating them into standalone workflow units.

Properties

Name	Type	Required	Description
name	`string`	`yes`	The name of the workflow to run
version	`string`	`yes`	The version of the workflow to run. Defaults to `latest`
input	`any`	`no`	The data, if any, to pass as input to the workflow to execute. The value should be validated against the target workflow's input schema, if specified

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: run-workflow-example
  version: '0.1.0'
do:
  - startWorkflow:
      run:
        workflow:
          namespace: another-one
          name: do-stuff
          version: '0.1.0'
          input:
            foo: bar

Set

A task used to set data.

Properties

Name	Type	Required	Description
set	`object`	`yes`	A name/value mapping of the data to set.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: default
  name: set-example
  version: '0.1.0'
do:
  - setShape:
      set:
        shape: circle
        size: ${ .configuration.size }
        fill: ${ .configuration.fill }

Switch

Enables conditional branching within workflows, allowing them to dynamically select different paths based on specified conditions or criteria

Properties

Name	Type	Required	Description
switch	`case[]`	`yes`	A name/value map of the cases to switch on

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: switch-example
  version: '0.1.0'
do:
  - processOrder:
      switch:
        - case1:
            when: .orderType == "electronic"
            then: processElectronicOrder
        - case2:
            when: .orderType == "physical"
            then: processPhysicalOrder
        - default:
            then: handleUnknownOrderType
  - processElectronicOrder:
      do:
        - validatePayment:
            call: http
            with:
              method: post
              endpoint: https://fake-payment-service.com/validate
        - fulfillOrder:
            call: http
            with:
              method: post
              endpoint: https://fake-fulfillment-service.com/fulfill
      then: exit
  - processPhysicalOrder:
      do:
        - checkInventory:
            call: http
            with:
              method: get
              endpoint: https://fake-inventory-service.com/inventory
        - packItems:
            call: http
            with:
              method: post
              endpoint: https://fake-packaging-service.com/pack
        - scheduleShipping:
            call: http
            with:
              method: post
              endpoint: https://fake-shipping-service.com/schedule
      then: exit
  - handleUnknownOrderType:
      do:
        - logWarning:
            call: http
            with:
              method: post
              endpoint: https://fake-logging-service.com/warn
        - notifyAdmin:
            call: http
            with:
              method: post
              endpoint: https://fake-notification-service.com/notify

Switch Case

Defines a switch case, encompassing a condition for matching and an associated action to execute upon a match.

Name	Type	Required	Description
when	`string`	`no`	A runtime expression used to determine whether or not the case matches. If not set, the case will be matched by default if no other case match. Note that there can be only one default case, all others MUST* set a condition.*
then	`flowDirective`	`yes`	The flow directive to execute when the case matches.

Try

Serves as a mechanism within workflows to handle errors gracefully, potentially retrying failed tasks before proceeding with alternate ones.

Properties

Name	Type	Required	Description
try	`map[string, task][]`	`yes`	The task(s) to perform.
catch	`catch`	`yes`	Configures the errors to catch and how to handle them.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: try-example
  version: '0.1.0'
do:
  - trySomething:
      try:
        - invalidHttpCall:
            call: http
            with:
              method: get
              endpoint: https://
      catch:
        errors:
          with:
            type: https://serverlessworkflow.io.io/dsl/errors/types/communication
            status: 503
        as: error
        retry:
          delay:
            seconds: 3
          backoff:
            exponential: {}
          limit:
            attempt:
              count: 5

Catch

Defines the configuration of a catch clause, which a concept used to catch errors.

Properties

Name	Type	Required	Description
errors	`errorFilter`	`no`	The definition of the errors to catch.
as	`string`	`no`	The name of the runtime expression variable to save the error as. Defaults to 'error'.
when	`string`	`no`	A runtime expression used to determine whether or not to catch the filtered error.
exceptWhen	`string`	`no`	A runtime expression used to determine whether or not to catch the filtered error.
retry	`string` `retryPolicy`	`no`	The `retry policy` to use, if any, when catching `errors`. If a `string`, must be the name of a retry policy defined in the workflow's reusable components.
do	`map[string, task][]`	`no`	The definition of the task(s) to run when catching an error.

Wait

Allows workflows to pause or delay their execution for a specified period of time.

Properties

Name	Type	Required	Description
wait	`string` `duration`	`yes`	The amount of time to wait. If a `string`, must be a valid ISO 8601 duration expression.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: wait-example
  version: '0.1.0'
do:
  - waitAWhile:
      wait:
        seconds: 10

Flow Directive

Flow Directives are commands within a workflow that dictate its progression.

Directive	Description
`"continue"`	Instructs the workflow to proceed with the next task in line. This action may conclude the execution of a particular workflow or branch if there are not task defined after the continue one.
`"exit"`	Halts the current branch's execution, potentially terminating the entire workflow if the current task resides within the main branch.
`"end"`	Provides a graceful conclusion to the workflow execution, signaling its completion explicitly.
`string`	Continues the workflow at the task with the specified name

External Resource

Defines an external resource.

Properties

Property	Type	Required	Description
name	`string`	`no`	The name, if any, of the defined resource.
endpoint	`endpoint`	`yes`	The endpoint at which to get the defined resource.

Examples

name: sample-resource
endpoint:
  uri: https://fake.com/resource/0123
  authentication:
    basic:
      username: admin
      password: 1234

Authentication

Defines the mechanism used to authenticate users and workflows attempting to access a service or a resource.

Properties

Property	Type	Required	Description
use	`string`	`no`	The name of the top-level authentication definition to use. Cannot be used by authentication definitions defined at top level.
basic	`basicAuthentication`	`no`	The `basic` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.
bearer	`bearerAuthentication`	`no`	The `bearer` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.
certificate	`certificateAuthentication`	`no`	The `certificate` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.
digest	`digestAuthentication`	`no`	The `digest` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.
oauth2	`oauth2`	`no`	The `oauth2` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.
oidc	`oidc`	`no`	The `oidc` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: authentication-example
  version: '0.1.0'
use:
  secrets:
    - usernamePasswordSecret
  authentications:
    sampleBasicFromSecret:
      basic:
        use: usernamePasswordSecret
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication:
            use: sampleBasicFromSecret

Basic Authentication

Defines the fundamentals of a 'basic' authentication.

Properties

Property	Type	Required	Description
username	`string`	`yes`	The username to use.
password	`string`	`yes`	The password to use.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: basic-authentication-example
  version: '0.1.0'
use:
  authentications:
    sampleBasic:
      basic:
        username: admin
        password: password123
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication: 
            use: sampleBasic

Bearer Authentication

Defines the fundamentals of a 'bearer' authentication

Properties

Property	Type	Required	Description
token	`string`	`yes`	The bearer token to use.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: bearer-authentication-example
  version: '0.1.0'
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication:
            bearer:
              token: ${ .user.token }

Certificate Authentication

Digest Authentication

Defines the fundamentals of a 'digest' authentication.

Properties

Property	Type	Required	Description
username	`string`	`yes`	The username to use.
password	`string`	`yes`	The password to use.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: digest-authentication-example
  version: '0.1.0'
use:
  authentications:
    sampleDigest:
      digest:
        username: admin
        password: password123
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication: 
            use: sampleDigest

OAUTH2 Authentication

Defines the fundamentals of an 'oauth2' authentication.

Properties

Name	Type	Required	Description
authority	`uri-template`	`yes`	The URI that references the authority to use when making OAuth2 calls.
endpoints.token	`uri-template`	`no`	The relative path to the endpoint for OAuth2 token requests. Defaults to `/oauth2/token`.
endpoints.revocation	`uri-template`	`no`	The relative path to the endpoint used to invalidate tokens. Defaults to `/oauth2/revoke`.
endpoints.introspection	`uri-template`	`no`	The relative path to the endpoint used to validate and obtain information about a token, typically to check its validity and associated metadata. Defaults to `/oauth2/introspect`.
grant	`string`	`yes`	The grant type to use. Supported values are `authorization_code`, `client_credentials`, `password`, `refresh_token` and `urn:ietf:params:oauth:grant-type:token-exchange`.
client.id	`string`	`no`	The client id to use. Required if the `client.authentication` method has not been set to `none`.
client.secret	`string`	`no`	The client secret to use, if any.
client.assertion	`string`	`no`	A JWT containing a signed assertion with your application credentials. Required when `client.authentication` has been set to `private_key_jwt`.
client.authentication	`string`	`no`	The client authentication method to use. Supported values are `client_secret_basic`, `client_secret_post`, `client_secret_jwt`, `private_key_jwt` or `none`. Defaults to `client_secret_post`.
request.encoding	`string`	`no`	The encoding of the token request. Supported values are `application/x-www-form-urlencoded` and `application/json`. Defaults to application/x-www-form-urlencoded.
issuers	`uri-template[]`	`no`	A list that contains that contains valid issuers that will be used to check against the issuer of generated tokens.
scopes	`string[]`	`no`	The scopes, if any, to request the token for.
audiences	`string[]`	`no`	The audiences, if any, to request the token for.
username	`string`	`no`	The username to use. Used only if the grant type is `Password`.
password	`string`	`no`	The password to use. Used only if the grant type is `Password`.
subject	`oauth2Token`	`no`	The security token that represents the identity of the party on behalf of whom the request is being made.
actor	`oauth2Token`	`no`	The security token that represents the identity of the acting party.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: oauth2-authentication-example
  version: '0.1.0'
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication:
            oauth2:
              authority: http://keycloak/realms/fake-authority
              endpoints:
                token: /oauth2/token
              grant: client_credentials
              client:
                id: workflow-runtime
                secret: "**********"
              scopes: [ api ]
              audiences: [ runtime ]

OAUTH2 Token

Represents the definition of an OAUTH2 token

Properties

Property	Type	Required	Description
token	`string`	`yes`	The security token to use to use.
type	`string`	`yes`	The type of security token to use.

OpenIdConnect Authentication

Defines the fundamentals of an 'oidc' authentication.

Properties

Name	Type	Required	Description
authority	`uri-template`	`yes`	The URI that references the authority to use when making OpenIdConnect calls.
grant	`string`	`yes`	The grant type to use. Supported values are `authorization_code`, `client_credentials`, `password`, `refresh_token` and `urn:ietf:params:oauth:grant-type:token-exchange`.
client.id	`string`	`no`	The client id to use. Required if the `client.authentication` method has not been set to `none`.
client.secret	`string`	`no`	The client secret to use, if any.
client.assertion	`string`	`no`	A JWT containing a signed assertion with your application credentials. Required when `client.authentication` has been set to `private_key_jwt`.
client.authentication	`string`	`no`	The client authentication method to use. Supported values are `client_secret_basic`, `client_secret_post`, `client_secret_jwt`, `private_key_jwt` or `none`. Defaults to `client_secret_post`.
request.encoding	`string`	`no`	The encoding of the token request. Supported values are `application/x-www-form-urlencoded` and `application/json`. Defaults to application/x-www-form-urlencoded.
issuers	`uri-template[]`	`no`	A list that contains that contains valid issuers that will be used to check against the issuer of generated tokens.
scopes	`string[]`	`no`	The scopes, if any, to request the token for.
audiences	`string[]`	`no`	The audiences, if any, to request the token for.
username	`string`	`no`	The username to use. Used only if the grant type is `Password`.
password	`string`	`no`	The password to use. Used only if the grant type is `Password`.
subject	`oauth2Token`	`no`	The security token that represents the identity of the party on behalf of whom the request is being made.
actor	`oauth2Token`	`no`	The security token that represents the identity of the acting party.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: oidc-authentication-example
  version: '0.1.0'
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication:
            oidc:
              authority: http://keycloak/realms/fake-authority/.well-known/openid-configuration
              grant: client_credentials
              client:
                id: workflow-runtime
                secret: "**********"
              scopes: [ api ]
              audiences: [ runtime ]

Catalog

A resource catalog is an external collection of reusable components, such as functions, that can be referenced and imported into workflows. Catalogs allow workflows to integrate with externally defined resources, making it easier to manage reuse and versioning across different workflows.

Each catalog is defined by an endpoint property, specifying the root URL where the resources are hosted, enabling workflows to access external functions and services. For portability, catalogs must adhere to a specific file structure, as defined here.

For more information about catalogs, refer to the Serverless Workflow DSL document.

Properties

Property	Type	Required	Description
endpoint	`endpoint`	`yes`	The endpoint that defines the root URL at which the catalog is located.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: catalog-example
  version: '0.1.0'
use:
  catalogs:
    global:
      endpoint:
        uri: https://github.com/serverlessworkflow/catalog
        authentication:
          basic:
            username: user
            password: '012345'
do:
  - log:
      call: log:0.5.2@global
      with:
        message: The cataloged custom function has been successfully called

Extension

Holds the definition for extending functionality, providing configuration options for how an extension extends and interacts with other components.

Extensions enable the execution of tasks prior to those they extend, offering the flexibility to potentially bypass the extended task entirely using an exit workflow directive.

Properties

Property	Type	Required	Description
extend	`string`	`yes`	The type of task to extend Supported values are: `call`, `composite`, `emit`, `extension`, `for`, `listen`, `raise`, `run`, `set`, `switch`, `try`, `wait` and `all`
when	`string`	`no`	A runtime expression used to determine whether or not the extension should apply in the specified context
before	`map[string, task][]`	`no`	The task to execute, if any, before the extended task
after	`map[string, task][]`	`no`	The task to execute, if any, after the extended task

Examples

Perform logging before and after any non-extension task is run:

document:
  dsl: '1.0.0-alpha5'
  namespace: test
  name: logging-extension-example
  version: '0.1.0'
use:
  extensions:
    - logging:
        extend: all
        before:
          - sendLog:
              call: http
              with:
                method: post
                endpoint: https://fake.log.collector.com
                body:
                  message: ${ "Executing task '\($task.reference)'..." }
        after:
          - sendLog:
              call: http
              with:
                method: post
                endpoint: https://fake.log.collector.com
                body:
                  message: ${ "Executed task '\($task.reference)'..." }
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: https://fake.com/sample

Intercept HTTP calls to 'https://mocked.service.com' and mock its response:

document:  
  dsl: '1.0.0-alpha5'
  namespace: test
  name: intercept-extension-example
  version: '0.1.0'
use:
  extensions:
    - mockService:
        extend: call
        when: $task.call == "http" and ($task.with.uri != null and ($task.with.uri | startswith("https://mocked.service.com"))) or ($task.with.endpoint.uri != null and ($task.with.endpoint.uri | startswith("https://mocked.service.com")))
        before:
          - intercept:
              set:
                statusCode: 200
                headers:
                  Content-Type: application/json
                content:
                  foo:
                    bar: baz
              then: exit #using this, we indicate to the workflow we want to exit the extended task, thus just returning what we injected
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: https://fake.com/sample

Error

Defines the Problem Details RFC compliant description of an error.

Properties

Property	Type	Required	Description
type	`uri-template`	`yes`	A URI reference that identifies the `error` type. For cross-compatibility concerns, it is strongly recommended to use Standard Error Types whenever possible. Runtimes MUST ensure that the property has been set when raising or escalating the `error`.
status	`integer`	`yes`	The status code generated by the origin for this occurrence of the `error`. For cross-compatibility concerns, it is strongly recommended to use HTTP Status Codes whenever possible. Runtimes MUST ensure that the property has been set when raising or escalating the `error`.
instance	`string`	`no`	A JSON Pointer used to reference the component the `error` originates from. Runtimes MUST set the property when raising or escalating the `error`. Otherwise ignore.
title	`string`	`no`	A short, human-readable summary of the `error`.
detail	`string`	`no`	A human-readable explanation specific to this occurrence of the `error`.

Examples

type: https://serverlessworkflow.io/spec/1.0.0/errors/communication
title: Service Not Available
status: 503

Standard Error Types

Standard error types serve the purpose of categorizing errors consistently across different runtimes, facilitating seamless migration from one runtime environment to another.

Type	Status¹	Description
https://serverlessworkflow.io/spec/1.0.0/errors/configuration	`400`	Errors resulting from incorrect or invalid configuration settings, such as missing or misconfigured environment variables, incorrect parameter values, or configuration file errors.
https://serverlessworkflow.io/spec/1.0.0/errors/validation	`400`	Errors arising from validation processes, such as validation of input data, schema validation failures, or validation constraints not being met. These errors indicate that the provided data or configuration does not adhere to the expected format or requirements specified by the workflow.
https://serverlessworkflow.io/spec/1.0.0/errors/expression	`400`	Errors occurring during the evaluation of runtime expressions, such as invalid syntax or unsupported operations.
https://serverlessworkflow.io/spec/1.0.0/errors/authentication	`401`	Errors related to authentication failures.
https://serverlessworkflow.io/spec/1.0.0/errors/authorization	`403`	Errors related to unauthorized access attempts or insufficient permissions to perform certain actions within the workflow.
https://serverlessworkflow.io/spec/1.0.0/errors/timeout	`408`	Errors caused by timeouts during the execution of tasks or during interactions with external services.
https://serverlessworkflow.io/spec/1.0.0/errors/communication	`500`	Errors encountered while communicating with external services, including network errors, service unavailable, or invalid responses.
https://serverlessworkflow.io/spec/1.0.0/errors/runtime	`500`	Errors occurring during the runtime execution of a workflow, including unexpected exceptions, errors related to resource allocation, or failures in handling workflow tasks. These errors typically occur during the actual execution of workflow components and may require runtime-specific handling and resolution strategies.

¹ Default value. The status code that best describe the error should always be used.

Event Consumption Strategy

Represents the configuration of an event consumption strategy.

Properties

Property	Type	Required	Description
all	`eventFilter[]`	`no`	Configures the workflow to wait for all defined events before resuming execution. Required if `any` and `one` have not been set.
any	`eventFilter[]`	`no`	Configures the workflow to wait for any of the defined events before resuming execution. Required if `all` and `one` have not been set.
one	`eventFilter`	`no`	Configures the workflow to wait for the defined event before resuming execution. Required if `all` and `any` have not been set.

Event Properties

An event object typically includes details such as the event type, source, timestamp, and unique identifier along with any relevant data payload. The Cloud Events specification, favored by Serverless Workflow, standardizes this structure to ensure interoperability across different systems and services.

Properties

Property	Type	Required	Description
id	`string`	`no`	Identifies the event. `source` + `id` is unique for each distinct event. Required when emitting an event using `emit.event.with`.
source	`string`	`no`	An URI formatted string, or runtime expression, that identifies the context in which an event happened. `source` + `id` is unique for each distinct event. Required when emitting an event using `emit.event.with`.
type	`string`	`no`	Describes the type of event related to the originating occurrence. Required when emitting an event using `emit.event.with`.
time	`string`	`no`	A string, or runtime expression, representing the timestamp of when the occurrence happened.
subject	`string`	`no`	Describes the subject of the event in the context of the event producer.
datacontenttype	`string`	`no`	Content type of `data` value. If omitted, it implies the `data` is a JSON value conforming to the "application/json" media type.
dataschema	`string`	`no`	An URI formatted string, or runtime expression, that identifies the schema that `data` adheres to.
data	`object`	`no`	The event payload.

Additional properties can be supplied, see the Cloud Events specification documentation for more info.

When used in an eventFilter, at least one property must be supplied.

Event Filter

An event filter is a mechanism used to selectively process or handle events based on predefined criteria, such as event type, source, or specific attributes.

Properties

Property	Type	Required	Description
with	`eventProperties`	`yes`	A name/value mapping of the attributes filtered events must define. Supports both regular expressions and runtime expressions.
correlate	`map[string, correlation]`	`no`	A name/definition mapping of the correlations to attempt when filtering events.

Correlation

A correlation is a link between events and data, established by mapping event attributes to specific data attributes, allowing for coordinated processing or handling based on event characteristics.

Properties

Property	Type	Required	Description
from	`string`	`yes`	A runtime expression used to extract the correlation value from the filtered event.
expect	`string`	`no`	A constant or a runtime expression, if any, used to determine whether or not the extracted correlation value matches expectations. If not set, the first extracted value will be used as the correlation's expectation.

Retry

The Retry is a fundamental concept in the Serverless Workflow DSL, used to define the strategy for retrying a failed task when an error is encountered during execution. This policy provides developers with fine-grained control over how and when to retry failed tasks, enabling robust error handling and fault tolerance within workflows.

Properties

Property	Type	Required	Description
when	`string`	`no`	A a runtime expression used to determine whether or not to retry running the task, in a given context.
exceptWhen	`string`	`no`	A runtime expression used to determine whether or not to retry running the task, in a given context.
limit	`retry`	`no`	The limits, if any, to impose to the retry policy.
backoff	`backoff`	`no`	The backoff strategy to use, if any.
jitter	`jitter`	`no`	The parameters, if any, that control the randomness or variability of the delay between retry attempts.

Retry Limit

The definition of a retry policy.

Property	Type	Required	Description
attempt.count	`integer`	`no`	The maximum attempts count.
attempt.duration	`duration`	`no`	The duration limit, if any, for all retry attempts.
duration	`duration`	`no`	The maximum duration, if any, during which to retry a given task.

Backoff

The definition of a retry backoff strategy.

Property	Type	Required	Description
constant	`object`	`no`	The definition of the constant backoff to use, if any. Required if `exponential` and `linear` are not set, otherwise ignored.
exponential	`object`	`no`	The definition of the exponential backoff to use, if any. Required if `constant` and `linear` are not set, otherwise ignored.
linear	`object`	`no`	The definition of the linear backoff to use, if any. Required if `constant` and `exponential` are not set, otherwise ignored.

Jitter

Represents the definition of the parameters that control the randomness or variability of a delay, typically between retry attempts

Property	Type	Required	Description
from	`duration`	`yes`	The minimum duration of the jitter range.
to	`duration`	`yes`	The maximum duration of the jitter range.

Examples

Input

Documents the structure - and optionally configures the transformation of - workflow/task input data.

It's crucial for authors to document the schema of input data whenever feasible. This documentation empowers consuming applications to provide contextual auto-suggestions when handling runtime expressions.

When set, runtimes must validate raw input data against the defined schema before applying transformations, unless defined otherwise.

Properties

Property	Type	Required	Description
schema	`schema`	`no`	The `schema` used to describe and validate raw input data. Even though the schema is not required, it is strongly encouraged to document it, whenever feasible.
from	`string` `object`	`no`	A runtime expression, if any, used to filter and/or mutate the workflow/task input.

Examples

schema:
  format: json
  document:
    type: object
    properties:
      order:
        type: object
        required: [ pet ]
        properties:
          pet:
            type: object
            required: [ id ]
            properties:
              id:
                type: string
from: .order.pet

Output

Documents the structure - and optionally configures the transformations of - workflow/task output data.

It's crucial for authors to document the schema of output data whenever feasible. This documentation empowers consuming applications to provide contextual auto-suggestions when handling runtime expressions.

When set, runtimes must validate output data against the defined schema after applying transformations, unless defined otherwise.

Properties

Property	Type	Required	Description
schema	`schema`	`no`	The `schema` used to describe and validate output data. Even though the schema is not required, it is strongly encouraged to document it, whenever feasible.
as	`string` `object`	`no`	A runtime expression, if any, used to filter and/or mutate the workflow/task output.

Examples

output:
  schema:
    format: json
    document:
      type: object
      properties:
        petId:
          type: string
      required: [ petId ]
  as:
    petId: '${ .pet.id }'

Export

Certain task needs to set the workflow context to save the task output for later usage. Users set the content of the context through a runtime expression. The result of the expression is the new value of the context. The expression is evaluated against the transformed task output.

Optionally, the context might have an associated schema which is validated against the result of the expression.

Properties

Property	Type	Required	Description
schema	`schema`	`no`	The `schema` used to describe and validate context. Included to handle the non frequent case in which the context has a known format.
as	`string` `object`	`no`	A runtime expression, if any, used to export the output data to the context.

Examples

Merge the task output into the current context.

as: '$context+.'

Replace the context with the task output.

as: '.'

Schema

Describes a data schema.

Properties

Property	Type	Required	Description
format	`string`	`yes`	The schema format. Supported values are: - `json`, which indicates the JsonSchema format.
document	`object`	`no`	The inline schema document. Required if `resource` has not been set, otherwise ignored.
resource	`externalResource`	`no`	The schema external resource. Required if `document` has not been set, otherwise ignored.

Examples

Example of an inline JsonSchema:

format: json
document:
  type: object
  properties:
    id:
      type: string
    firstName:
      type: string
    lastName:
      type: string
  required: [ id, firstName, lastName ]

Example of a JsonSchema based on an external resource:

format: json
resource:
  endpoint: https://test.com/fake/schema/json/document.json

Timeout

Defines a workflow or task timeout.

Properties

Property	Type	Required	Description
after	`duration`	`yes`	The duration after which the workflow or task times out.

Examples

document:
  dsl: '1.0.0-alpha5'
  namespace: default
  name: timeout-example
  version: '0.1.0'
do:
  - waitAMinute:
      wait:
        seconds: 60
timeout:
  after:
    seconds: 30

Duration

Defines a duration.

Properties

Property	Type	Required	Description
Days	`integer`	`no`	Number of days, if any.
Hours	`integer`	`no`	Number of hours, if any.
Minutes	`integer`	`no`	Number of minutes, if any.
Seconds	`integer`	`no`	Number of seconds, if any.
Milliseconds	`integer`	`no`	Number of milliseconds, if any.

Examples

Example of a duration of 2 hours, 15 minutes and 30 seconds:

hours: 2
minutes: 15
seconds: 30

Endpoint

Describes an enpoint.

Properties

Property	Type	Required	Description
uri	`string`	`yes`	The endpoint's URI.
authentication	`[authentication](#authentication)`	`no`	The authentication policy to use.

HTTP Response

Describes an HTTP response.

Properties

Property	Type	Required	Description
request	`request`	`yes`	The HTTP request associated with the HTTP response.
statusCode	`integer`	`yes`	The HTTP response status code.
headers	`map[string, string]`	`no`	The HTTP response headers, if any.
content	`any`	`no`	The HTTP response content, if any. If the request's content type is one of the following, should contain the deserialized response content. Otherwise, should contain the base-64 encoded response content, if any.

Examples

request:
  method: get
  uri: https://petstore.swagger.io/v2/pet/1
  headers:
    Content-Type: application/json
headers:
  Content-Type: application/json
statusCode: 200
content:
  id: 1
  name: milou
  status: pending

HTTP Request

Describes an HTTP request.

Properties

Property	Type	Required	Description
method	`string`	`yes`	The request's method.
uri	`uri`	`yes`	The request's URI.
headers	`map[string, string]`	`no`	The HTTP request headers, if any.

Examples

method: get
uri: https://petstore.swagger.io/v2/pet/1
headers:
  Content-Type: application/json

URI Template

The DSL has limited support for URI template syntax as defined by RFC 6570. Specifically, only the Simple String Expansion is supported, which allows authors to embed variables in a URI.

To substitute a variable within a URI, use the {} syntax. The identifier inside the curly braces will be replaced with its value during runtime evaluation. If no value is found for the identifier, an empty string will be used.

This has the following limitations compared to runtime expressions:

Only top-level properties can be interpolated within strings, thus identifiers are treated verbatim. This means that {pet.id} will be replaced with the value of the "pet.id" property, not the value of the id property of the pet property.
The referenced variable must be of type string, number, boolean, or null. If the variable is of a different type an error with type https://https://serverlessworkflow.io/spec/1.0.0/errors/expression and status 400 will be raised.
Runtime expression arguments are not available for string substitution.

Examples

uri: https://petstore.swagger.io/v2/pet/{petId}

Files

dsl-reference.md

Latest commit

History

dsl-reference.md

File metadata and controls

Serverless Workflow DSL - Reference

Table of Contents

Abstract

Definitions

Workflow

Properties

Document

Use

Schedule

Evaluate

Examples

Task

Properties

Call

Properties

Examples

AsyncAPI Call

Properties

Examples

gRPC Call

Properties

Examples

HTTP Call

Properties

Examples

OpenAPI Call

Properties

Examples

Do

Properties

Examples

Emit

Properties

Examples

For

Properties

Examples

Fork

Properties

Examples

Listen

Properties

Examples

Raise

Properties

Examples

Run

Properties

Examples

Container Process

Properties

Examples

Script Process

Properties

Examples

Shell Process

Properties

Examples

Workflow Process

Properties

Examples

Set

Properties

Examples

Switch

Properties

Examples

Switch Case

Try

Properties

Examples

Catch

Properties

Wait