It's not redundant.. just a little confusing probably. You're indicating WHICH of the defined operation parameters you are passing values in to FROM the inputs.

 - name: username
 in: query
 value: $inputs.username

The operation (loginUser) defines username as a parameter. You are telling Arazzo that you want to pass to that operation the inputs FROM $inputs.username at that step.

If you think of this from a code generation perspective, the workflow becomes say, a single function.. the steps are then coded as a sequence of requests in that one function:

// Workflow ID loginUser
func loginUser(username, password: string) {
 // step 1 (only one defined in this example.. but could be more)
 err,resp := loginStep(username, password)
 ... more steps here if there were more defined ...
}
// Step 1 function
// Operation ref - loginUser
// loginUser defined with two parameters in its description (username and password as well)
// code generator tool sets up variables (elsewhere) for OpenAPI server info, etc
func loginStep(username, password: string) error, resp {
 err, resp := httpCall(http.POST, loginAPIUrl, username, password)
 return err, resp
}

This is just an example of what it might turn in to. If there were more steps in that workfow, they would be INSIDE The { } of that function. If you had a 2nd step that took in a parameter like userId that was returned from the first step, there might be some code to pull the userId from the resp object, then pass it on to the 2nd step.

So just to double up on the explanation.. the "outer" function receives input variables (username and password). Those are defined in the inputs: section. The step uses the $inputs... to access those. The step is setting it up to pass the $inputs.Username to the operations username property. as per the psuedo loginStep() function, that would match the step and as I commented there some of the things like the server it would make the API call to would be provided during code generation as well. Just left some of that out for brevity.

Make sense?

Thanks Kevin,
Makes sense overall. As you point out, it is clear that we need a template to hydrate with the inputs expected by the operations defined in the open api spec document. We also need a document to describe the sequence in which these operations will be called.
I was referring exclusively to the definitions of the inputs (e.g. parameters). In your example, let's look at this:

 in: query

The fact that this parameter is to be submitted in the query can be obtained from the open api spec. My concern with two separate locations where the same above fact is available is that there is a possibility that in the arazzo document it is in: query while in the open api spec it is in: header. In other words, if the arazzo doc author made a mistake we now have an inconsistency.
If we say that arazzo overrides open api spec, this weakens the oapi spec which should always be the single source of truth. Alternatively, if we say that the oapi spec overrides arazzo, then we have a typo in arazzo and when an engineer is troibleshooting the code generators this will be a source of confusion and thus added maintenance.

What do you think is the right approach to explain this to an engineer that is new to this pattern? Should we just need to let the engineer know that we need to make sure that both arazzo and oapi spec should be the same to prevent any confusion?

Hi @zepedaherbey and @kevinduffey,

Firstly, apologies in my delay in getting back to this discussion ping.

I can confirm the reason we had to be explicit with the in parameter property was to ensure that we can have explicit mapping given that it's the combination of name and in that defines parameter uniqueness in OpenAPI. From the OpenAPI Specification:

A unique parameter is defined by a combination of a name and location.

There could be a discussion to be had for future versions of Arazzo to relax the in property to be optional in all cases, and allow an author to leverage it only for scenarios where there are parameter name conflicts in the underlying spec.

@zepedaherbey I'm going to slightly tweak the title of this discussion because as it is it (ironically) appears to be redundant with some other discussions. If this bothers you in any way, please switch it back, or if GitHub won't let you, please comment and I will fix it.