Low-Level DesignEntities, Attributes, and Behaviors

Entities, Attributes, and Behaviors

LevelBeginner

Duration60 mins

TopicEntities, Attributes, and Behaviors

2 / 4

Attributes — Properties That Describe Entities

Describing the Things in Your System

In the previous page, we established that entities are the identifiable "things" in your system—the nouns with continuity and meaning. But an entity without description is like a noun without adjectives: grammatically correct but informationally useless.

A User entity exists, but what do we know about it? What's their email? Their name? When did they join? Are they verified? What plan are they on? These descriptive elements are what we call attributes—the properties that give entities their characteristics and make them useful for business logic.

What You Will Learn

By the end of this page, you will understand what attributes are, how to identify which attributes an entity needs, the critical distinction between essential and incidental attributes, and how to design attribute sets that are complete yet focused. You'll develop the skill to model entities with exactly the right level of detail.

What Are Attributes?

Attributes are the properties that describe an entity's characteristics and state. They answer questions about the entity:

What is its name? → name attribute
When was it created? → createdAt attribute
What's its current status? → status attribute
How much does it cost? → price attribute
Is it active? → isActive attribute

In code, attributes typically manifest as instance variables (fields) of a class. They hold the data that makes one instance distinguishable from another instance of the same type.

Entity with Attributes
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
class Product {
    // Identity
    private readonly id: string;
    
    // Descriptive attributes
    private name: string;
    private description: string;
    private category: Category;
    
    // Pricing attributes
    private price: Money;
    private discount: Percentage;
    
    // Inventory attributes
    private stockQuantity: number;
    private reorderThreshold: number;
    
    // State attributes
    private status: ProductStatus;
    private isVisible: boolean;
    
    // Temporal attributes
    private readonly createdAt: Date;
    private updatedAt: Date;
    
    constructor(
        id: string,
        name: string,
        price: Money,
        category: Category
    ) {
        this.id = id;
        this.name = name;
        this.price = price;
        this.category = category;
        this.createdAt = new Date();
        this.updatedAt = new Date();
        // ... defaults for other fields
    }
}

Attributes vs. Identity

While we often discuss the entity's ID alongside attributes, identity is conceptually separate. Identity determines WHICH entity something is; attributes describe WHAT the entity is like. The ID could be considered a special attribute, but it's useful to keep the distinction clear in your mental model.

Categories of Attributes

Not all attributes are alike. Understanding the different categories helps you design complete, well-organized entities. Let's examine the major categories:

Attribute Categories
Category	Purpose	Examples	Design Considerations
Identifying	Distinguish instances; may be business-meaningful	ID, SKU, email, order number	Immutable after creation; must be unique within scope
Descriptive	Core characteristics of the entity	Name, title, description, bio	Often user-facing; consider localization
Categorical	Classify or type the entity	Category, type, role, tier	Use enums or reference entities; validates against fixed lists
Quantitative	Numeric measurements or amounts	Price, quantity, balance, rating	Type carefully (Money vs float); handle precision
Temporal	Time-related tracking	createdAt, updatedAt, expiresAt, birthDate	Consider timezone; some are immutable (createdAt)
State	Current status in lifecycle	status, isActive, isVerified, phase	Often governs allowed operations; model state machines
Relational	References to other entities	userId, categoryId, parentId	ID references for loose coupling; consider cascading
Computed/Derived	Calculated from other attributes	fullName, age, totalPrice	Don't store if easily computed; cache if expensive

Why categorization matters:

Understanding attribute categories helps you:

Ensure completeness — Have you covered all the categories relevant to your entity?
Apply appropriate types — Temporal attributes need Date types, quantitative attributes need appropriate numeric types
Manage mutability — Identification attributes are immutable; state attributes are specifically for controlled change
Design accessors properly — Some attributes need validation on set; some are read-only
Plan persistence — Different categories may have different database strategies (indexed, encrypted, etc.)

Not Every Category for Every Entity

Not every entity needs every category of attribute. A simple value-like entity might only have descriptive and quantitative attributes. An aggregate root might have all categories. The categories are a checklist to prompt completeness, not a required structure.

Essential vs. Incidental Attributes

This is one of the most important distinctions in attribute modeling. Essential attributes are fundamental to what the entity IS. Incidental attributes are nice-to-have details that could be absent or different without changing the entity's fundamental nature.

The distinction matters for:

Deciding which attributes are required vs. optional
Determining what goes in the entity vs. in related objects
Prioritizing which attributes to implement first
Understanding invariants the entity must maintain

Essential Attributes

•Required for entity existence — The entity cannot be valid without them
•Core to identity or purpose — They define what the entity fundamentally is
•Stable over time — While they may change, their presence is constant
•Drive key business logic — Essential for the entity to participate in domain operations
•Examples: Order needs items and customer; User needs identifier; Product needs price

Incidental Attributes

•Optional or supplementary — The entity is valid without them
•Enhancing, not defining — They add detail but don't change fundamental nature
•May come later — Often populated after entity creation
•Context-dependent — Their relevance may vary by use case
•Examples: User's bio, profile picture; Product's detailed description; Order's gift message

The Essential Attribute Test:

For each attribute, ask yourself:

