Questions about `sourceDescriptions` references and sructure

[DmitryAnansky]

Hi Everyone,

I have a few questions about sourceDescriptions with the type workflowsSpec. It appears that the intention is to reuse workflows from other files or sources.

I’m a bit puzzled by the way workflows are referenced throughout the document. The commonly described example is $sourceDescriptions.<name>.workflowId, which creates some confusion with the suggested structure.

In the suggested structure, the workflow seems to have an extra level of workflows:

{ 
 "workflowsSpec": "1.0.0",
 "info": { "title": "Reusable API", "version": "1.0" },
 "sourceDescriptions": [],
 "x-parameters": [],
 "workflows": [{}]
} 

So I’m wondering if this is a mistake and if we’re missing an extra workflows level in this reference $sourceDescriptions.<name>.workflows.<workflowId>,

or if it was done by design and all that should be available from the sourceDescriptions of type workflowsSpec is just the list of workflows and nothing else. It this case more questions about usage of sourceDescriptions inside that file arise.

Looking forward to your reply, Thank you.

[kevinduffey]

I see why you are asking that. In this case when you import a workflow tooling would assume all workflows from all sources are "inlined" so workflow IDs are unique. There isn't any benefit or need to use .workflows. Each workflow document has one or more workflows in its workflows[] section and each has a unique id. When use sourceDescriptions. you're already specifying the workflow import so having workflows. or not wouldn't make any difference. I guess one could argue about "correctness" but me personally I don't see why we need to specify another layer when we know the id we are specifying is unique. Frankly we could probably avoid even using sourceDescriptions. but that makes it more readable.. so someone looking at the main source can see that a given workflow ID resides in a given imported source description.

[frankkilcommins]

[Following up here from slack convo]: @DmitryAnansky It might be more beneficial to move this to an issue but we can keep here for now. The goal in general is to provide an easy way to uniquely identify a where a workflowId in this case (and an operationId in similar cases) can be found. The prefixing is only applicable when multiple sourceDescriptions of the same type (including the inline workflow in the document in question) exist.

I think there are two options:

• Just use the runtime expression syntax to identify the specific sourceDescription to look in for the workflow or operation. How the workflow or OAS is parsed to find the thing is up to the tooling. This keeps things simple but we'll need to adjust the verbiage so that instruction is clear to use the expression to identify where to look for the workflow/operation
• Use runtime expressions to allow explicit mechanism to evaluate to a workflow or operation. In this case then yes, the examples need to be updated. This makes it a more cumbersome for operationId however
  • Like you suggest, $sourceDescriptions.<name>.workflows.<workflowId> for a workflow
  • Something like $sourceDescriptions.<name>.paths['/pets'].get.<operationId> for an operation following OAS structures....

Either way, this probably needs to be cleaned up. Thanks for raising.

[frankkilcommins]

From Dmytro:

Case 2 looks more preferable for me, but if you will decide to go with the first option, or maybe it is actual for both cases: If workflow in external file has its own refs to the sourceDescriptions or maybe its own components, should it continue to have this awareness, or it should loose context when it is imported workflow, and use only local vars(components | sourceDescriptions)?

This also includes some outputs usage, as it would be easy to make mistakes with dependent responses from other steps|workflows.

Entry Workflow Document context is not available within a workflow accessed via the sourceDescription. What ever you need must be passed into it via the inputs and what ever you have to back must be returned via the workflow outputs