Context

The bson.Unmarshaler interface describes that it's only used for "full BSON documents":

// Unmarshaler is only used to unmarshal full BSON documents. To create custom
// BSON unmarshaling behavior for individual values in a BSON document,
// implement the ValueUnmarshaler interface instead.

The bson.ValueUnmarshaler interface describes that it's only used for "individual values in a BSON document":

// ValueUnmarshaler is only used to unmarshal individual values in a BSON
// document. To create custom BSON unmarshaling behavior for an entire BSON
// document, implement the Unmarshaler interface instead.

Users often start by implementing bson.Unmarshaler because it's what they expect based on the patterns in the "encoding/json" package. Those users are then confused when UnmarshalBSON is called for the individual fields (which doesn't match the documentation) and then doesn't contain any type information in the function signature. Some users discover that they actually should implement UnmarshalBSONValue, which actually works both for top-level documents and individual fields (also not matching the documentation).

Instead, it would be much simpler to have a single interface:

type Unmarshaler interface {
	UnmarshalBSON(typ byte, data []byte) error
}

It would behave identically to the existing ValueUnmarshaler interface. The only difference from the existing Unmarshaler interface is that the function signature includes the BSON type info. Users can discard the type info if it's not useful to them, making migration from the existing Unmarshaler interface simple. In most cases, it's very helpful to check that the BSON type is the expected value.

Definition of done

What must be done to consider the task complete?

Pitfalls

What should the implementer watch out for? What are the risks?