The default type mapping documentation we added in https://github.com/mongodb/mongo-hibernate/pull/133 specifies how Java types are mapped to BSON types. Actually, the mapping is not as direct, and it usually involves two other pieces: org.hibernate.type.descriptor.java.JavaType, org.hibernate.type.descriptor.jdbc.JdbcType. See Hibernate ORM User Guide 6.6: 3.2.44. Compositional basic mapping for more details, or a shorter version A Short Guide to Hibernate 7.2: 3.13. Compositional basic types.

Thus, we should have a table not of two columns (Java type, BSON type), but of four columns (Java type, JavaType, JdbcType / SQL type or code, BSON type). The Hibernate ORM documentation had a somewhat similar table previously, but not anymore.

Adding this information is beneficial to our users, as Hibernate ORM allows changing the default JavaType and JdbcType, and when users change those, the table will help them to understand how that affects the mapping.

This idea was expressed by slav.babanin@mongodb.com.