search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.91k stars 9.07k forks source link

operationId - should exclude reserved characters #2844

Closed gpsarkar closed 4 months ago

gpsarkar commented 2 years ago

Current description of operationId

Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.

The definition can be made more specific by defining the allowed or excluded character set. This being an ID field, should not include any reserved characters, as defined here - https://www.rfc-editor.org/rfc/rfc3986#section-2.2

Here is some context which might add more weight to this recommendation.

I found an issue with Az Powershell which provides a client to update apis on their azure gateway. One particular command fails to update the operation if there is a / character in the operationId. Although this issue is not directly related with openapi, but it is connected in way where some commands in that client works with the same id, while some errors out. Here is the issue id - https://github.com/Azure/azure-powershell/issues/16772

handrews commented 4 months ago

Unfortunately this would be a breaking change, so we can't do it in 3.x (the experience with compatibility exceptions made for 3.1 was such that we are not planning to that again). I'm closing this as moved to OAI/sig-moonwalk where we are discussing the next major version. There is no specific discussion for this, although you are welcome to add it, but I'm hoping we are in general more rigorous with syntax requirements this time around.