Identifying Entities - Learning Module

Loading content...

0/246

Entity vs Attribute Distinction

The Fundamental Modeling Decision

After extracting nouns from requirements, you face a deceptively simple question for each candidate: Should this be a class or a property of another class?

This decision—entity versus attribute—is one of the most consequential in object-oriented design. Get it wrong, and you either:

Over-model: Create unnecessary classes for simple concepts, adding complexity and indirection
Under-model: Bury important domain concepts inside other classes, losing expressiveness and flexibility

Both errors compound over time. An over-modeled system becomes a maze of tiny classes doing almost nothing. An under-modeled system grows rigid as buried concepts need to evolve independently.

The challenge:

There's no universal rule. Address might be an entity in a shipping system but an attribute in a customer database. Price might be a simple number in one context and a complex object with currency, effective dates, and discount rules in another. Context determines the right choice.

What You Will Learn

By the end of this page, you will have a systematic framework for distinguishing entities from attributes. You'll learn the key criteria that guide this decision, see concrete examples across domains, and develop intuition for when to promote an attribute to an entity or demote an entity to an attribute.

Defining Entities and Attributes

Before distinguishing them, let's define precisely what we mean by entity and attribute in object-oriented design.

Entity (Class):

An entity is a distinct concept in your domain that:

Has identity — you can distinguish one instance from another
Has lifecycle — instances are created, modified, and potentially destroyed
May have behavior — operations that act on or with the entity
Is independently meaningful — makes sense to discuss on its own

Attribute (Property):

An attribute is a characteristic or quality of an entity that:

Describes the entity it belongs to
Has no independent meaning outside its owning entity
Is typically a primitive value or simple type
Changes with the entity, not independently
Is not individually addressable — you reference the entity, not the attribute alone

Entity vs Attribute Characteristics
Characteristic	Entity	Attribute
Identity	Has unique identity (ID)	No independent identity
Independence	Exists independently	Exists only as part of entity
Lifecycle	Has own lifecycle	Follows owning entity's lifecycle
Behavior	Often has methods	Usually just holds data
References	Referenced by ID from other entities	Accessed through owning entity
Persistence	Has own table/document	Stored within entity's record
Complexity	Can be arbitrarily complex	Usually simple/primitive

entity_vs_attribute_example.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
// Clear entity: Customer
// Has identity, lifecycle, behavior, independence
class Customer {
    id: string;                    // Identity
    name: string;                  // Attribute: simple property
    email: string;                 // Attribute: simple property
    registeredAt: Date;            // Attribute: simple property
    
    updateEmail(newEmail: string): void { /* behavior */ }
    deactivate(): void { /* lifecycle */ }
}
 
// Clear attribute: name
// No identity of its own, describes Customer, simple string
// You'd never ask "What's the ID of this name?"
 
// Ambiguous case: Address
// Is this an entity or an attribute?
 
// OPTION A: Address as an attribute (embedded/value object)
class CustomerWithAddressAttribute {
    id: string;
    name: string;
    street: string;      // Address fields as attributes
    city: string;
    state: string;
    zipCode: string;
    country: string;
}
 
// OPTION B: Address as a separate entity
class Address {
    id: string;          // Has identity
    street: string;
    city: string;
    state: string;
    zipCode: string;
    country: string;
    
    format(): string { /* behavior */ }
    validate(): ValidationResult { /* behavior */ }
}
 
class CustomerWithAddressEntity {
    id: string;
    name: string;
    addressId: string;   // References Address entity
    // or
    address: Address;    // Embedded reference
}
 
// Which is correct? It depends on the context and requirements!

The Entity Promotion Criteria

When should a candidate noun be promoted from a potential attribute to a full entity? Apply these criteria systematically:

Criterion 1: Identity Requirement

Does the concept need to be uniquely identified independent of its context?

If you need to say "this specific X" (not just "an X"), it needs identity → Entity
If you only reference X as a property of something else → Attribute

Criterion 2: Shared Reference

Is the concept referenced by multiple entities?

If multiple entities point to the same instance → Entity
If each owning entity has its own copy → Attribute (or Value Object)

Criterion 3: Independent Lifecycle

Can the concept exist or change independently of other entities?

If it can be created, modified, or deleted on its own → Entity
If it only exists as part of another entity → Attribute

Criterion 4: Significant Behavior

Does the concept have operations (methods) beyond simple get/set?

