Standardize JS API to encode/decode CBOR

rmedaer commented 2 years ago

Introduction

Concise Binary Object Representation, aka. CBOR (RFC 8949) is a data format widely deployed on the web. However there is no standardization of JS API to encode/decode it.

Use Cases

A consensus around a standard CBOR JS API specification might be used by web browsers or any other JS implementation to expose native CBOR support[^1].

Goals

The goal of this proposal is to define a standard JS API to encode/decode CBOR data format. It includes:

the prototype of functions for encoding/decoding (based on know-how from existing JS implementations),
the mapping and convertion between JS notation and CBOR representation considering the non-normative advices from RFC 8949 Section 6: "Converting Data between CBOR and JSON".

Non-goals

This proposal does not consider the RFC 8742: "Concise Binary Object Representation (CBOR) Sequences".

Proposed Solution

Based on existing implementations, the proposed solution defines the simple JS API of the form:

encoded = CBOR.encode(data) ➔ data = CBOR.decode(encoded)

Encoding CBOR

The CBOR.encode() method converts a JavaScript object or value to its CBOR representation in an ArrayBuffer object.

This method follow the recommendations from RFC 8949 Section 6.2: "Converting from JSON to CBOR " to encode JS types into CBOR representation.

Syntax

CBOR.encode(value)

Decoding CBOR

The CBOR.decode() method converts the CBOR representation within an ArrayBuffer object to a JavaScript object or value.

This method follow the recommendations from RFC 8949 Section 6.1: "Converting from CBOR to JSON" to decode JS types from CBOR representation.

Syntax

CBOR.decode(value)

Let’s Discuss

A few remaining questions:

Is it the right place for this kind of proposal ?[^2]
Should we map (some) CBOR tags to their equivalent in JS ? For instance date/time, URI,...

Previous discussion on discourse: https://discourse.wicg.io/t/proposal-native-cbor-or-messagepack-support/2011

[^1]: CBOR is already implemented in some browsers (Chrome, Firefox, and Edge) thanks to the new W3C Specification Web Authentication (WebAuthn). [^2]: Request for Mozilla Position has been asked here.

yoavweiss commented 1 month ago

Thanks for proposing this! Can you expand on the use case? Is there a polyfill for this already?

/cc @jyasskin

jyasskin commented 1 month ago

There are a couple different APIs floating around. The simple CBOR.{encode,decode} is in https://github.com/paroga/cbor-js (and doesn't handle large integers or non-string map keys, at least), while https://hildjj.github.io/node-cbor/ has more features and answers more questions about what to do with non-JS values. Neither answers questions around how to deterministically encode the data or how to enforce that input data was encoded deterministically. Some of the determinism question is under active discussion in the CBOR WG: see https://datatracker.ietf.org/doc/draft-ietf-cbor-cde/, https://datatracker.ietf.org/doc/draft-mcnally-deterministic-cbor/, and https://datatracker.ietf.org/doc/draft-bormann-cbor-det/.

I think it would be useful, but TC39 should get right of first refusal (https://github.com/tc39/ecma262/blob/main/CONTRIBUTING.md#new-feature-proposals), and someone needs to work out all the details.

marcoscaceres commented 1 month ago

The Digital Credentials API might need this too... some responses contain CBOR.

marcoscaceres commented 1 month ago

I agree with @jyasskin assessment... this feels like something that might need to go through TC-39, given its close relationship with JSON. I personally think this is still worth exploring though.

Although not a Web API, Web Driver BIDI also makes extensive use of CBORL

Network protocol messages are defined using CDDL. [RFC8610]

(CDDL is CBOR... yay acronyms!)

WICG / proposals