Must HTTP Status Codes be strings?

[lafrech]

The Responses object contains a {HTTP Status Code: Response} mapping.

In all the examples I found, the status code is provided as a string:

    {"200": {"description": "a pet to be returned"}}

I couldn't find any requirement for it to be a string and integers are accepted by the validators I tried.

All I found was a PR changing from integer to string in all YAML examples.

Should I only use strings?

In JSON, only strings are valid keys. So the question could be rephrased as "which of the following two assumptions is correct"?

• OpenAPI doesn't specify that HTTP Status Codes should be strings because that's implicit (JSON format). However, validation and display tools are being loose about that requirement.

• OpenAPI uses some kind of "JSON superset" in which integer keys are considered valid.

I'm sorry if this is a silly question. I asked on SO and got no answer.

I'm pretty sure I'd be on the safe using using only strings, but I'd like to understand, and I'm surprised I didn't find any explicit requirement.

[MikeRalphson]

OpenAPI can be represented canonically in either JSON or YAML, as you say in JSON only strings can be keys. With regard to YAML:

This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML.

This has the effect that the key is always a string type.

[lafrech]

So it MUST be string and validators are loose when they let me use integers.

Thanks.

[MikeRalphson]

For example in the Javascript world, even processing a YAML document will coerce all the non-string keys to strings so the document can be represented as an object, so the validator may not even see the 'error' to flag it up. Other languages may vary.

[lafrech]

Hmmm, OK. I think I see. It's more a language / format / representation issue than a spec issue.

[justin-ad]

One of the many reasons I strongly prefer JSON to YAML. Is the V3 spec going to support JSON?

[MikeRalphson]

All versions of OAS can be written in JSON.

[justin-ad]

Would you accept a PR for some JSON examples added to OpenAPI-Specification/examples/v3.0/?

[MikeRalphson]

I believe the last stated position is that if we added json examples, they would be autogenerated from the yaml ones.

[justin-ad]

I'd be happy to auto-generate some JSON examples from the existing YAML examples for V3 and submit a PR. But I don't want to waste the effort if those who could accept the PR are trying to steer the community to YAML and are intentionally omitting JSON examples.

[MikeRalphson]

One-off generation of JSON examples from the YAML is not "autogeneration" as I meant it. If we went down this route it would be an automated process to keep the two in step.