Breaking Change After Upgrading to Mongoid 9.0.6 – belongs_to_required_by_default = false Doesn't Restore Legacy Behavior

[lucasDechenier]

Hi,

I recently upgraded a Rails app from Mongoid 7.4 to Mongoid 9.0.6 and encountered unexpected behavior related to the belongs_to_required_by_default setting.

Context

In Mongoid 7.4 passing a full document object to an *_id field worked without issue:

TrackEmail.create(company_id: Company.first)

Mongoid would automatically extract the ID from the object and assign it to the foreign key field.

What I did after upgrading

To try to restore the legacy behavior from Mongoid 7.4, I set:

Mongoid.belongs_to_required_by_default = false

Many of my tests started failing.

The Problem

Even with this configuration, I’m now getting the following error when passing a document object into the foreign key field:

TrackEmail.create(
  email: "test@example.com",
  company_id: company, # 'company' is a Company instance
  ...
)

Error:

BSON::Error::UnserializableClass:
Value does not define its BSON serialized type: #<Company:...>

Expected Behavior (Mongoid 7.4)

In Mongoid 7.4, Mongoid would handle this gracefully, extracting the .id from the object and saving it as the reference.

Minimal Reproducible Example

class Company
  include Mongoid::Document
  field :name, type: String
end

class TrackEmail
  include Mongoid::Document
  belongs_to :company, optional: true
end

company = Company.new(name: "Acme Inc.")
TrackEmail.create(company_id: company)

Expected result (Mongoid 7.4):
TrackEmail is created with company_id set to company.id.

Current result (Mongoid 9.0.6):
Raises BSON::Error::UnserializableClass.

Hypothesis

It appears that in recent versions of Mongoid, passing a document object directly to an *_id field is no longer supported when optional: true is declared, or when belongs_to_required_by_default is set to false. Instead, Mongoid attempts to serialize the object as-is, causing a failure.

This may be related to stricter internal validation or BSON serialization changes.

Impact

• More than 300 tests are now failing in my application
• Many create, update, and find_or_create_by calls are affected because the object was passed into *_id fields instead of the raw id

Questions

1. Is this the expected behavior in Mongoid 9.0.6?
2. Is there a recommended way to preserve the legacy behavior where Mongoid extracts the ID from document objects passed into *_id fields?
3. Are there any known workarounds or configuration flags to ease this transition without modifying all occurrences manually?

Thanks in advance for your time and support.