Can the entity exist without it? If the entity can be created and function meaningfully without this attribute, it's likely incidental.
Does removing it change what the entity IS? A Product without a price isn't really a product in commerce terms. A User without a bio is still a user.
Is it required by the core use cases? Essential attributes are needed for the primary operations. Incidental attributes support secondary features.
Would a domain expert consider it fundamental? Ask someone who works in the domain—is this attribute central to understanding the concept?

Essential vs Incidental Example
TypeScript
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
class User {
    // === ESSENTIAL ATTRIBUTES ===
    // Without these, it's not a valid user
    
    private readonly id: string;           // Must have identity
    private email: string;                 // Primary login credential
    private passwordHash: string;          // Required for authentication
    private readonly createdAt: Date;      // When the account was created
    private status: UserStatus;            // Account state (active/suspended)
    
    // === INCIDENTAL ATTRIBUTES ===
    // Entity is valid without these; they enhance but don't define
    
    private displayName?: string;          // Optional; can use email as fallback
    private avatarUrl?: string;            // Nice to have; default avatar fine
    private bio?: string;                  // Completely optional profile info
    private phoneNumber?: string;          // Optional second factor
    private timezone?: string;             // Defaults to UTC if not set
    private locale?: string;               // Defaults to en-US
    private lastLoginAt?: Date;            // Tracking, not existence
    
    constructor(id: string, email: string, passwordHash: string) {
        // Essential attributes are REQUIRED in constructor
        this.id = id;
        this.email = email;
        this.passwordHash = passwordHash;
        this.createdAt = new Date();
        this.status = UserStatus.Active;
        
        // Incidental attributes have sensible defaults or are undefined
    }
    
    // Essential operations work with essential attributes
    authenticate(password: string): boolean {
        return this.verifyPassword(password) && 
               this.status === UserStatus.Active;
    }
    
    // Incidental attributes can be set later
    updateProfile(updates: Partial<UserProfile>): void {
        if (updates.displayName !== undefined) {
            this.displayName = updates.displayName;
        }
        if (updates.bio !== undefined) {
            this.bio = updates.bio;
        }
        // ...
    }
}

Incidental Doesn't Mean Unimportant

Incidental attributes are often very important for user experience and business value. A profile picture makes users more engaged. A gift message makes an order special. 'Incidental' only means the entity can exist and function at a basic level without them—not that they're unimportant to your product.

Attribute Types and Type Safety

Choosing the right types for attributes is crucial for correctness, safety, and clarity. Poor typing leads to bugs, confusion, and defensive code scattered throughout your codebase.

Let's explore best practices for attribute typing:

Primitive Obsession: The Anti-Pattern

One of the most common mistakes is using primitive types (string, number, boolean) for everything. This leads to:

No validation at boundaries — A string can hold invalid emails, negative prices, malformed UUIDs
Meaning encoded in variable names only — price: number doesn't tell you the currency or precision
Easy to confuse similar-typed values — Swapping userId and orderId both typed as string compiles fine
Validation logic scattered everywhere — Is this email valid? Check in 47 places...

Primitive Obsession vs Strong Types
TypeScript
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
// ❌ PRIMITIVE OBSESSION — Easy to make mistakes
class WeakOrder {
    customerId: string;     // Is this a UUID? An email? Who knows
    amount: number;         // In dollars? Cents? Bitcoin?
    email: string;          // Could be "not_an_email" 
    discount: number;       // 0.1 means 10%? Or $0.10?
}
 
// Bugs are easy:
const order = new WeakOrder();
order.customerId = order.email;  // Compiles! Both strings
order.amount = -500;             // Compiles! Just a number
order.discount = 150;            // 150% off? Compiles fine!
 
// ✅ STRONG TYPING — Type system catches mistakes
 
// Value Objects that validate and encapsulate
class CustomerId {
    private readonly value: string;
    
    constructor(value: string) {
        if (!this.isValidUUID(value)) {
            throw new InvalidCustomerIdError(value);
        }
        this.value = value;
    }
    
    private isValidUUID(value: string): boolean {
        return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
            .test(value);
    }
    
    toString(): string { return this.value; }
}
 
class Money {
    constructor(
        private readonly amount: number,
        private readonly currency: Currency
    ) {
        if (amount < 0) {
            throw new NegativeAmountError(amount);
        }
    }
    
    add(other: Money): Money {
        if (!this.currency.equals(other.currency)) {
            throw new CurrencyMismatchError(this.currency, other.currency);
        }
        return new Money(this.amount + other.amount, this.currency);
    }
}
 
class EmailAddress {
    private readonly value: string;
    
    constructor(value: string) {
        if (!this.isValidEmail(value)) {
            throw new InvalidEmailError(value);
        }
        this.value = value.toLowerCase(); // Normalize
    }
    
    private isValidEmail(value: string): boolean {
        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
    }
}
 
class Percentage {
    private readonly value: number; // 0 to 100
    
    constructor(value: number) {
        if (value < 0 || value > 100) {
            throw new InvalidPercentageError(value);
        }
        this.value = value;
    }
    
    applyTo(amount: Money): Money {
        return amount.multiply(this.value / 100);
    }
}
 