If it has meaningful business logic → Entity (or rich Value Object)
If it's purely data with no behavior → Likely Attribute

Criterion 5: Change Frequency Mismatch

Does this aspect change at a different rate than the rest of the entity?

If it changes independently or more frequently → Consider Entity
If it changes with the whole entity → Attribute

Quick Decision Flowchart

•Does it need a unique ID? → YES: Lean toward Entity
•Is it shared across entities? → YES: Entity (avoid duplication)
•Can it exist independently? → YES: Entity (has own lifecycle)
•Does it have complex behavior? → YES: At least Value Object, possibly Entity
•If NO to all above → Attribute is likely appropriate

promotion_criteria_examples.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
// EXAMPLE 1: Author in a Book System
// Applying the criteria to decide: Entity or Attribute?
 
// Criterion 1: Identity Requirement
// "I want to see all books by THIS author (ID: 123)"
// ✓ Needs identity → suggests Entity
 
// Criterion 2: Shared Reference
// Multiple books reference the same author
// ✓ Shared across entities → suggests Entity
 
// Criterion 3: Independent Lifecycle
// Authors exist before books are published
// Authors can be updated (biography) without changing books
// ✓ Independent lifecycle → suggests Entity
 
// Criterion 4: Significant Behavior
// Authors might have: calculateRoyalties(), getBibliography()
// ✓ Has business behavior → suggests Entity
 
// DECISION: Author should be an Entity
class Author {
    id: string;
    name: string;
    biography: string;
    birthDate: Date;
    
    getBibliography(): Book[] { /* ... */ }
    calculateRoyalties(period: DateRange): Money { /* ... */ }
}
 
class Book {
    id: string;
    title: string;
    authorId: string;  // References Author entity
}
 
 
// EXAMPLE 2: Page Count in a Book System
// Applying the criteria:
 
// Criterion 1: Identity Requirement
// "Show me page count #456" - nonsensical
// ✗ No identity needed → suggests Attribute
 
// Criterion 2: Shared Reference
// Each book has its own page count
// ✗ Not shared → suggests Attribute
 
// Criterion 3: Independent Lifecycle
// Page count doesn't change independently of book
// ✗ No independent lifecycle → suggests Attribute
 
// Criterion 4: Significant Behavior
// No operations on page count alone
// ✗ No behavior → suggests Attribute
 
// DECISION: Page count should be an Attribute
class Book {
    id: string;
    title: string;
    pageCount: number;  // Simple attribute
}
 
 
// EXAMPLE 3: Price in an E-commerce System
// This is where it gets interesting!
 
// Simple context: Product catalog display
// ✗ No independent identity needed
// ✗ Each product has its own price
// ✗ Price is just data
// → ATTRIBUTE is appropriate
 
class SimpleProduct {
    id: string;
    name: string;
    price: number;  // Attribute
}
 
// Complex context: Multi-currency, price history, promotions
// ✓ Prices have effective dates and need tracking
// ✓ Multiple products might share a price tier
// ✓ Complex calculation logic
// → ENTITY is appropriate
 
class PriceEntity {
    id: string;
    amount: number;
    currency: Currency;
    effectiveFrom: Date;
    effectiveTo: Date | null;
    
    isActive(): boolean { /* ... */ }
    convertTo(currency: Currency): PriceEntity { /* ... */ }
}
 
class ComplexProduct {
    id: string;
    name: string;
    priceId: string;  // References Price entity
}

Context Is King

The same concept can be an entity in one system and an attribute in another. 'Email' is an attribute in a simple CRM but might be an entity in an email marketing platform where email addresses have verification status, bounce history, and engagement metrics. Always consider your specific domain requirements.

Value Objects — The Middle Ground

Between entities and simple attributes lies a powerful concept: the Value Object. Value Objects bundle related attributes together with behavior, but unlike entities, they have no identity.

Value Object characteristics:

No identity — equality is based on attribute values, not ID
Immutable — cannot be changed after creation (create new instances instead)
Self-validating — enforce invariants in constructor
Behavior-rich — have methods that operate on their values
Replaceable — swapped wholesale, not modified in place

value_objects.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
// VALUE OBJECT: Money
// Groups amount and currency, has behavior, no identity
class Money {
    private constructor(
        readonly amount: number,
        readonly currency: Currency
    ) {
        if (amount < 0) throw new Error("Amount cannot be negative");
    }
    
