Cosmos: Use 1:1 mapping for .NET `Id` to JSON `id` unless explicitly configured otherwise

[ajcvickers]

Motivation

Currently we have a lot of rules that determine which properties get configured as keys, partition keys, alternate keys, discriminators, and do on. The intention here is to create a model that will fall into the pit-of-success for use with Cosmos. This works to some extent, but the problem is that it becomes very hard to follow what is actually happening, or why. This means that, for example, that it is difficult to know which properties form a relatively simple concept such as the JSON id property. And without knowing the definition of the id, everything else becomes confusing.

Proposal

Remove a lot of the magic from this area to create conventions that are easy to understand, while allowing additional configuration to be done explicitly, also in a non-magical way.

Principal

Based on discussions with the Cosmos folks, we will use the following principle:

• The EF primary key property Id discovered by convention should map 1:1 to the JSON id property, unless the developer explicitly configures something different.

Notes:

• This is likely what developers expect, and doing otherwise can cause confusion.
• The downside is that EF and Cosmos have different concepts of key spaces—EF has one key space per root entity type, Cosmos has one key space per logical partition.

Discriminators

• We will keep putting the discriminator into the model by convention.
  • However, if there is only one entity type in the container, then we won’t use it in queries that are generated. #20268
• The JSON id property will not have a discriminator added so as to keep it an easy-to-understand 1:1 mapping
  • Developers need to be aware that there is one key space per logical partition in a container.
  • We will provide a mechanism to go back to the old behavior

Note that partition keys will still be added to the EF primary key definition.

• This ensures that EF primary keys are unique across partitions, and that FK definitions can follow this.
• The partition key properties have no impact on id
• This means that the part of the primary key that isn’t partition keys will map 1:1 to JSON id. If this part is called Id then this is still Id to id mapping.

[roji]

We will provide a mechanism to go back to the old behavior

Just for completeness, mentioning @divega's additional suggestion of allowing users to integrate a discriminator into id, but one that's the same across the inheritance hierarchy (i.e. the root type's only), as opposed to the discriminator property that differs across entity types within the hierarchy. The reason to do this is that it would allow using ReadItem; with concrete discriminators, we don't know in advance what concrete type we're getting (which kind of Blog), so if the concrete discriminator is part of id, we can't use ReadItem.