Our current reference documentation for mongoization/demongoization/evolution is the custom field definition - https://www.mongodb.com/docs/mongoid/master/reference/fields/#custom-field-types. This documentation can be expanded to state what is returned from #attributes and #read_attribute methods for custom types, i.e. whether it's a value of the field type or the mongoized value (I expect the latter).