The future of do and execute

[JBBianchi]

Context

As part of the discussions in issues #882 and #884, the inclusion and roles of the do and execute directives in our specification have become points of contention. This post aims to outline the various perspectives on this matter and invite the maintainers and community members to present their arguments for or against each option.

Options for Consideration:

1. Keep both do and execute

document:
  dsl: 1.0.0-alpha1
  namespace: default
  name: sample
  version: 1.0.0
do:
  for:
    each: guest
    in: .guests
  do:
    execute:
      sequentially:
        - bookFlight:
            call: http
            with: 'https://travel.com/book-flight/{guest}'
        - bookHotel:
            execute:
              concurrently:
                - bookRoom:
                    call: http
                    with: 'https://travel.com/book-room/{guest}'
                - bookBreakfast:
                    call: http
                    with: 'https://travel.com/book-breakfast/{guest}'

2. Retain only do

document:
  dsl: 1.0.0-alpha1
  namespace: default
  name: sample
  version: 1.0.0
do:
  for:
    each: guest
    in: .guests
  do:
    sequentially:
      - bookFlight:
          call: http
          with: 'https://travel.com/book-flight/{guest}'
      - bookHotel:
          concurrently:
            - bookRoom:
                call: http
                with: 'https://travel.com/book-room/{guest}'
            - bookBreakfast:
                call: http
                with: 'https://travel.com/book-breakfast/{guest}'

3. Remove "top-level" do and rename execute as do

document:
  dsl: 1.0.0-alpha1
  namespace: default
  name: sample
  version: 1.0.0
for:
  each: guest
  in: .guests
do:
  do:
    sequentially:
      - bookFlight:
          call: http
          with: 'https://travel.com/book-flight/{guest}'
      - bookHotel:
          do:
            concurrently:
              - bookRoom:
                  call: http
                  with: 'https://travel.com/book-room/{guest}'
              - bookBreakfast:
                  call: http
                  with: 'https://travel.com/book-breakfast/{guest}'

4. Remove both "top-level" do and execute

document:
  dsl: 1.0.0-alpha1
  namespace: default
  name: sample
  version: 1.0.0
for:
  each: guest
  in: .guests
do:
  sequentially:
    - bookFlight:
        call: http
        with: 'https://travel.com/book-flight/{guest}'
    - bookHotel:
        concurrently:
          - bookRoom:
              call: http
              with: 'https://travel.com/book-room/{guest}'
          - bookBreakfast:
              call: http
              with: 'https://travel.com/book-breakfast/{guest}'

5. Refactor execute (and maybe rename it as tasks)

document:
  dsl: 1.0.0-alpha1
  namespace: default
  name: sample
  version: 1.0.0
do:
  for:
    each: guest
    in: ".guests"
  do:
    execute: # or `tasks`
    - bookFlight:
        call: http
        with: https://travel.com/book-flight/{guest}
    - bookHotel:
        execute: # or `tasks`
        - bookRoom:
            call: http
            with: https://travel.com/book-room/{guest}
        - bookBreakfast:
            call: http
            with: https://travel.com/book-breakfast/{guest}
        in: parallel
        compete: false
    in: order

Engagement

We encourage all contributors to share their thoughts and insights on these options. Please provide your arguments, backed by examples or experiences, to help us make an informed decision. Requested reply format:

### 1. Keep both `do` and `execute`
#### Pro
<!-- your arguments for this option -->
#### Con
<!-- your arguments against this option -->

<!-- you can skip a point if you have nothing to fill -->
### 4. Remove both "top-level" `do` and `execute`
#### Con
<!-- your arguments against this option -->

Please, do not reply to others. If someone posts after you and you want to add something, please edit your own post. Thanks.

After gathering feedback, we will open a poll to capture the community's informed opinion on the best path forward.

Let's work together to ensure the robustness and clarity of our specification.

Edit:
The poll is #893

[cdavernas]

1. Keep both do and execute

Pro

