Which row is Maria?
Two rows from a regional blood service's donor registry:
- 48213 · Maria Ferreira · born 14 May 1988 · Porto · deferred until 2 June
- 91877 · Maria Lopes · born 14 May 1988 · Braga · no deferrals
They are the same woman. She gave blood as Ferreira for thirteen years, then married, took her husband's surname and moved. At a mobile session in her new town the clerk searched for Maria Lopes and her birth date, found nobody, and registered a new donor. The deferral, a period during which a person must not give blood, lived only on the first row, so the session took her donation, and the unit had to be withdrawn once someone noticed the duplicate. Each row is accurate. The system had asked is there a donor with these details? when the question was is this the same person?
Same person, different details
An Entity is a domain object the business tracks by identity: it stays the same thing while its attributes change. Maria is the same donor with a new surname, address and phone, and everything attached to her (donations, deferrals) has to follow that one identity. Equality between two entities of the same kind is decided by their id, not by their values. Two donor objects with the id 48213 are the same donor even if one says Ferreira and the other Lopes; two donors with identical names and birthdays and different ids are two donors to the system; if two records turn out to be one person, as Maria's did, the fix is a merge, not equality by name.
Equality by id answers which donor?, not is this data current? Two copies of donor 48213 loaded an hour apart are equal as entities and can still disagree about her phone number. Which copy is current is a question for the code that loads and saves the donor, not for equals.
What does not get an id
Maria's address is not an entity. When she moves, the service replaces one value with another rather than tracking the old address as it changes, and two donors at the same flat hold equal, interchangeable addresses. Her blood group is a value too. These are the job of a Value Object: compared by their values, with no identity to follow, and usually immutable. The test is whether the business cares which one, or only what it says. A donation, on the other hand, is an entity: the service must be able to say which unit came from which session, even when two donations look identical on paper.
The donor and each donation are tracked by id. The address is a value: replaced whole when she moves, never tracked.
Where the id comes from
The obvious candidate is a natural key, something the person already has. A national identity number looks ideal until you meet the donors who do not have one in this country, and the ones whose number was typed with two digits swapped at registration. Email addresses and phone numbers change, and a phone number abandoned by one person can later be assigned to someone else. Name plus date of birth is what failed for Maria. A natural key is only as stable as the world outside your system lets it be.
So the service issues its own: a surrogate key, the donor number, generated by the registry at first registration, printed on a donor card and asked for at every session. It means nothing outside the system, which is exactly why nothing outside the system can change it. A number alone did not stop Maria's second row, which got one of its own; what changes is the step before issuing one. The national number stays as an attribute, useful for finding a likely match when a donor comes without her card, and the clerk's search becomes a step that proposes candidates rather than one that decides identity.
When the id is created matters too. If the database assigns it on insert, a new donor has no id until it is saved, and an equals that compares ids calls two unsaved donors equal, or never equal, depending on how it treats the missing value. An id generated in the application when the object is built, a UUID for instance, avoids that gap; the ways to generate one, and their costs, are in Unique ID generation.
A life, not a row
An entity has a lifecycle, and the identity has to survive all of it. A donor is registered, gives blood, is deferred and reinstated, goes quiet for years, comes back. When the service finds Maria's two records, it merges them: one id survives and absorbs the donations and deferrals, and the other is marked as merged into it, so a donation recorded under the old number still leads to her. The retired number must not be issued again: if it were, a donation recorded years ago under 91877 would lead to a stranger.
Moments in that life that other parts of the system react to, such as a deferral recorded, are often published as a Domain Event. When a donor and her donations must change together under one set of rules, they may form an Aggregate, with the donor as its root.
When sameness goes wrong
- Comparing entities by their attributes. Code that decides two donors are the same because name, birthday and address match will split one person into two when she moves, and merge two people who share those details. Compare by id; use attributes only to suggest a match for a person to confirm.
- Letting the id change. If the donor number is derived from something that can change, such as initials and birth year, then correcting a typo in the name moves her history to a new identity, and every reference held elsewhere points at nothing.
Try it in the Challenge
The Aggregate & Repository Challenge asks you to connect an aggregate to the entities and value objects it owns. Before drawing an edge, decide for each card whether the business would ever ask which one: if it would, it is an entity, so write on its card what identifies it and who issues that id; if not, make it a value object. Give the root entity the donor's treatment: its id written on its card, its name and address listed as attributes that can change around it.