// Now the Order is type-safe
class StrongOrder {
    customerId: CustomerId;       // Can't be confused with other IDs
    amount: Money;                // Currency is explicit, can't be negative
    customerEmail: EmailAddress;  // Guaranteed valid format
    discount: Percentage;         // 0-100, can't be 150%
}

When to Create Custom Types:

Not every attribute needs its own type. Create custom types (also called value objects) when:

Validation is required — Emails, phone numbers, currencies, etc.
Confusion is possible — Multiple attributes with the same primitive type (string IDs that could be swapped)
Operations are domain-specific — Money has arithmetic with currency checks; Percentage has specific behavior
The concept is reused — EmailAddress appears across User, Contact, Invoice, etc.

Common Value Objects to Create

•Money — Amount + currency, with arithmetic that respects currency rules
•EmailAddress — Validated, normalized email string
•PhoneNumber — Country code + number, validated format
•DateRange — Start + end, with invariant that start ≤ end
•Coordinates — Latitude + longitude, validated ranges
•Percentage — 0-100 (or 0-1) with application logic
•Slug — URL-safe string with validation and normalization
•Typed IDs — UserId, OrderId, ProductId as distinct types

Start Simple, Upgrade When Burned

You don't need to create custom types for everything upfront. Start with primitives for simple cases. When bugs appear because of primitive confusion or scattered validation, that's the signal to introduce a value object. Pragmatic iteration beats premature abstraction.

Designing Complete Attribute Sets

How do you know if you've captured all the right attributes for an entity? How do you avoid both over-specification (too many attributes) and under-specification (missing critical ones)?

Here's a systematic approach to designing complete attribute sets:

Attribute Discovery Process

•List all use cases — What operations will this entity participate in? Reading, writing, querying, displaying, reporting, integrating...
•Extract data needs per use case — For each use case, what data about this entity is needed? This reveals required attributes.
•Identify identifying attributes — What makes one instance distinguishable from another? This is your ID strategy.
•Add lifecycle tracking — createdAt, updatedAt, status fields that track entity lifecycle.
•Consider audit requirements — Do you need createdBy, updatedBy? Version numbers for optimistic locking?
•Map relationships — Which other entities does this connect to? Add reference IDs.
•Review with domain experts — Ask business stakeholders: What information do you need to know about a [Entity]?
•Prune and prioritize — Mark attributes as essential vs incidental. Remove anything truly unnecessary.

Worked Example: Designing Order Attributes

Let's design the attributes for an Order entity in an e-commerce system.

Use cases:

Customer places order → Need items, shipping address, payment method
Customer views order status → Need status, tracking info
Warehouse fulfills order → Need items, shipping address, priority
Finance generates reports → Need totals, dates, payment details
Customer support resolves issues → Need all of the above plus notes

Complete Order Attributes
TypeScript
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
class Order {
    // === IDENTIFICATION ===
    private readonly id: OrderId;
    private readonly orderNumber: OrderNumber;  // Human-readable: ORD-2024-00123
    
    // === CORE RELATIONSHIPS ===
    private readonly customerId: CustomerId;
    private readonly items: OrderItem[];
    
    // === FINANCIAL ===
    private readonly subtotal: Money;
    private readonly taxAmount: Money;
    private readonly shippingCost: Money;
    private readonly discountApplied: Money;
    private readonly total: Money;
    private paymentId?: PaymentId;
    private paymentStatus: PaymentStatus;
    
    // === SHIPPING ===
    private shippingAddress: Address;        // Snapshot at order time
    private billingAddress: Address;
    private shippingMethod: ShippingMethod;
    private trackingNumber?: string;
    private estimatedDelivery?: Date;
    
    // === LIFECYCLE ===
    private status: OrderStatus;             // Draft, Confirmed, Paid, Shipped, Delivered, Cancelled
    private readonly createdAt: Date;
    private updatedAt: Date;
    private confirmedAt?: Date;
    private shippedAt?: Date;
    private deliveredAt?: Date;
    private cancelledAt?: Date;
    
    // === OPERATIONAL ===
    private priority: OrderPriority;
    private notes: OrderNote[];              // Internal customer service notes
    private giftMessage?: string;            // Customer-facing 
    
    // === AUDIT ===
    private readonly createdBy?: UserId;     // If created by staff on behalf
    private lastModifiedBy?: UserId;
    private version: number;                 // Optimistic locking
}

Don't Store What You Can Compute

Notice we store subtotal, taxAmount, shippingCost, and total as snapshots. In many systems, you might compute total from items. But for orders, we snapshot because prices/taxes may change after placement. The rule: don't store what you can compute UNLESS there's a business reason to preserve the snapshot.

Attribute Validation and Invariants

Attributes don't exist in isolation—they must satisfy constraints and maintain consistency with each other. These constraints are called invariants: conditions that must always be true for the entity to be in a valid state.

There are three levels of attribute validation:

Validation Levels
Level	What It Validates	Where It's Enforced	Examples
Type-Level	Valid format/value for a single attribute	In the type/value object	Email format, positive amounts, valid UUID
Attribute-Level	Valid value for this attribute in this entity	In setters or entity methods	Username length 3-50, description max 1000 chars
Entity-Level	Consistency between multiple attributes	In entity methods, especially state transitions	endDate > startDate, total = sum(items), status transitions