    static of(amount: number, currency: Currency): Money {
        return new Money(amount, currency);
    }
    
    // Behavior: arithmetic operations
    add(other: Money): Money {
        if (this.currency !== other.currency) {
            throw new Error("Cannot add different currencies");
        }
        return Money.of(this.amount + other.amount, this.currency);
    }
    
    multiply(factor: number): Money {
        return Money.of(this.amount * factor, this.currency);
    }
    
    // Behavior: formatting
    format(): string {
        return `${this.currency} ${this.amount.toFixed(2)}`;
    }
    
    // Equality by value, not identity
    equals(other: Money): boolean {
        return this.amount === other.amount && 
               this.currency === other.currency;
    }
}
 
// Usage: Replace, don't mutate
let price = Money.of(100, Currency.USD);
price = price.multiply(1.1);  // Creates new Money, doesn't mutate
 
 
// VALUE OBJECT: Address
// More complex than primitives, but no identity
class Address {
    private constructor(
        readonly street: string,
        readonly city: string,
        readonly state: string,
        readonly zipCode: string,
        readonly country: string
    ) {
        this.validate();
    }
    
    static create(props: AddressProps): Address {
        return new Address(
            props.street,
            props.city,
            props.state,
            props.zipCode,
            props.country
        );
    }
    
    private validate(): void {
        if (!this.street || !this.city || !this.country) {
            throw new Error("Street, city, and country are required");
        }
        // Additional validation...
    }
    
    format(): string {
        return `${this.street}\n${this.city}, ${this.state} ${this.zipCode}\n${this.country}`;
    }
    
    isInternational(homeCountry: string): boolean {
        return this.country !== homeCountry;
    }
    
    equals(other: Address): boolean {
        return this.street === other.street &&
               this.city === other.city &&
               this.state === other.state &&
               this.zipCode === other.zipCode &&
               this.country === other.country;
    }
}
 
// VALUE OBJECT: DateRange
// Encapsulates start-end logic
class DateRange {
    private constructor(
        readonly start: Date,
        readonly end: Date
    ) {
        if (end < start) {
            throw new Error("End date must be after start date");
        }
    }
    
    static create(start: Date, end: Date): DateRange {
        return new DateRange(start, end);
    }
    
    contains(date: Date): boolean {
        return date >= this.start && date <= this.end;
    }
    
    overlaps(other: DateRange): boolean {
        return this.start <= other.end && this.end >= other.start;
    }
    
    getDurationInDays(): number {
        const msPerDay = 24 * 60 * 60 * 1000;
        return Math.ceil((this.end.getTime() - this.start.getTime()) / msPerDay);
    }
}

When to Use Each Approach
Modeling Choice	Use When	Examples
Primitive Attribute	Simple, single value; no invariants or behavior	name (string), age (number), isActive (boolean)
Value Object	Multiple related values; has behavior/invariants; no identity	Money, Address, DateRange, Email, PhoneNumber
Entity	Needs identity; independent lifecycle; referenced by multiple entities	Customer, Order, Product, Invoice

Value Objects Prevent Primitive Obsession

Primitive obsession is an anti-pattern where complex concepts are represented as simple primitives (strings, numbers). Value Objects cure this by encapsulating domain concepts with their behavior and validation. An Email Value Object validates format; a Money Value Object handles currency conversion. Don't model everything as strings and ints.

Common Entity/Attribute Decisions

Certain concepts appear repeatedly across domains, and recognizing patterns helps you make decisions faster. Here's guidance for commonly debated concepts:

Common Concept Decision Guide
Concept	Usually Entity When...	Usually Attribute/VO When...
Address	Shared (shipping addresses reused), has delivery preferences	Embedded per customer, no sharing
Phone Number	Part of contact management system, has verification	Simple string for contact purposes
Email	Email marketing system, needs bounce/engagement tracking	Just a contact field on User
Price	Price history needed, multi-currency, tiered pricing	Simple current price per product
Date/Time	Almost never; use Value Objects (DateTime, DateRange)	Primitive Date is usually fine
Location (lat/long)	Geospatial queries, place information attached	Just coordinates for one-off storage
Comment	Has replies, edits, likes; referenced independently	Simple text note embedded in parent
Tag	Tag library with descriptions, shared across items	Just a list of strings on an item
Category	Has hierarchy, metadata, used for navigation	Just a string label
Status	Has transitions, history, attached metadata	Simple enum value

