OpenAPI-Specification icon indicating copy to clipboard operation
OpenAPI-Specification copied to clipboard

Format Registry documentation is not accurate / well published

Open LasneF opened this issue 1 year ago • 3 comments

Looking on the page here https://spec.openapis.org/registry/format/ as well on the JSON content here https://spec.openapis.org/api/format.json

there are some mistakes in the collumn type

for instance : decimal A fixed point decimal number of unspecified precision and range stringnumber should be string, number

for in64 we have an other version int64 signed 64-bit integer numberstring

only sf integer looks correct

then about the JSON content , to me the given the constrains that a format can apply to multiple base type it should be represented as an array

"base_type": "numberstring" => "base_type": [ "number","string"]

LasneF avatar Apr 12 '24 08:04 LasneF

Looking a bit deeper in gh-page repo , it looks like data is accurate , but it is more a generation issue of the HTML document and of the JSON document that does not leverage the data

for instance int64 is correctly described here https://raw.githubusercontent.com/OAI/OpenAPI-Specification/gh-pages/registries/_format/int64.md

LasneF avatar Apr 12 '24 08:04 LasneF

Yes, something is concatenating two type values instead of rendering them as a comma-separated list.

handrews avatar Apr 12 '24 17:04 handrews

I found a solution on this one and I will open a PR soon. It is worth noting that the only reason the sf-integer is shown correctly it is because we have wrongly set its base type to string. Which means that the base type is basically set to "integer, string" instead of ["integer", "string"]. You can check it also by the produced JSON: https://spec.openapis.org/api/format.json

Bellangelo avatar May 07 '24 23:05 Bellangelo

Resolved by @Bellangelo 's PR - I just checked the rendered pages and they look good now.

handrews avatar May 11 '24 15:05 handrews