In the BSON Spec there is a null type: http://bsonspec.org/spec.html. This type has no value (only the type byte).

When a hash contains a nil value, this value is serialized using the bson null type. Thus, bson-ruby correctly round-trips hashes with null values:

irb(main):008:0> {a:nil}.to_bson
=> #<BSON::ByteBuffer:0x000055e8182e7650>
irb(main):009:0> Hash.from_bson({a:nil}.to_bson)
=> {"a"=>nil}

However, it is also possible to call to_bson on nil, which produces an empty string:

irb(main):005:0> nil.to_bson.to_s
=> ""

The empty string subsequently causes problems like https://jira.mongodb.org/browse/MONGOCRYPT-246.

The reason is that #to_bson performs two functions:

• Producing a complete, legal bson document
• Producing a bson fragment

When a user intends to obtain a legal bson document, they should be warned (e.g. via an exception) when their input won't produce a legal document. I believe the only input which produces legal bson documents in Ruby would be Hash instances.

The method which bson-ruby internally uses to produce bson fragments can be renamed, e.g. to #to_bson_fragment, and this method would be marked api private.