common_decisions.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
// EXAMPLE: Category - When is it an Entity vs Attribute?
 
// SCENARIO A: E-commerce with category navigation
// Categories have hierarchy, descriptions, images
// Products belong to category; users browse by category
// → Entity
 
class Category {
    id: string;
    name: string;
    description: string;
    parentId: string | null;  // Hierarchy
    imageUrl: string;
    seoMetadata: SEOMetadata;
    
    getAncestors(): Category[] { /* ... */ }
    getSubcategories(): Category[] { /* ... */ }
    getBreadcrumb(): string { /* ... */ }
}
 
class Product {
    id: string;
    name: string;
    categoryId: string;  // References Category entity
}
 
 
// SCENARIO B: Blog post with simple tags
// Tags are just labels, no hierarchy or metadata
// → Attribute (array of strings)
 
class BlogPost {
    id: string;
    title: string;
    content: string;
    tags: string[];  // Simple attribute array
}
 
 
// EXAMPLE: Status - Enum vs Entity
 
// SCENARIO A: Simple order status
// Fixed set of statuses, no transitions tracked
// → Enum
 
enum OrderStatus {
    PENDING = "PENDING",
    CONFIRMED = "CONFIRMED",
    SHIPPED = "SHIPPED",
    DELIVERED = "DELIVERED",
    CANCELLED = "CANCELLED"
}
 
class SimpleOrder {
    id: string;
    status: OrderStatus;  // Enum attribute
}
 
 
// SCENARIO B: Workflow with status transitions
// Status changes tracked with timestamps and actors
// Transition rules enforced
// → Embedded Value Object or Related Entity
 
class StatusChange {
    timestamp: Date;
    fromStatus: OrderStatus;
    toStatus: OrderStatus;
    changedBy: string;
    reason?: string;
}
 
class WorkflowOrder {
    id: string;
    currentStatus: OrderStatus;
    statusHistory: StatusChange[];  // Tracks all transitions
    
    transitionTo(newStatus: OrderStatus, actor: string, reason?: string): void {
        // Validates transition is allowed
        // Records in history
    }
}

Signs You've Made the Wrong Choice

Design decisions aren't permanent. As you develop the system, certain patterns emerge that suggest you've over-modeled or under-modeled. Recognizing these signs early lets you refactor before complexity compounds.

Signs of Over-Modeling (Should Be Attribute)

•Anemic class: Entity has only getters/setters, no behavior
•One-to-one mandatory: Every parent has exactly one child, always together
•No independent queries: You never fetch the entity alone, always with parent
•Same lifecycle: Entity always created and deleted with parent
•Trivial ID: The ID is rarely used except for foreign key joins
•Copy everywhere: You copy all fields when embedding rather than referencing

Signs of Under-Modeling (Should Be Entity)

•Repeated attribute groups: Same set of fields appears in multiple classes
•Update anomalies: Changing one instance doesn't update copies elsewhere
•Complex validation: Many rules around a set of related attributes
•Behavior growing: Methods accumulating around specific attribute set
•Querying difficulty: You need to query/filter by embedded attributes often
•Reference from outside: Other entities want to point to this 'attribute set'

refactoring_examples.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
// SIGN OF OVER-MODELING: Anemic entity with no behavior
 
// ❌ This entity is over-modeled - it's just data
class CustomerPreferences {
    id: string;
    customerId: string;
    emailNotifications: boolean;
    smsNotifications: boolean;
    theme: 'light' | 'dark';
    language: string;
    
    // No methods beyond getters/setters
}
 
// ✅ Should be embedded attributes or Value Object
class Customer {
    id: string;
    name: string;
    // Embedded as Value Object
    preferences: {
        emailNotifications: boolean;
        smsNotifications: boolean;
        theme: 'light' | 'dark';
        language: string;
    };
}
 
 
// SIGN OF UNDER-MODELING: Repeated attribute groups
 
// ❌ Same address fields duplicated
class Customer {
    id: string;
    name: string;
    // Billing address
    billingStreet: string;
    billingCity: string;
    billingState: string;
    billingZip: string;
    billingCountry: string;
    // Shipping address
    shippingStreet: string;
    shippingCity: string;
    shippingState: string;
    shippingZip: string;
    shippingCountry: string;
}
 
