Support for CBOR

[cyberphone]

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

[MikeRalphson]

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 json-schema-org/json-schema-spec#6

[cyberphone]

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.

[MikeRalphson]

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?

[cyberphone]

Hinting would probably be needed for binary data since is raw. There is only one binary data format.

[handrews]

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.

[mkschreder]

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?)

[handrews]

@mkschreder the idea of supporting it in 4.0 "Moonwalk" is mentioned here (it does not yet have its own discussion):

• Learning from "competing" formats sig-moonwalk#47 (comment)

[cyberphone]

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

[Type1J]

I have used EJSON from the Meteor project. It has been around for quite a while. It only encodes Date and Uint8Array, but that is useful enough. Also, the fact that it is actual JSON helps (a Date is an object with the single key $date and the value is an ISO date string.).

If the schema could be augmented, then Swagger UI could have a plugin that allows a conversion of an annotated JSON or EJSON object to CBOR before the call, and convert the returned valuea from annotated JSON or EJSON.

Ecerything starts with the spec, though.

[cyberphone]

@MikeRalphson @mkschreder @handrews @Type1J I believe the ability to use Embedded Signatures, is the most compelling reason for looking into CBOR.

JSON:

{
  "data1": true,
  "data2": "something else"
}

How would you using Open API sign this message?

CBOR (using an Embedded Signature):

{
  "data1": true,
  "data2": "something else",
  simple(99): {
      algorithm, signature, etc.
   }
}

That is, the message structure stays intact. Note: this is a debug (toString()) printout, CBOR is a binary format.

Internet-Draft: https://www.ietf.org/archive/id/draft-rundgren-cbor-core-25.html#name-embedded-signatures

You may try it online: https://test.webpki.org/csf-lab/home

An alternative: is https://www.rfc-editor.org/rfc/rfc9421
This is fine but the messages are not (easily) serializable since the signature is provided in HTTP headers.