Feedback on the 1.0.0 draft

[earth2marsh]

Great to see the first working draft landed! I wasn't sure where to put feedback, so starting this discussion, but please adjust me if it should go somewhere else.

1. While this draft is a solid start, the amount of abstraction makes it hard for me to understand what it will look like in practice. I'd benefit from a bunch of examples that accompany the formal rules. May I suggest taking some of the highest priority workflows and imagine them in YAML? That would help me better understand what the authoring experience might be like in practice.
2. The workflows spec would benefit from having a clear purpose at the top of the document, even if that's a placeholder.
3. The word version has bitten OpenAPI document authors time and again... consider a multi-word property name here, even it it means diverging from OpenAPI somewhat.
4. Is a workflows document meant to refer to an OpenAPI document? A specific version of that document? Multiple documents?
5. Might each workflow be a separate document?

[ankrim]

I agree that we need to add examples, that's one of the efforts that we'll start in parallel to writing the spec.
For now, you can see an example in this discussion #10.

[namdeirf]

Please provide your use case examples in this discussion #23

[swaldron58]

can you suggest a format for use cases? in sig-travel we have looked at several formats. We looking at real world API sequences which takes a while to document in a non specific product or provider way. Like a common hotel booking workflow versus Hilton specifically. what I mean by that is we have some members that can provide the existing sequence of their current API offering. Then there are other high level (not at the API level) documents on how, for example, to exchange digital IDs.
What will take longer is for the sig-travel team to sort out in, for example and end to end booking flow, how we break this down into procedures. For example is an initial procedure just "shop" followed by others for "book", "pay" and "fulfillment".

[edwinlzs]

Hey! Appreciate the work on the spec. Not sure where else to ask clarifications so I'll drop it here.

https://spec.openapis.org/arazzo/latest.html#step-object

It says a step MAY be a call to an API op. I'm reading this as: there might NOT be any calls at all (i.e. its possible that operationId, operationPath and workflowId are all not defined). Would that just be a no-op? What would be the purpose of having such a step?

[edwinlzs]

Never mind, I figured it out. I was tripped out by the placement of the parentheses (there might be a mistake in the explanation there), I think what the spec actually meant to say is:

"Describes a single workflow step which MAY be a call to an API operation (OpenAPI Operation Object) or another Workflow Object."

[frankkilcommins]

v1.0.0 is not longer in draft status and has been published. Closing this discussion