Validation at All Levels
TypeScript
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
// Type-level validation: EmailAddress
class EmailAddress {
    private readonly value: string;
    
    constructor(value: string) {
        // Validates email format once, at construction
        if (!this.isValidFormat(value)) {
            throw new InvalidEmailError(value);
        }
        this.value = value.toLowerCase();
    }
    
    private isValidFormat(value: string): boolean {
        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
    }
}
 
// Entity with attribute-level and entity-level validation
class Event {
    private readonly id: EventId;
    private title: string;
    private description: string;
    private startTime: Date;
    private endTime: Date;
    private maxAttendees: number;
    private attendees: UserId[] = [];
    private status: EventStatus = EventStatus.Draft;
    
    constructor(id: EventId, title: string, start: Date, end: Date) {
        this.id = id;
        this.setTitle(title);           // Attribute-level validation
        this.setTimeRange(start, end);  // Entity-level validation
    }
    
    // Attribute-level: validates single attribute constraints
    private setTitle(title: string): void {
        if (title.length < 3 || title.length > 200) {
            throw new ValidationError("Title must be 3-200 characters");
        }
        this.title = title.trim();
    }
    
    // Entity-level: validates cross-attribute constraints
    private setTimeRange(start: Date, end: Date): void {
        if (end <= start) {
            throw new ValidationError("End time must be after start time");
        }
        if (start < new Date()) {
            throw new ValidationError("Cannot create events in the past");
        }
        this.startTime = start;
        this.endTime = end;
    }
    
    // Entity-level: validates state + capacity
    registerAttendee(userId: UserId): void {
        // State constraint
        if (this.status !== EventStatus.Open) {
            throw new InvalidOperationError("Event is not open for registration");
        }
        // Capacity constraint
        if (this.attendees.length >= this.maxAttendees) {
            throw new CapacityExceededError(this.id);
        }
        // Uniqueness constraint
        if (this.attendees.some(a => a.equals(userId))) {
            throw new AlreadyRegisteredError(userId, this.id);
        }
        
        this.attendees.push(userId);
    }
    
    // Entity invariant: expose computed property
    get spotsRemaining(): number {
        return Math.max(0, this.maxAttendees - this.attendees.length);
    }
}

Fail Fast, Fail Clearly

Validate at the boundary. When invalid data enters your system, reject it immediately with a clear error. Don't let it propagate deeper where it causes confusing bugs. The entity's job is to protect its invariants—it should be impossible to create an entity in an invalid state.

Common Attribute Design Mistakes

Over years of software development, certain attribute design mistakes appear repeatedly. Learning to recognize these patterns helps you avoid them:

Attribute Anti-Patterns

•Stringly-Typed Attributes — Using strings for everything when enums, typed IDs, or value objects would be safer. status: string invites typos; status: OrderStatus doesn't.
•Flags Instead of States — Multiple boolean flags that create impossible combinations: isActive && isPaused && isDeleted. Use a single state enum instead.
•Nullable Everything — Every attribute being optional because 'we might not always have it'. This hides required invariants and leads to null checks everywhere.
•Computed Properties Stored Redundantly — Storing fullName alongside firstName and lastName, creating sync bugs. Store source data; compute derivations.
•Missing Temporal Context — Storing current values without history when history matters. The current price isn't what the customer was charged.
•Overloaded Attributes — A single field meaning different things in different contexts. value that's sometimes a dollar amount and sometimes a percentage.
•Implicit Unit Assumptions — distance: number — in meters? feet? miles? Always encode units explicitly or use typed values.

Flag Anti-Pattern vs State Pattern
TypeScript
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
// ❌ ANTI-PATTERN: Multiple boolean flags
class BadSubscription {
    isActive: boolean;
    isPaused: boolean;
    isCancelled: boolean;
    isTrialing: boolean;
    isPastDue: boolean;
    
    // What does isActive=true, isPaused=true, isCancelled=true mean??
    // How many states is that? 2^5 = 32 theoretical combinations
    // Most are invalid but not prevented
}
 
// ✅ CORRECT: Single state enum
enum SubscriptionStatus {
    Trialing = "TRIALING",
    Active = "ACTIVE",
    PastDue = "PAST_DUE",      // Still active but payment failed
    Paused = "PAUSED",
    Cancelled = "CANCELLED",
    Expired = "EXPIRED",
}
 
class Subscription {
    private status: SubscriptionStatus;
    
    // Clear state, clear transitions
    canPause(): boolean {
        return this.status === SubscriptionStatus.Active;
    }
    
    pause(): void {
        if (!this.canPause()) {
            throw new InvalidStateTransitionError(this.status, "pause");
        }
        this.status = SubscriptionStatus.Paused;
    }
    
    // Status-dependent behavior is clean
    get hasAccess(): boolean {
        return [
            SubscriptionStatus.Trialing,
            SubscriptionStatus.Active,
            SubscriptionStatus.PastDue,  // Grace period
        ].includes(this.status);
    }
}

Not All Redundancy Is Bad

Sometimes storing 'redundant' data is the right choice. Order totals are snapshots, not computations. Denormalized data for read performance is intentional. The anti-pattern is ACCIDENTAL redundancy where you store computed values without realizing you'll need to keep them in sync.

