feature: Custom encodings for external types

[burdiyan]

Is your feature request related to a problem? Please describe.
Very often one might want a custom encoding of some type they can't control to implement the Marshaler/Unmarshaler interfaces. So, normally you'd have to wrap the external type into your own type that does implement the interface, which is very annoying and makes it harder to work with those types.

Describe the solution you'd like
The newly proposed JSON v2 package in the standard library has some ideas on how to deal with this, allowing users to mass custom marshaler functions to the codecs.

This package already has a similar concept of having a common "registry" of various type-specific encode functions, but those are not exported for users to register their own encoders. It would be great to expose them as-is, or maybe implement something similar to what JSON v2 is dong.

[burdiyan]

After struggling again with serializing some custom types, I revisited this issue with the idea of implementing the registry concept myself and possibly submitting a PR. But I was surprised to see it marked as waiting-for-go-api. I'm curious, what kind of Go API change is blocking this? I assume it might be related to encoding/json/v2, though it's not clear how that ties into this CBOR library. Is the goal just to mirror the behavior of encoding/json/v2, or is there some deeper reason a codec registry would be more viable or useful once that API lands?

[fxamacker]

I assume it might be related to encoding/json/v2, though it's not clear how that ties into this CBOR library.

Yes, "waiting-for-go-api" label is related to encoding/json/v2 still being in experimental-API phase (it has no Go compatibility promise as of June 14, 2025 and API is expected to evolve). The Go compiler's jsonv2 guard was committed with a warning:

Warning

The experimental API is not bound by the Go compatibility
promise and is expected to evolve as updates are made to
the json/v2 proposal.

Is the goal just to mirror the behavior of encoding/json/v2, or is there some deeper reason a codec registry would be more viable or useful once that API lands?

One of the goals is to support similar or same API (where it makes sense) as Go's built-in encoding package (especially encoding/json and encoding/json/v2).

Differences in codec API/behaviors can lead to increased learning curve, risk of bugs, and more maintenance burden.

On the other hand, it isn't always feasible to exactly "mirror" the behavior or API of encoding/json/v2 because CBOR has more data types and extension points compared to JSON.

The Go encoding/json/v2 API landing first will reduce risks for this codec dealing with breaking changes in the subset of Go built-in API we choose to mirror.

[burdiyan]

As a user of this library I honestly wouldn't mind the divergence at all. In the end there's no single built-in framework for serialization (like Serde in Rust), so it's expected that one would need to consult the documentation for each library they use for serialization. Of course it's nice when there's similarity, but knowing that json/v2 is experimental it's not even sure whether it will ever be merged, maybe it's not worth relying/waiting on it for implementing this feature (ofc I'm biased, because I really want this feature).

If json/v2 gets merged and stabilized, it should be possible to adopt its semantics here, deprecating whatever other approach could be implemented now.

In the end I understand that it's not my call, but maybe this could convince you to change your mind.

EDIT:

Looks like it's reasonable to expect for json/v2 to actually merge at some point soon, so maybe its API is already stable-enough to replicate here?