• No change required (but as @fjtirado pointed out, it's not an argument in current stage)
• Ubiquitous
• Consistant.

Con

• Repeating two similar words, which IMHO is acceptable: do/execute

2. Retain only do

Pro

• Slightly shortens declaration without loss of meaning
• Ubiquitous
• Avoid repeating similar words: do/execute

Con

• Inconsistency between other task discriminator keyword (call, try, ...)

3. Remove "top-level" do and rename execute as do

Pro

None IMHO

Con

• Breaks clear responsibility of top level properties
• Incomprehensible when unordered (which WILL occur, as demonstrated, in many languages, amongst which js)
• Wierd looking
• Repeating twice the exact same keyword (do/do)
• Complexifies schema
• Makes schema super wierd conceptually ( workflow "inherits" from task)

4. Remove both "top-level" do and execute

Pro

None IMHO

Con

• Breaks clear responsibility of top level properties
• Incomprehensible when unordered (which WILL occur, as demonstrated, in many languages, amongst which js)
• Wierd looking
• Complexifies schema
• Makes schema super wierd conceptually ( workflow "inherits" from task)

[JBBianchi]

Could you please provide you take on case 5. added after your reply (if any) ?

[fjtirado]

1. Keep both do and execute

Pro

• Consistent schema

Con

• Execute is redundant with do.
• Execute is not a good place holder for properties specific to concurrent or sequential list of task, so keeping it do not allow us to add future properties if needed. (or, if we use, we will be adding under execute properties that only applies to concurrently and not apply to sequentially)

2. Retain only do

Pro

• Shorter
• Consistent schema

Cons

• Concurrently is a adverb and try is a verb. This can be fixed by using the verb (concurrent? As @cdavernas pointed out this is an adjective ;)). But after thinking it during a while, why using a verb followed by an adverb is considered inconsistent? "do something" sounds better than "do execute"

Idea

To be able to add properties specifics to concurrently: or sequentially: maybe we should consider the possibility of adding a generic keyword to the task object, like using: so we write

do:
  concurrently: 
      - task1:
      - task 2:
  using: 
       onParallel: true

Following that idea, we can maybe promote with from call schema to task schema, so we can add properties using with to all task.

do: 
  concurrently: 
     -  task1: 
        call: http
        with: .....
     - task2: 
        call: grpc
        with: .....
  with:
    onParallel: true

3.Remove "top-level" do and rename execute as do

Con

• Do duplication
• Messy schema

4. Remove both "top-level" do and execute

Pro

• Compact solution

Con

• Not really possible with json schema.

5. Refactor execute (and maybe rename it as tasks)

Pro

• Good altenative to 2 (the in is essentially similar to using that I proposed)
• I prefer tasks, so the workflow can be read "do tasks in order" which is as good as "do concurrently" or "do sequentially". I do not think semantically, there is a problem in using names or adverbs, but I do see an issue in using two equivalent vers "do execute sequentially" sound less natural

Con

• If we use execute rather than task, we still have do/execute

[JBBianchi]

Could you please provide you take on case 5. added after your reply (if any) ?

[bvandewe]

hi! hey i'm certainly missing few points here but how about avoiding the confusion between both do by renaming the first one to something like run (run tasks... vs do tasks...)?

6. Rename top-level do to run

Pro

Avoids confusion with the other usage of do.

Con

?

[JBBianchi]

Thanks for your input, I'll extend use cases which still rely on do with the possibility to rename it as run

[bvandewe]

oh well, run is used elsewhere... https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#run

[JBBianchi]

Calling @matthias-pichler-warrify as you were part of the discussion in #882

[matthias-pichler]

1. Keep both do and execute

Pro

1. as described here this maintains the top level structure that makes it easy to know where to find which information:

document: {} # Metadata: name, version, dsl etc
input: {} # what is expected as input
use: {} # reusable components
do: {} # which actions are performed
timeout: {} # how long does it run
output: {} # what is returned
schedule: {} # when is it run
evaluate: {} # which kind of expressions can I expect

2. All tasks are still using verbs in imperative form for consistency. It's also still meaningful when reading aloud ( execute sequentially )

3. It allows for options being added next to concurrently / sequentially such as compete and is extensible in the future

document: {}
do:
  execute:
    compete: true
    parallelism: 3 # hypothetical future option
    concurrently: []

4. It keeps the schema logical in the sense that every occurrence of do takes a single task. It also does not introduce any illogical inheritance relations such as Workflow extends Task as also described here.

Con

1. do/execute when appearing next to each other seem to be redundant/meaning basically the same thing. This also is a very common occurrence since any workflow with more than 1 task will include this.

2. Retain only do

Pro

1. keeps a clean top level structure (same as first point above)

2. Similar to above options still can be added:

document: {}
do:
  compete: true
  parallelism: 3 # hypothetical future option
  concurrently: []

which might make competitively obsolete since we can retain the compete option