Summary and Next Steps

We've explored attributes as the descriptive properties that give entities their characteristics. Let's consolidate the key takeaways:

Key Takeaways

•Attributes describe entity characteristics — They answer 'what is this entity like?' through identifying, descriptive, categorical, quantitative, temporal, state, and relational properties.
•Distinguish essential from incidental — Essential attributes are required for entity validity; incidental attributes enhance but don't define. This drives required vs optional decisions.
•Type attributes carefully — Avoid primitive obsession. Create value objects for validated, domain-meaningful types like Money, EmailAddress, and typed IDs.
•Design complete attribute sets systematically — Use use case analysis, domain expert review, and category checklists to ensure completeness without over-specification.
•Enforce invariants at all levels — Type-level, attribute-level, and entity-level validation work together to make invalid states unrepresentable.
•Avoid common anti-patterns — Boolean flag explosions, nullable everything, computed redundancy, and stringly-typed data create maintenance nightmares.

What's Next:

We've covered what entities ARE (identity) and what they're LIKE (attributes). But entities aren't just passive data containers—they DO things. The next page explores behaviors: the methods and operations that entities can perform, how to design cohesive method sets, and how behaviors interact with state and invariants.

Page Complete

You now understand how to design attributes that are complete, type-safe, and well-validated. You can distinguish essential from incidental attributes and apply appropriate typing strategies. Next, we'll explore behaviors—the actions that bring your entities to life.

2 / 4

Loading learning content...

Low-Level DesignEntities, Attributes, and Behaviors

Entities, Attributes, and Behaviors

LevelBeginner

Duration60 mins

TopicEntities, Attributes, and Behaviors

2 / 4

Attributes — Properties That Describe Entities

Describing the Things in Your System

What You Will Learn

What Are Attributes?

Attributes are the properties that describe an entity's characteristics and state. They answer questions about the entity:

What is its name? → name attribute
When was it created? → createdAt attribute
What's its current status? → status attribute
How much does it cost? → price attribute
Is it active? → isActive attribute

In code, attributes typically manifest as instance variables (fields) of a class. They hold the data that makes one instance distinguishable from another instance of the same type.

Entity with Attributes
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
class Product {
    // Identity
    private readonly id: string;
    
    // Descriptive attributes
    private name: string;
    private description: string;
    private category: Category;
    
    // Pricing attributes
    private price: Money;
    private discount: Percentage;
    
    // Inventory attributes
    private stockQuantity: number;
    private reorderThreshold: number;
    
    // State attributes
    private status: ProductStatus;
    private isVisible: boolean;
    
    // Temporal attributes
    private readonly createdAt: Date;
    private updatedAt: Date;
    
    constructor(
        id: string,
        name: string,
        price: Money,
        category: Category
    ) {
        this.id = id;
        this.name = name;
        this.price = price;
        this.category = category;
        this.createdAt = new Date();
        this.updatedAt = new Date();
        // ... defaults for other fields
    }
}

Attributes vs. Identity

Categories of Attributes

Not all attributes are alike. Understanding the different categories helps you design complete, well-organized entities. Let's examine the major categories:

Attribute Categories
Category	Purpose	Examples	Design Considerations
Identifying	Distinguish instances; may be business-meaningful	ID, SKU, email, order number	Immutable after creation; must be unique within scope
Descriptive	Core characteristics of the entity	Name, title, description, bio	Often user-facing; consider localization
Categorical	Classify or type the entity	Category, type, role, tier	Use enums or reference entities; validates against fixed lists
Quantitative	Numeric measurements or amounts	Price, quantity, balance, rating	Type carefully (Money vs float); handle precision
Temporal	Time-related tracking	createdAt, updatedAt, expiresAt, birthDate	Consider timezone; some are immutable (createdAt)
State	Current status in lifecycle	status, isActive, isVerified, phase	Often governs allowed operations; model state machines
Relational	References to other entities	userId, categoryId, parentId	ID references for loose coupling; consider cascading
Computed/Derived	Calculated from other attributes	fullName, age, totalPrice	Don't store if easily computed; cache if expensive

Why categorization matters:

Understanding attribute categories helps you:

Ensure completeness — Have you covered all the categories relevant to your entity?
Apply appropriate types — Temporal attributes need Date types, quantitative attributes need appropriate numeric types
Manage mutability — Identification attributes are immutable; state attributes are specifically for controlled change
Design accessors properly — Some attributes need validation on set; some are read-only
Plan persistence — Different categories may have different database strategies (indexed, encrypted, etc.)

Not Every Category for Every Entity

Essential vs. Incidental Attributes

The distinction matters for:

Deciding which attributes are required vs. optional
Determining what goes in the entity vs. in related objects
Prioritizing which attributes to implement first
Understanding invariants the entity must maintain

Essential Attributes

•Required for entity existence — The entity cannot be valid without them
•Core to identity or purpose — They define what the entity fundamentally is
•Stable over time — While they may change, their presence is constant
•Drive key business logic — Essential for the entity to participate in domain operations
•Examples: Order needs items and customer; User needs identifier; Product needs price

Incidental Attributes

