Why is :db.unique/identity only allowed on :db.cardinality/one?

Question

I'm curious about the rationale for only allowing :db.cardinality/one attributes to be :db.unique/identity? An immediate use case in the wild is email addresses, which uniquely identify an individual but an individual can have many email addresses.

Answer 1

I decided to not trust the documentation and, as of version 0.9.5697 of datomic-free, :db.cardinality/many attributes can be :db.unique/identity, in disagreement with:

https://docs.datomic.com/on-prem/schema/identity.html#unique-identities

Uniqueness can be declared on attributes of any value type, including
references (:db.type/ref). Only (:db.cardinality/one) attributes can
be unique.

In testing I found that the schema of a :db.cardinality/many :db.unique/identity attribute was accepted and that entity upsert worked fine across multiple instances of the attribute (i.e. the right behavior).

How can we get the documentation updated?