3. do/sequentially does read nicely and basically the same as execute/sequentially but without the redundancy of do/execute/sequentially

4. Schema stays logical (same as above)

Con

1. Sequentially/Concurrently/Competitively are no longer verbs in imperative and hence less consistent.

3. Remove "top-level" do and rename execute as do

Pro

Con

Points are taken from here.

I have the following issues with effectively replacing execute with do and allowing a top level task:

Logical Inheritance

Allowing the properties of a task to reside at the top level of the workflow would mean that the schema for workflow would look something like

type: object
$ref: "#/defs/task" # to allow task properties at the top level
properties:
  document: {} 
  input: {} 
  use: {} 
  timeout: {} 
  output: {}
  schedule: {} 
  evaluate: {}

Now this is, according to the JSON schema homepage: https://json-schema.org/blog/posts/modelling-inheritance , the de-facto standard way to model Inheritance.

I am not sure how generated types/schemas are handled in (all) OOP programing languages (I believe you are much better informed here) but at least conceptually this would mean Workflow extends Task and by the substitution principle an entire workflow could be used anywhere where a task is expected? also in try, catch, for.do ect ? This seems illogical to me.

The schema will be more logically consistent in my opinion

So I disagree an this one. One is a task and the other a workflow. try, catch, loops, extensions and a workflow all have task(s) to run/execute/do/perform but only some of them are tasks themselves. So for me its a bit of Composition vs Inheritance thing and not everything has to be a task (in my opinion).

Readability

Assuming I receive a workflow document that looks like:

then: exit
output: {} # what is returned
document: {} # Metadata: name, version, dsl etc
do: {} # task of the loop
input: {} # what is expected as input
schedule: {} # when is it run
while: .vet != null
use: {} # reusable components
timeout: {} # how long does it run
for:
  in: .pets
evaluate: {} # which kind of expressions can I expect

(I intentionally reordered the keys because this is what this PR is about after all).

Now it is way less clear where to find what. And suddenly do is not for sequential or concurrent but the loop task. Which I might completely miss due to the fact that for is near the end. And the loop statements for and while might be spread across the very beginning and end of the workflow ... not very clear to me.

Furthermore then does not make any sense at the top level but suddenly becomes valid.

Also with simpler workflows, such as:

document: {} # Metadata: name, version, dsl etc
call: http
input: {} # what is expected as input
use: {} # reusable components
with: {}

I find the appearance of with and use right next to each other less than pretty because it makes me stop every time to think: which one is for components and which one for function calls.

Sequential tasks in catch and loops

Because do also appears in catch and loops there is the possibility of two dos appearing right next to each other.

try: {}
catch:
  do:
    do: # yikes
      sequentially: [] 

for:
  in: .pets
do:
  do: # yikes
    sequentially: [] 

So this would mean we would need to introduce yet another verb to replace the occurrences of the word do in catch and loops.

Lastly do is no longer consistent because for.do and catch.do take a single task while do/sequentially & do/concurrently are tasks themselves and do not take another task

4. Remove both "top-level" do and execute

Pro

Con

Basically all my points about option 3 minus the occurrence of do/do

5. Refactor execute (and maybe rename it as tasks)

Pro

1. as described here this maintains the top level structure that makes it easy to know where to find which information:

document: {} # Metadata: name, version, dsl etc
input: {} # what is expected as input
use: {} # reusable components
do: {} # which actions are performed
timeout: {} # how long does it run
output: {} # what is returned
schedule: {} # when is it run
evaluate: {} # which kind of expressions can I expect

2. All tasks are still using verbs in imperative form for consistency. It's also still meaningful when reading aloud ( execute in order, execute in parallel )

3. It allows for options being added next to execute such as compete and is extensible in the future

document: {}
do:
  execute: []
  in: parallel
  compete: true
  parallelism: 3 # hypothetical future option

4. It keeps the schema logical in the sense that every occurrence of do takes a single task. It also does not introduce any illogical inheritance relations such as Workflow extends Task as also described here.

Con

1. do/execute when appearing next to each other seem to be redundant/meaning basically the same thing. This also is a very common occurrence since any workflow with more than 1 task will include this. And tasks would no longer be a verb.

tasks would not always appear after a do e.g.

document: {}
do:
  tasks:
    - task1:
         tasks: [] # no longer read as "do tasks" but "task1 tasks"
  in: order

[JBBianchi]

Poll available #893

[JBBianchi]

This topic has been resolved with #895