While custom type support (added in PYTHON-1476) allows users to transform scalar BSON types, it doesn't allow for customized decoding of fields containing BSON container types - i.e. documents and arrays. While a custom document_class allows the user to customize the type of the entire document being deserialized from BSON, no equivalent mechanism exists that works at a higher degree of granularity - specifically at the field-level.

For instance, users can write an encoder that can enable them to transparently write a custom object to the database as a document, but there is no mechanism to re-create that same custom object when reading back the transformed document. At present, the only way to do this is for users to encode their custom types to a Binary subtype for which they can define a TypeDecoder but this would make it impossible to query that information in the database.

Ideally, it should be possible for a user to round-trip custom types from MongoDB. In order to track which fields need to be decoded to a custom type, we can use either:

• a type discriminator - essentially an extra, driver-added field to the document containing the BSON representation of the custom type. On read, the driver can check for the discriminator to determine whether custom decoding is required.
• a user-specified namespace path - the user can specify one or more namespaces corresponding to a given custom type. If a returned document is found to have one of the specified namespaces, the BSON bytes therein will be decoded based on the custom decoding rules specified by the user for the corresponding type.