OAI / OAI/Arazzo-Specification

Runtime expression grammar: add $workflows.<workflowId>.steps.<stepId> for dependsOn step references (Step Object)

Open
#557 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.