We currently support the following dictionary representations:

    public enum DictionaryRepresentation
    {
        Dynamic,
        Document,
        ArrayOfArrays,
        ArrayOfDocuments
    }

The last 3 representations correspond to:

{ dictionary : { key1 : value1, ... } }
{ dictionary : [[key1, value1], ...] }
{ dictionary : [{ key1 : value1 }, ...] }

Each representation has its advantages. The first is probably the most natural representation and what most users would instinctively expect a Dictionary to be represented as. However, it can only be used when all they key values are strings and when the values of the strings are valid element names for a BSON document.

The current default representation is Dynamic, which means that the serializer examines the keys and uses the Document representation if possible, and falls back to the ArrayOfArrays representation if not.

Dynamic has pluses and minuses. On the plus side, serialization always succeeds and your Dictionary will be successfully saved to the database no matter what values the keys have. On the minus side, you will not have a consistent representation of your Dictionary values in your collection, because depending on the values of the keys one or the other representation will have been chosen. This is not a problem for round-tripping your Dictionary, but can be a huge problem if you need to write queries against your Dictionary values.

The task in this ticket is to reconsider whether we should just remove the Dynamic representation or perhaps at least make it not be the default.

It is tempting to make Document the default representation, but the problem with that is that if any of your keys have values that are not valid element names serialization will throw an exception. Is that acceptable?