parameters as a list

[bjne]

parameters is currently specified as a list, and this allows specifying multiple parameters with the same name and the same in. The documentation states:

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

I am reading location here as path, and if that is the case, I do not think its a good solution to leave parameters as a list, a object with patternProperties would be a better approach, as the object itself will limit undefined behavior:

"parameters": {
  "uuid": {
    "location": "path"
  }
}

If the documentation should have read:

"A unique parameter is defined by a combination of name and in", I still think it should be designed as a object:

"parameters": {
  "path": {
    "uuid": { ... }
  },
 "query": {
    "uuid": { ... }
 }
}

I do prefer the first approach, as imho it is dangerous to allow the same parameter names in different parts. A server operation would typically want a flat parameters object as input, agnostic to how schema specifies where it was passed.

[Doqnach]

Seeing as you may want a parameter named "content-type" in a query param, path or cookie, your approach would not allow this since there is already a HTTP header named this way.

The current way it is seems fine to me, though the documentation could be clarified about what they mean with 'location' if this ends up not being clear to people.

[bjne]

I will try to be a bit more clear on how I would like parameters.

Current design allows for undefined behavior, say for example:

"parameters": [
  {
    "name": "foo",
    "in": "query",
    "required": false,
  },
  {
    "name": "foo",
    "in": "query",
    "required": true
  }
]

In this case, the specification would need to document how to deal with this. Also, I do not think it is possible to validate this with a schema.

In addition, having a parameter with the same name in path, query, header and cookie (not body), is imho a source of confusion and possible security issues and should be avoided.

My preferred approach would be:

"parameters": {
  "foo": {
    "in": "path"
  }
}

Also, would consider replacing in keyword with location, as in is a keyword in multiple languages, and location is easier referenced in documentation imho.

But if the need for equal named variables in different "in/locations" really is wanted:

"parameters": {
  "path": {
    "foo": {
      "required": true
     }
  },
  "query": {
    "foo": {
      "required": false
    }
  }
}

[bjne]

Any comments on this please?

[handrews]

This is essentially the same as #3040, I think, so it will be addressed in Moonwalk, so I'm going to close it "Moved to Moonwalk" and all are encouraged to discuss in that repo! Here are the relevant proposals:

• the original proposal treats parameters as objects and applies one schema to them
• https://github.com/OAI/sig-moonwalk/discussions/32 proposes moving everything to arrays instead

We can't make this sort of structural change in 3.x, so I'm closing it out of this repo which is now just for the 3.x series.