•Optional or supplementary — The entity is valid without them
•Enhancing, not defining — They add detail but don't change fundamental nature
•May come later — Often populated after entity creation
•Context-dependent — Their relevance may vary by use case
•Examples: User's bio, profile picture; Product's detailed description; Order's gift message

The Essential Attribute Test:

For each attribute, ask yourself:

Can the entity exist without it? If the entity can be created and function meaningfully without this attribute, it's likely incidental.
Does removing it change what the entity IS? A Product without a price isn't really a product in commerce terms. A User without a bio is still a user.
Is it required by the core use cases? Essential attributes are needed for the primary operations. Incidental attributes support secondary features.
Would a domain expert consider it fundamental? Ask someone who works in the domain—is this attribute central to understanding the concept?

Essential vs Incidental Example
TypeScript
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
class User {
    // === ESSENTIAL ATTRIBUTES ===
    // Without these, it's not a valid user
    
    private readonly id: string;           // Must have identity
    private email: string;                 // Primary login credential
    private passwordHash: string;          // Required for authentication
    private readonly createdAt: Date;      // When the account was created
    private status: UserStatus;            // Account state (active/suspended)
    
    // === INCIDENTAL ATTRIBUTES ===
    // Entity is valid without these; they enhance but don't define
    
    private displayName?: string;          // Optional; can use email as fallback
    private avatarUrl?: string;            // Nice to have; default avatar fine
    private bio?: string;                  // Completely optional profile info
    private phoneNumber?: string;          // Optional second factor
    private timezone?: string;             // Defaults to UTC if not set
    private locale?: string;               // Defaults to en-US
    private lastLoginAt?: Date;            // Tracking, not existence
    
    constructor(id: string, email: string, passwordHash: string) {
        // Essential attributes are REQUIRED in constructor
        this.id = id;
        this.email = email;
        this.passwordHash = passwordHash;
        this.createdAt = new Date();
        this.status = UserStatus.Active;
        
        // Incidental attributes have sensible defaults or are undefined
    }
    
    // Essential operations work with essential attributes
    authenticate(password: string): boolean {
        return this.verifyPassword(password) && 
               this.status === UserStatus.Active;
    }
    
    // Incidental attributes can be set later
    updateProfile(updates: Partial<UserProfile>): void {
        if (updates.displayName !== undefined) {
            this.displayName = updates.displayName;
        }
        if (updates.bio !== undefined) {
            this.bio = updates.bio;
        }
        // ...
    }
}

Incidental Doesn't Mean Unimportant

Attribute Types and Type Safety

Choosing the right types for attributes is crucial for correctness, safety, and clarity. Poor typing leads to bugs, confusion, and defensive code scattered throughout your codebase.

Let's explore best practices for attribute typing:

Primitive Obsession: The Anti-Pattern

One of the most common mistakes is using primitive types (string, number, boolean) for everything. This leads to:

No validation at boundaries — A string can hold invalid emails, negative prices, malformed UUIDs
Meaning encoded in variable names only — price: number doesn't tell you the currency or precision
Easy to confuse similar-typed values — Swapping userId and orderId both typed as string compiles fine
Validation logic scattered everywhere — Is this email valid? Check in 47 places...

Primitive Obsession vs Strong Types
TypeScript
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
// ❌ PRIMITIVE OBSESSION — Easy to make mistakes
class WeakOrder {
    customerId: string;     // Is this a UUID? An email? Who knows
    amount: number;         // In dollars? Cents? Bitcoin?
    email: string;          // Could be "not_an_email" 
    discount: number;       // 0.1 means 10%? Or $0.10?
}
 
// Bugs are easy:
const order = new WeakOrder();
order.customerId = order.email;  // Compiles! Both strings
order.amount = -500;             // Compiles! Just a number
order.discount = 150;            // 150% off? Compiles fine!
 
// ✅ STRONG TYPING — Type system catches mistakes
 
// Value Objects that validate and encapsulate
class CustomerId {
    private readonly value: string;
    
    constructor(value: string) {
        if (!this.isValidUUID(value)) {
            throw new InvalidCustomerIdError(value);
        }
        this.value = value;
    }
    
    private isValidUUID(value: string): boolean {
        return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
            .test(value);
    }
    
    toString(): string { return this.value; }
}
 
class Money {
    constructor(
        private readonly amount: number,
        private readonly currency: Currency
    ) {
        if (amount < 0) {
            throw new NegativeAmountError(amount);
        }
    }
    
    add(other: Money): Money {
        if (!this.currency.equals(other.currency)) {
            throw new CurrencyMismatchError(this.currency, other.currency);
        }
        return new Money(this.amount + other.amount, this.currency);
    }
}
 
class EmailAddress {
    private readonly value: string;
    
    constructor(value: string) {
        if (!this.isValidEmail(value)) {
            throw new InvalidEmailError(value);
        }
        this.value = value.toLowerCase(); // Normalize
    }
    
    private isValidEmail(value: string): boolean {
        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
    }
}
 
class Percentage {
    private readonly value: number; // 0 to 100
    
    constructor(value: number) {
        if (value < 0 || value > 100) {
            throw new InvalidPercentageError(value);
        }
        this.value = value;
    }
    
    applyTo(amount: Money): Money {
        return amount.multiply(this.value / 100);
    }
}
 
