OpenAPI-Specification
OpenAPI-Specification copied to clipboard
OAI
Support for CBOR
I have after almost a decade with JSON, decided to use CBOR as the foundation for new designs (except for browser-based applications where the JavaScript/JSON combo still makes sense).
The rationale is here: https://github.com/cyberphone/cbor-everywhere
Do you mean support for requestBodies and responses in CBOR format, or exchanging OAS document instances encoded as CBOR? What changes in the specification do you think might be warranted?
https://spec.openapis.org/oas/latest.html#format
Note: While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
There is some discussion about CBOR for both representing JSON Schema instances and the object models they operate on over at the JSON Schema spec repo, such as https://github.com/json-schema-org/json-schema-spec/issues/6
I was thinking about request and response bodies. The data types would be affected since CBOR distinguishes between integer and float types. The handling of binary data also differ.
As long as bi-directional mapping can be established beween the JSON Schema model and the CBOR model (such as the implicit JSON<=>YAML mapping, or the JSON<=>XML mapping which is supported by the xml keyword which provides hints to perform that mapping), OAS would support CBOR request and response bodies. Do you feel any hinting mechanism would be required here?
JSON Schema also distinguishes between integer and number types. Does CBOR have one or many formats for binary data?
Hinting would probably be needed for binary data since is raw. There is only one binary data format.
The proposal to loosen the coupling between the OAS and JSON Schema in Moonwalk as noted in the recent "Moonwalk in 2024" blog post could theoretically allow using CDDL with Moonwalk when describing CBOR payloads. Which seems like the best way to support it.
I'm not sure there's much that could be done in an OAS 3.2 other than what @MikeRalphson already suggested, which is define a mapping to the JSON Schema data model and maybe use extension keywords in the schema for hinting.
I also think CDDL is a fantastic way to bridge openapi and CBOR data. Would be great to have native support for CDDL generation from schema. (maybe there is already? Anyone know?)
@mkschreder the idea of supporting it in 4.0 "Moonwalk" is mentioned here (it does not yet have its own discussion):
- https://github.com/OAI/sig-moonwalk/discussions/47#discussioncomment-9255156
If there will be CBOR support in Open API. it should be restricted to deterministic encoding: Draft: https://datatracker.ietf.org/doc/draft-ietf-cbor-cde One of many implementations: https://github.com/cyberphone/CBOR.js#cborjs