// ✅ Extract to Value Object (or Entity if shared)
class Address {
    readonly street: string;
    readonly city: string;
    readonly state: string;
    readonly zip: string;
    readonly country: string;
    
    format(): string { /* ... */ }
    validate(): void { /* ... */ }
}
 
class CustomerFixed {
    id: string;
    name: string;
    billingAddress: Address;
    shippingAddress: Address;
}
 
 
// SIGN OF UNDER-MODELING: Complex validation scattered
 
// ❌ Phone validation logic scattered
class Contact {
    phone: string;  // Just a string
    
    validatePhone(): boolean {
        // Complex regex, country code handling, etc.
        // This logic doesn't belong here!
    }
}
 
// ✅ Extract to Value Object with encapsulated validation
class PhoneNumber {
    private constructor(
        readonly countryCode: string,
        readonly number: string
    ) {}
    
    static parse(input: string): PhoneNumber {
        // Parsing and validation logic here
        const { countryCode, number } = this.parseAndValidate(input);
        return new PhoneNumber(countryCode, number);
    }
    
    private static parseAndValidate(input: string): { countryCode: string; number: string } {
        // Complex validation encapsulated
    }
    
    format(): string {
        return `+${this.countryCode} ${this.number}`;
    }
    
    isInternational(homeCountry: string): boolean {
        return this.countryCode !== homeCountry;
    }
}
 
class ContactFixed {
    phone: PhoneNumber;  // Value Object, not primitive
}

Refactoring Is Normal

If you discover you've made the wrong entity/attribute choice, that's not failure—it's learning. Requirements evolve, and initial assumptions prove incorrect. The key is recognizing the signs early and refactoring before the wrong abstraction becomes deeply embedded in your codebase.

The Domain-Driven Design Perspective

Domain-Driven Design (DDD) provides precise terminology that clarifies the entity/attribute distinction:

DDD Terminology:

DDD Concept	Definition	Equivalent
Entity	Object defined by identity, not attributes	Class with ID
Value Object	Object defined by attributes, immutable, no identity	Complex attribute
Aggregate	Cluster of entities/VOs with a root entity	Transactional boundary
Aggregate Root	Entry point to aggregate, only external reference point	Main entity

DDD emphasizes that the distinction isn't just about code—it reflects how domain experts think about concepts.

ddd_modeling.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
// DDD-STYLE MODELING: Order Aggregate
 
// AGGREGATE ROOT: Order
// - Has identity (orderId)
// - Entry point for all operations
// - Only reference point from outside the aggregate
class Order {
    readonly orderId: OrderId;      // Value Object for ID
    private status: OrderStatus;
    private lineItems: LineItem[];  // Entities within aggregate
    private shippingAddress: Address;  // Value Object
    private billingAddress: Address;   // Value Object
    readonly customerId: CustomerId;   // Reference to different aggregate
    
    // All operations go through aggregate root
    addItem(product: ProductId, quantity: number, price: Money): void {
        this.lineItems.push(new LineItem(product, quantity, price));
    }
    
    removeItem(lineItemId: LineItemId): void {
        this.lineItems = this.lineItems.filter(item => !item.id.equals(lineItemId));
    }
    
    calculateTotal(): Money {
        return this.lineItems.reduce(
            (sum, item) => sum.add(item.subtotal()),
            Money.zero(Currency.USD)
        );
    }
    
    ship(carrier: string, trackingNumber: string): void {
        if (this.status !== OrderStatus.PAID) {
            throw new Error("Cannot ship unpaid order");
        }
        this.status = OrderStatus.SHIPPED;
        // Domain event would be raised here
    }
}
 
// ENTITY WITHIN AGGREGATE: LineItem
// - Has identity (within the aggregate)
// - Cannot be referenced from outside Order
// - Lifecycle bound to Order
class LineItem {
    readonly id: LineItemId;
    readonly productId: ProductId;
    private quantity: number;
    private unitPrice: Money;
    
    subtotal(): Money {
        return this.unitPrice.multiply(this.quantity);
    }
    
    updateQuantity(newQuantity: number): void {
        if (newQuantity < 1) throw new Error("Quantity must be positive");
        this.quantity = newQuantity;
    }
}
 
// VALUE OBJECTS: Immutable, equality by value
class OrderId {
    constructor(readonly value: string) {
        if (!value || value.length === 0) {
            throw new Error("OrderId cannot be empty");
        }
    }
    
