Do not force "" for http status code

[pkuczynski]

In JSON the key which is a number must be wrapped into "". This is not the case of yaml format. Different formats, different requirements. It does not make sense to force json requirements into yaml and this makes it really annoying to have to use "400": ... in YAML

Please also note that https://editor.swagger.io does not wrap status codes into "", which is correct, but contradictory to this spec:

I propose to remove the requirement of providing status codes as strings in YAML and only keep it for JSON, leaving the alignment for the transformation tool between two formats.

I already created #2147, which got rejected, so now I am opening this issue as the proposal for the next version of the spec.

[notEthan]

I think this would not be an improvement to OpenAPI. in terms of general principles, OpenAPI exists to aid interoperability. changes that add ambiguity to how an API can be represented in OpenAPI are counter to that. every tool would now have to look for numeric keys in addition to string keys. it opens up the possibility for collisions if both integer 200 and string "200" are present. it brings in issues of comparing numbers (is 200 equal to 200.0? in some languages all numbers are parsed to floats).

having a single, consistent way to represent an http status obviates all these problems. I appreciate that the aesthetics of having to quote these, when you don't normally have to quote object keys in YAML, is suboptimal. but it is best for keys to remain as strings.

it's unfortunate that the swagger editor uses integer keys. they shouldn't. it looks like these are implicitly converted to strings by their YAML parser (which is not usual and seems plainly incorrect according to the YAML spec - but that's far afield). I will open an issue to correct their examples (unless, of course, the consensus on this issue goes the other way).

[pkuczynski]

In the HTTP/1.1 standard (RFC 7231: https://tools.ietf.org/html/rfc7231#page-47) response status code is described as:

three-digit integer code giving the result of the attempt to understand and satisfy the request.

In all of the languages and libraries I know, it is implemented as an integer.

Forcing in OpenAPI spec to represent response status code as a string is misleading, against HTTP standard and all of the software implementations.

What's worse is that it's done only to cover the limitations of the JSON format not being able to handle numeric kets or to avoid double keys in YAML. I believe such things should be covered by the linting tools, instead OpenAPI spec introducing misleading requirements.

[MikeRalphson]

The responses object is defined as a map of string keys to response objects. This is to facilitate the use of range codes like 4XX and the default value.

[notEthan]

In all of the languages and libraries I know, it is implemented as an integer.

I've worked with a lot of http libraries, the string/integer decision seems like a coin toss sometimes. arguably an integer is more appropriate, but it doesn't really matter. OpenAPI documents are JSON (even when they are YAML), and in JSON, object keys are strings, not integers.

[pkuczynski]

I am keen to see the library which exposes response status code as string :)

The internals of OpenAPI spec does not matter so much. If the format (like YAML) offering easy transformation to what OpenAPI uses under the hood, this should not force on the format to use something not natural. YAML keys wrapped into "" is not common for this format.

I believe OpenAPI spec should focus on the value it offers (and it's undoubtedly great!) instead of specifying format details.

[pkuczynski]

@MikeRalphson responses could be defined as "integer | string" enum to satisfy the case you have mentioned.

[hkosova]

@pkuczynski your proposal would allow situations like this

responses:
  200:
    ...
  "200":
    ...

which would need additional wording in the Spec to ensure the uniqueness of map keys and, as a result, require additional work from tooling vendors.

Using a single data type (string in this case) helps keep things simple.

[pkuczynski]

@hkosova this is a very unlikely situation, and I think very easy to spot when reviewing the spec (source or rendered to a nice doc) - duplicated keys would really stand out. And still, if one would miss it, he could use one of the many linting tools to ensure the syntax of the spec is correct.

I believe that it would be better to say that response code need to be unique, instead of forcing "" on the format, where they are not needed and very not natural to use.

[philsturgeon]

@pkuczynski unlikely based on what? Two people merge a change to an OpenAPI document, both adding 404, one uses string the other doesn't. Now you have a "404" and a 404.

[pkuczynski]

This should be picked up by git as a merge conflict, so the second-person would see it and resolve it. In a rare case of mistake, validation should report it...

[philsturgeon]

That's not actually how git works. 😅

[pkuczynski]

I know how git works, trust me :)