// Now the Order is type-safe
class StrongOrder {
    customerId: CustomerId;       // Can't be confused with other IDs
    amount: Money;                // Currency is explicit, can't be negative
    customerEmail: EmailAddress;  // Guaranteed valid format
    discount: Percentage;         // 0-100, can't be 150%
}

When to Create Custom Types:

Not every attribute needs its own type. Create custom types (also called value objects) when:

Validation is required — Emails, phone numbers, currencies, etc.
Confusion is possible — Multiple attributes with the same primitive type (string IDs that could be swapped)
Operations are domain-specific — Money has arithmetic with currency checks; Percentage has specific behavior
The concept is reused — EmailAddress appears across User, Contact, Invoice, etc.

Common Value Objects to Create

•Money — Amount + currency, with arithmetic that respects currency rules
•EmailAddress — Validated, normalized email string
•PhoneNumber — Country code + number, validated format
•DateRange — Start + end, with invariant that start ≤ end
•Coordinates — Latitude + longitude, validated ranges
•Percentage — 0-100 (or 0-1) with application logic
•Slug — URL-safe string with validation and normalization
•Typed IDs — UserId, OrderId, ProductId as distinct types

Start Simple, Upgrade When Burned

Designing Complete Attribute Sets

How do you know if you've captured all the right attributes for an entity? How do you avoid both over-specification (too many attributes) and under-specification (missing critical ones)?

Here's a systematic approach to designing complete attribute sets:

Attribute Discovery Process

•List all use cases — What operations will this entity participate in? Reading, writing, querying, displaying, reporting, integrating...
•Extract data needs per use case — For each use case, what data about this entity is needed? This reveals required attributes.
•Identify identifying attributes — What makes one instance distinguishable from another? This is your ID strategy.
•Add lifecycle tracking — createdAt, updatedAt, status fields that track entity lifecycle.
•Consider audit requirements — Do you need createdBy, updatedBy? Version numbers for optimistic locking?
•Map relationships — Which other entities does this connect to? Add reference IDs.
•Review with domain experts — Ask business stakeholders: What information do you need to know about a [Entity]?
•Prune and prioritize — Mark attributes as essential vs incidental. Remove anything truly unnecessary.

Worked Example: Designing Order Attributes

Let's design the attributes for an Order entity in an e-commerce system.

Use cases:

Customer places order → Need items, shipping address, payment method
Customer views order status → Need status, tracking info
Warehouse fulfills order → Need items, shipping address, priority
Finance generates reports → Need totals, dates, payment details
Customer support resolves issues → Need all of the above plus notes

Complete Order Attributes
TypeScript
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
class Order {
    // === IDENTIFICATION ===
    private readonly id: OrderId;
    private readonly orderNumber: OrderNumber;  // Human-readable: ORD-2024-00123
    
    // === CORE RELATIONSHIPS ===
    private readonly customerId: CustomerId;
    private readonly items: OrderItem[];
    
    // === FINANCIAL ===
    private readonly subtotal: Money;
    private readonly taxAmount: Money;
    private readonly shippingCost: Money;
    private readonly discountApplied: Money;
    private readonly total: Money;
    private paymentId?: PaymentId;
    private paymentStatus: PaymentStatus;
    
    // === SHIPPING ===
    private shippingAddress: Address;        // Snapshot at order time
    private billingAddress: Address;
    private shippingMethod: ShippingMethod;
    private trackingNumber?: string;
    private estimatedDelivery?: Date;
    
    // === LIFECYCLE ===
    private status: OrderStatus;             // Draft, Confirmed, Paid, Shipped, Delivered, Cancelled
    private readonly createdAt: Date;
    private updatedAt: Date;
    private confirmedAt?: Date;
    private shippedAt?: Date;
    private deliveredAt?: Date;
    private cancelledAt?: Date;
    
    // === OPERATIONAL ===
    private priority: OrderPriority;
    private notes: OrderNote[];              // Internal customer service notes
    private giftMessage?: string;            // Customer-facing 
    
    // === AUDIT ===
    private readonly createdBy?: UserId;     // If created by staff on behalf
    private lastModifiedBy?: UserId;
    private version: number;                 // Optimistic locking
}

Don't Store What You Can Compute

Attribute Validation and Invariants

There are three levels of attribute validation:

Validation Levels
Level	What It Validates	Where It's Enforced	Examples
Type-Level	Valid format/value for a single attribute	In the type/value object	Email format, positive amounts, valid UUID
Attribute-Level	Valid value for this attribute in this entity	In setters or entity methods	Username length 3-50, description max 1000 chars
Entity-Level	Consistency between multiple attributes	In entity methods, especially state transitions	endDate > startDate, total = sum(items), status transitions

Validation at All Levels
TypeScript
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
// Type-level validation: EmailAddress
class EmailAddress {
    private readonly value: string;
    
    constructor(value: string) {
        // Validates email format once, at construction
        if (!this.isValidFormat(value)) {
            throw new InvalidEmailError(value);
        }
        this.value = value.toLowerCase();
    }
    
    private isValidFormat(value: string): boolean {
        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
    }
}
 