    equals(other: OrderId): boolean {
        return this.value === other.value;
    }
}
 
class Money {
    private constructor(
        readonly amount: number,
        readonly currency: Currency
    ) {}
    
    static of(amount: number, currency: Currency): Money {
        return new Money(amount, currency);
    }
    
    static zero(currency: Currency): Money {
        return new Money(0, currency);
    }
    
    add(other: Money): Money {
        this.assertSameCurrency(other);
        return new Money(this.amount + other.amount, this.currency);
    }
    
    multiply(factor: number): Money {
        return new Money(this.amount * factor, this.currency);
    }
    
    private assertSameCurrency(other: Money): void {
        if (this.currency !== other.currency) {
            throw new Error("Currency mismatch");
        }
    }
}
 
class Address {
    constructor(
        readonly street: string,
        readonly city: string,
        readonly state: string,
        readonly zipCode: string,
        readonly country: string
    ) {
        // Validation in constructor
    }
    
    // Value Objects are compared by value
    equals(other: Address): boolean {
        return this.street === other.street &&
               this.city === other.city &&
               this.state === other.state &&
               this.zipCode === other.zipCode &&
               this.country === other.country;
    }
}

Think in Terms of Transactions

A key DDD insight: Aggregate boundaries are transactional boundaries. Everything inside an aggregate should be modifiable in a single transaction. If you find yourself needing to modify two 'entities' separately in different transactions, they belong to different aggregates.

Practical Decision Exercise

Let's practice making entity/attribute decisions with a realistic scenario. Consider an Ride-Sharing Application with these requirements:

Riders request rides from one location to another
Drivers accept ride requests based on their availability
Each ride has a pickup and dropoff location
Drivers have vehicles with specific characteristics (make, model, color, license plate)
Riders rate drivers after each completed ride
Payment is processed based on distance and time
Riders can save favorite locations (like 'Home' and 'Work')
Drivers can set a service area where they're willing to accept rides

Analyzing key concepts:

Entity vs Attribute Analysis for Ride-Sharing
Concept	Analysis	Decision
Rider	Has ID, lifecycle, behavior (request ride, rate driver)	✅ Entity
Driver	Has ID, lifecycle, behavior (accept ride, set availability)	✅ Entity
Ride/Trip	Has ID, lifecycle (requested→accepted→completed), state transitions	✅ Entity
Location (lat/lng)	Used by many entities, no independent identity	Value Object
Pickup Location	Just a Location at a moment in time	Attribute (Location VO) on Ride
Vehicle	Has ID (license plate), could be swapped, has own details	⚠️ Entity OR embedded—depends on complexity
Rating	Has ID, might be reviewed/responded to, might be standalone record	⚠️ Entity if featured; Attribute if simple 1-5
Payment	Has ID, has lifecycle (pending→completed), transaction record	✅ Entity
Favorite Location	Saved for rider, has name ('Home'), might be shared	⚠️ Likely Entity (has name, pattern of use)
Service Area	Complex geometry, might be shared/templated	⚠️ Value Object or Entity based on complexity

ride_sharing_model.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
// Ride-Sharing Domain Model
 
// VALUE OBJECT: Location
class Location {
    constructor(
        readonly latitude: number,
        readonly longitude: number
    ) {
        this.validate();
    }
    
    private validate(): void {
        if (this.latitude < -90 || this.latitude > 90) {
            throw new Error("Invalid latitude");
        }
        if (this.longitude < -180 || this.longitude > 180) {
            throw new Error("Invalid longitude");
        }
    }
    
    distanceTo(other: Location): number {
        // Haversine formula
        return calculateDistance(this, other);
    }
    
    equals(other: Location): boolean {
        return this.latitude === other.latitude &&
               this.longitude === other.longitude;
    }
}
 
// ENTITY: Rider
class Rider {
    readonly id: RiderId;
    private name: string;
    private phone: PhoneNumber;  // Value Object
    private email: Email;        // Value Object
    private paymentMethods: PaymentMethod[];
    private favoriteLocations: FavoriteLocation[];  // Entities owned by Rider
    
    requestRide(pickup: Location, dropoff: Location): RideRequest {
        return new RideRequest(this.id, pickup, dropoff);
    }
    
    rateDriver(ride: Ride, rating: number, comment?: string): Rating {
        return new Rating(ride.id, this.id, ride.driverId, rating, comment);
    }
    
