Add stand-alone example resources

[cdavernas]

What would you like to be added:

Stand-alone example json/yaml files, instead of just embedding them into an MD file

Why is this needed:

Allows SDKs and other implementations to unit test the successfull parsing of official, up-to-date examples

Other thoughts:

Now, what would be really awesome IMHO is to use factual examples, instead of theoretical ones, so that runtime implementations can test them to. The idea is to create some out-of-the-box examples for which runtime can be validated/tested.

We could use Swagger's Pet Store Api for demonstrating OpenApi function calls, and something like a free webhook tool for testing events.

---

What do you guys think?

[tsurdilo]

@Neuroglia I was actually working on this hehe :) I just wish there was a way to embed the files into the examples.md so we don't have to maintain both sides...

[tsurdilo]

@Neuroglia do you think doing this for the comparison examples: https://github.com/serverlessworkflow/specification/tree/main/comparisons

would be beneficial as well?

[cdavernas]

@tsurdilo Niiiice x) Ah yes, I hear you: I face the exact same problem in some private repos. The only "sane(ish)" way to do so, IMO, is by using a pipeline to replace values in your MD with the contents of the examples. Less user-friendly to write, but at least it's up to date.

[tsurdilo]

@Neuroglia we can host all OpenApi defs on serverlessworkflow.io ;) +100 for "running" examples Those can also become the start of our TCK tests as well.

[cdavernas]

@Neuroglia do you think doing this for the comparison examples: https://github.com/serverlessworkflow/specification/tree/main/comparisons would be beneficial as well?

@tsurdilo I'm not sure. I must say I only did go once or twice on that specific page, as there was no need to sell me the spec further x) But I can see the added value for more analytical brains than mine I guess!

[tsurdilo]

@Neuroglia if it helps, we do have (i hope all) examples here: https://github.com/serverlessworkflow/sdk-java/tree/main/api/src/test/resources/examples

but the problem with that is its a pain to maintain them all the time so they might not be all up to date with the spec examples, but the workflow dsl used there is validated against v0.6. Hope this helps for now until we work on this

[tsurdilo]

@Neuroglia here are some examples the java sdk uses for validation of some certain edge cases: https://github.com/serverlessworkflow/sdk-java/tree/main/api/src/test/resources/features hope this helps for now too :)

[cdavernas]

@tsurdilo Aaaaah! Awesome! I'll use that to add some unit test before the commit that adds the reader/writer!

[tsurdilo]

@Neuroglia This might help also: https://github.com/serverlessworkflow/sdk-java/blob/main/api/src/test/java/io/serverlessworkflow/api/test/MarkupToWorkflowTest.java to see whats tested in https://github.com/serverlessworkflow/sdk-java/tree/main/api/src/test/resources/features Need to add more tests tho :( ....

[tsurdilo]

@Neuroglia one more thing, we have our dsl schemas also exposed on the website: https://serverlessworkflow.io/schemas/latest/workflow.json this is used by the vscode plugin and the diagram generation project as well the "latest" always points to the latest release of the spec you can use "previous" to access v0.5 and "snapshot" to access the latest (main branch)

..maybe we should expose the examples as well there....hmmm

[tsurdilo]

@Neuroglia looking at this tool to possible be able to do this: https://github.com/temporalio/snipsync

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[tsurdilo]

@cdavernas we talked about this in this weeks meeting. will create a new repo and move all our examples and test json/yaml into it. SDK then can have a common pool of test workflows to use rather than having to have their own

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[cdavernas]

@tsurdilo Shouldn't this be re-opened?

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[cdavernas]

@tsurdilo Any update on this one? Anyone willing to take care of it?

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[lsytj0413]

@tsurdilo @cdavernas Any update of this？When we implement sdk-go we facing this which describe at https://github.com/serverlessworkflow/sdk-go/issues/115#issuecomment-1301560340.

A standalone example json/yaml files should helpful.

[cdavernas]

@tsurdilo Wanna take care of it? Otherwise I'll do it, no worries - even though I resent it too 🤣: this has been opened for faaaaar to long (like about two years).

[tsurdilo]

on it

[cdavernas]

You rule thanks bro!

[cdavernas]

Ping me if you need/want any help

[ricardozanini]

Same here; I can do it as well. Or we can share, divide, and conquer!

[ricardozanini]

It will be done as part of the migration work: https://github.com/serverlessworkflow/specification-docs/pull/1

[tsurdilo]

@ricardozanini this is a bit more involved. the intent was not for docs, but for sdks, as in all sdks would use same samples for their tests

[ricardozanini]

Yeah I know! I was going to add the examples in the docs directory as part of this migration. So we would have URLs like docs.serverlessworkflow.io/0.8/examples/heartmonitor.yaml

The docs URLs are versioned by default. Every release Antora will add a new directory for the given version. Would simplify a little bit.

[tsurdilo]

im not sure our tests should be downloading yaml from url. this should be imo separate repo that sdks consume and read from file system

[cdavernas]

@tsurdilo I see what you mean, and I'd tend to agree. However, I prefer having those examples available, in any shape or form, rather than having to wait for the hypothetical time where we will have enough slack to make that repo happen... I see it that way: it'd be infinitely better than nothing 😜

[ricardozanini]

Additionally, we use CI to download (cache) and run these tests. MD5 features in GitHub actions work pretty neatly.

[tsurdilo]

our sdk users should be able to compile sdk and run tests offline as well imo

[cdavernas]

@tsurdilo you are totally right! What do you propose we do as of now then?

[tsurdilo]

was looking at structuring sdks so can take advantage of git submodules maybe. wdyt?

[ricardozanini]

honestly, the tradeoff of having the examples online vs configuration bottlenecks doesn't seem a bad option IMO. These files can be cached locally by the SDKs as well. At least in Go, we will do a local cache.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[cdavernas]

This has been addressed in 1.0.0, and is closed as part of https://github.com/serverlessworkflow/specification/issues/843

In 1.0.0, we did even better than what was suggested by adding a list of Gherkin features for conformance testing and Behavior Driven Development.

Example:

Feature: Flow Directive
  As an implementer of the workflow DSL
  I want to ensure that tasks are executed in the correct order
  So that my implementation conforms to the expected behavior

  Scenario: Implicit Sequence Flow
    Given a workflow with definition:
    """yaml
    document:
      dsl: 0.10
      namespace: default
      name: implicit-sequence
    do:
      setRed:
        set:
          colors: '${ .colors + [ "red" ] }'
      setGreen:
        set:
          colors: '${ .colors + [ "green" ] }'
      setBlue:
        set:
          colors: '${ .colors + [ "blue" ] }'
    """
    When the workflow is executed
    Then the workflow should complete with output:
    """yaml
    colors: [ red, green, blue ]
    """
    And setRed should run first
    And setGreen should run after setRed
    And setBlue should run after setGreen