// Entity with attribute-level and entity-level validation
class Event {
    private readonly id: EventId;
    private title: string;
    private description: string;
    private startTime: Date;
    private endTime: Date;
    private maxAttendees: number;
    private attendees: UserId[] = [];
    private status: EventStatus = EventStatus.Draft;
    
    constructor(id: EventId, title: string, start: Date, end: Date) {
        this.id = id;
        this.setTitle(title);           // Attribute-level validation
        this.setTimeRange(start, end);  // Entity-level validation
    }
    
    // Attribute-level: validates single attribute constraints
    private setTitle(title: string): void {
        if (title.length < 3 || title.length > 200) {
            throw new ValidationError("Title must be 3-200 characters");
        }
        this.title = title.trim();
    }
    
    // Entity-level: validates cross-attribute constraints
    private setTimeRange(start: Date, end: Date): void {
        if (end <= start) {
            throw new ValidationError("End time must be after start time");
        }
        if (start < new Date()) {
            throw new ValidationError("Cannot create events in the past");
        }
        this.startTime = start;
        this.endTime = end;
    }
    
    // Entity-level: validates state + capacity
    registerAttendee(userId: UserId): void {
        // State constraint
        if (this.status !== EventStatus.Open) {
            throw new InvalidOperationError("Event is not open for registration");
        }
        // Capacity constraint
        if (this.attendees.length >= this.maxAttendees) {
            throw new CapacityExceededError(this.id);
        }
        // Uniqueness constraint
        if (this.attendees.some(a => a.equals(userId))) {
            throw new AlreadyRegisteredError(userId, this.id);
        }
        
        this.attendees.push(userId);
    }
    
    // Entity invariant: expose computed property
    get spotsRemaining(): number {
        return Math.max(0, this.maxAttendees - this.attendees.length);
    }
}

Fail Fast, Fail Clearly

Common Attribute Design Mistakes

Over years of software development, certain attribute design mistakes appear repeatedly. Learning to recognize these patterns helps you avoid them:

Attribute Anti-Patterns

•Stringly-Typed Attributes — Using strings for everything when enums, typed IDs, or value objects would be safer. status: string invites typos; status: OrderStatus doesn't.
•Flags Instead of States — Multiple boolean flags that create impossible combinations: isActive && isPaused && isDeleted. Use a single state enum instead.
•Nullable Everything — Every attribute being optional because 'we might not always have it'. This hides required invariants and leads to null checks everywhere.
•Computed Properties Stored Redundantly — Storing fullName alongside firstName and lastName, creating sync bugs. Store source data; compute derivations.
•Missing Temporal Context — Storing current values without history when history matters. The current price isn't what the customer was charged.
•Overloaded Attributes — A single field meaning different things in different contexts. value that's sometimes a dollar amount and sometimes a percentage.
•Implicit Unit Assumptions — distance: number — in meters? feet? miles? Always encode units explicitly or use typed values.

Flag Anti-Pattern vs State Pattern
TypeScript
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
// ❌ ANTI-PATTERN: Multiple boolean flags
class BadSubscription {
    isActive: boolean;
    isPaused: boolean;
    isCancelled: boolean;
    isTrialing: boolean;
    isPastDue: boolean;
    
    // What does isActive=true, isPaused=true, isCancelled=true mean??
    // How many states is that? 2^5 = 32 theoretical combinations
    // Most are invalid but not prevented
}
 
// ✅ CORRECT: Single state enum
enum SubscriptionStatus {
    Trialing = "TRIALING",
    Active = "ACTIVE",
    PastDue = "PAST_DUE",      // Still active but payment failed
    Paused = "PAUSED",
    Cancelled = "CANCELLED",
    Expired = "EXPIRED",
}
 
class Subscription {
    private status: SubscriptionStatus;
    
    // Clear state, clear transitions
    canPause(): boolean {
        return this.status === SubscriptionStatus.Active;
    }
    
    pause(): void {
        if (!this.canPause()) {
            throw new InvalidStateTransitionError(this.status, "pause");
        }
        this.status = SubscriptionStatus.Paused;
    }
    
    // Status-dependent behavior is clean
    get hasAccess(): boolean {
        return [
            SubscriptionStatus.Trialing,
            SubscriptionStatus.Active,
            SubscriptionStatus.PastDue,  // Grace period
        ].includes(this.status);
    }
}

Not All Redundancy Is Bad

Summary and Next Steps

We've explored attributes as the descriptive properties that give entities their characteristics. Let's consolidate the key takeaways:

Key Takeaways

•Attributes describe entity characteristics — They answer 'what is this entity like?' through identifying, descriptive, categorical, quantitative, temporal, state, and relational properties.
•Distinguish essential from incidental — Essential attributes are required for entity validity; incidental attributes enhance but don't define. This drives required vs optional decisions.
•Type attributes carefully — Avoid primitive obsession. Create value objects for validated, domain-meaningful types like Money, EmailAddress, and typed IDs.
•Design complete attribute sets systematically — Use use case analysis, domain expert review, and category checklists to ensure completeness without over-specification.
•Enforce invariants at all levels — Type-level, attribute-level, and entity-level validation work together to make invalid states unrepresentable.
•Avoid common anti-patterns — Boolean flag explosions, nullable everything, computed redundancy, and stringly-typed data create maintenance nightmares.

What's Next:

Page Complete

2 / 4