OAI / OAI/Arazzo-Specification
Runtime expression grammar: add $workflows.<workflowId>.steps.<stepId> for dependsOn step references (Step Object)
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 471
- Forks
- 69
- Avg merge
- 17h 58m
- Merged PRs (30d)
- 19
Description
Summary
The dependsOn field (Step Object) documents this syntax for referencing a step in a different workflow within the current Arazzo Document:
If the step is defined in a different workflow within the current Arazzo Document, reference it using
$workflows.<workflowId>.steps.<stepId>.
This syntax doesn't appear in the runtime expression ABNF (Appendix A). The ABNF only defines:
workflows-reference = workflow-id "." workflow-field "." workflow-field-name [ "#" json-pointer ]
workflow-field = "inputs" / "outputs"
workflow-field has no "steps" alternative, so a conforming parser of the runtime expression grammar rejects this spec-documented dependsOn syntax outright.
Impact
A conforming implementation that builds dependsOn validation directly from the published runtime expression grammar currently rejects $workflows.<workflowId>.steps.<stepId> entirely, which is a real spec-compliance gap for a spec-documented syntax — not an edge case.
Proposal
"steps" doesn't collide with any other documented use of workflow-field, so this is safe to add unambiguously and purely additively:
workflows-reference = workflow-id "." ( workflows-value-reference / workflows-steps-reference )
workflows-value-reference = workflow-field "." workflow-field-name [ "#" json-pointer ]
workflows-steps-reference = "steps" "." step-id
workflow-field = "inputs" / "outputs"
(step-id = identifier-strict, already defined for $steps.<stepId>.outputs.<name>.) Every string accepted today still parses identically; only $workflows.<id>.steps.<id> newly becomes valid.
Alternative
If dependsOn's $workflows. step-reference syntax is meant to be left ungoverned by Appendix A (e.g. because it's considered a distinct, non-"runtime-expression" string syntax that only reuses the $workflows. prefix cosmetically), it would help to say so explicitly.
Notes
Found while adding dependsOn step-reference parsing to @swaggerexpert/arazzo-runtime-expression. Related: #501, #518, #519 (same "documented in prose, ungoverned by Appendix A's grammar" pattern).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with Appendix A's runtime expression ABNF and the dependsOn Step Object wording described in the issue. Compare the existing workflows-reference rules with the proposed steps alternative, then update the specification so the documented syntax is either accepted by the grammar or explicitly excluded from it.
Written by the indexing model from the issue text.
Assessment
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 66/100