    addFavoriteLocation(name: string, location: Location): void {
        this.favoriteLocations.push(new FavoriteLocation(name, location));
    }
}
 
// ENTITY: FavoriteLocation (belongs to Rider aggregate)
class FavoriteLocation {
    readonly id: FavoriteLocationId;
    readonly name: string;        // "Home", "Work", etc.
    readonly location: Location;  // Value Object
    
    constructor(name: string, location: Location) {
        this.id = FavoriteLocationId.generate();
        this.name = name;
        this.location = location;
    }
}
 
// ENTITY: Driver
class Driver {
    readonly id: DriverId;
    private name: string;
    private phone: PhoneNumber;
    private email: Email;
    private vehicle: Vehicle;      // Entity or Value Object?
    private serviceArea: ServiceArea;  // Value Object
    private status: DriverStatus;
    
    isAvailable(): boolean {
        return this.status === DriverStatus.ONLINE;
    }
    
    acceptRide(request: RideRequest): Ride {
        if (!this.isAvailable()) {
            throw new Error("Driver is not available");
        }
        return Ride.create(request, this.id);
    }
}
 
// DECISION: Vehicle as embedded Value Object (simple model)
// If vehicles need separate management, tracking, insurance → Entity
class Vehicle {
    constructor(
        readonly make: string,
        readonly model: string,
        readonly year: number,
        readonly color: string,
        readonly licensePlate: string
    ) {}
    
    getDisplayName(): string {
        return `${this.color} ${this.year} ${this.make} ${this.model}`;
    }
}
 
// ENTITY: Ride (core transaction entity)
class Ride {
    readonly id: RideId;
    readonly riderId: RiderId;
    readonly driverId: DriverId;
    readonly pickupLocation: Location;   // Value Object
    readonly dropoffLocation: Location;  // Value Object
    private status: RideStatus;
    private startTime: Date | null;
    private endTime: Date | null;
    
    static create(request: RideRequest, driverId: DriverId): Ride {
        // Factory method
    }
    
    start(): void {
        this.status = RideStatus.IN_PROGRESS;
        this.startTime = new Date();
    }
    
    complete(): void {
        this.status = RideStatus.COMPLETED;
        this.endTime = new Date();
    }
    
    calculateFare(): Money {
        // Based on distance and time
    }
}
 
// ENTITY: Rating (if we need to manage/respond to ratings)
// Could be Value Object embedded in Ride if ratings are simple
class Rating {
    readonly id: RatingId;
    readonly rideId: RideId;
    readonly riderId: RiderId;
    readonly driverId: DriverId;
    readonly score: number;  // 1-5
    readonly comment: string | null;
    readonly createdAt: Date;
    private response: string | null;
    
    constructor(
        rideId: RideId,
        riderId: RiderId,
        driverId: DriverId,
        score: number,
        comment?: string
    ) {
        if (score < 1 || score > 5) {
            throw new Error("Rating must be 1-5");
        }
        this.id = RatingId.generate();
        this.rideId = rideId;
        this.riderId = riderId;
        this.driverId = driverId;
        this.score = score;
        this.comment = comment ?? null;
        this.createdAt = new Date();
        this.response = null;
    }
    
    addDriverResponse(response: string): void {
        this.response = response;
    }
}

Summary: Entity vs Attribute Distinction

You now have a framework for one of the most important decisions in object-oriented design: determining whether a concept should be modeled as an entity (class) or an attribute (property).

Key Takeaways

•Identity is the key differentiator — Entities have unique identity; attributes don't exist independently
•Apply the five criteria — Identity, shared reference, independent lifecycle, significant behavior, change frequency
•Value Objects are the middle ground — Complex attributes with behavior but no identity
•Context determines the answer — The same concept may be entity or attribute in different systems
•Watch for warning signs — Anemic entities should become attributes; growing attributes should become entities
•DDD provides vocabulary — Entities, Value Objects, and Aggregates formalize these distinctions

What's next:

Not all entities are equally important. Some are essential to fulfilling core requirements; others are nice-to-have extensions. The next page explores how to distinguish essential from optional entities—a skill that helps you prioritize your design effort and avoid scope creep.

Page Complete

You're now equipped to make entity versus attribute decisions systematically. This skill prevents both over-engineering (too many tiny classes) and under-modeling (buried concepts that should be explicit). Next, we'll learn to distinguish essential entities from optional ones to focus our design efforts.