Swagger allows to specify request or response body schemas with type/format string/byte and string/binary. The intention of the spec writers is probably to allow describing pure binary and base64 payloads, but in the realm of JSON Schema, such description implies a valid JSON string (i.e. "blah blah") with its contents being of a particular format. Currently we treat Swagger schemas as JSON Schemas and there are compatibility issues caused by what format values are supported - https://github.com/apiaryio/fury-adapter-swagger/issues/99 - but this is slightly different, because I think nobody really meant there should be payloads like this:
"âPNGIHDRdlú±9bKGDˇˇˇ†ΩßìpHYs..."
(It was supposed to be a beginning of a PNG image in binary, but I had to delete some bytes so GitHub wouldn't break the code block 😬)
Instead, the intention was probably that following Swagger describes a /binary route responding with some raw bytes in the body:
paths:
/binary:
get:
responses:
200:
description: Representation
examples:
"application/octet-stream": "..."
schema:
type: string
format: binaryEven if subsequent tooling ignores the format description, it is lead by the schema to assume the payload should be a valid JSON string.
The Swagger adapter should somehow deal with the situation, as it is Swagger-specific and ruins the agnosticism of the subsequent tooling. One approach, probably the easiest, would be to drop top level string/binary and string/bytes schemas and leave the body description without any assertions for the subsequent tooling. Nested schemas of such types/formats are okay, as the nested nature already implies a structure like JSON.
Swagger allows to specify request or response body schemas with type/format
string/byteandstring/binary. The intention of the spec writers is probably to allow describing pure binary and base64 payloads, but in the realm of JSON Schema, such description implies a valid JSON string (i.e."blah blah") with its contents being of a particular format. Currently we treat Swagger schemas as JSON Schemas and there are compatibility issues caused by whatformatvalues are supported - https://github.com/apiaryio/fury-adapter-swagger/issues/99 - but this is slightly different, because I think nobody really meant there should be payloads like this:"âPNGIHDRdlú±9bKGDˇˇˇ†ΩßìpHYs..."(It was supposed to be a beginning of a PNG image in binary, but I had to delete some bytes so GitHub wouldn't break the code block 😬)
Instead, the intention was probably that following Swagger describes a
/binaryroute responding with some raw bytes in the body:Even if subsequent tooling ignores the
formatdescription, it is lead by the schema to assume the payload should be a valid JSON string.The Swagger adapter should somehow deal with the situation, as it is Swagger-specific and ruins the agnosticism of the subsequent tooling. One approach, probably the easiest, would be to drop top level
string/binaryandstring/bytesschemas and leave the body description without any assertions for the subsequent tooling. Nested schemas of such types/formats are okay, as the nested nature already implies a structure like JSON.