Value Objects Enhancing Business Semantics

Value Objects in .NET: Enhancing Business Semantics

Value objects are fundamental building blocks in Domain-Driven Design, serving far more than simple data wrappers. This article explores their strategic importance in bridging technical code and business concepts, enforcing domain rules, and fostering clearer communication with domain experts. Learn how to build robust aggregates, cultivate ubiquitous language, and encapsulate domain-specific behavior using Thinktecture.Runtime.Extensions in .NET applications.

Article Series

1. Value Objects: Solving Primitive Obsession in .NET
2. Handling Complexity: Introducing Complex Value Objects in .NET
3. Value Objects in .NET: Integration with Frameworks and Libraries
4. Value Objects in .NET: Enhancing Business Semantics ⬅

---

Introduction

In the first article, we explored how simple value objects help overcome primitive obsession by wrapping single values like amounts or email addresses, adding type safety and validation. Following that, 2nd article introduced complex value objects, demonstrating how concepts defined by multiple related pieces of data, such as a time period or a postal address, can be modeled as cohesive, self-validating units.

While these articles focused on the technical benefits and implementation using Thinktecture.Runtime.Extensions, value objects play a much deeper role. They are fundamental building blocks in Domain-Driven Design (DDD), a software development approach that emphasizes collaboration between technical and domain experts to create software that accurately models the core business domain.

This article delves into the strategic importance of value objects within DDD. We'll see how they help bridge the gap between technical code and business concepts, enforce business rules naturally, and foster clearer communication by aligning the software's vocabulary with the language spoken by domain experts.

Value Objects as Core DDD Elements

Domain-Driven Design provides a structured way to tackle complex software projects by focusing on the core domain and its logic. It introduces several key patterns, and value objects are among the most fundamental. They work alongside other patterns like Entities (objects with distinct identities, like a Customer or Product) and Aggregates (clusters of domain objects treated as a single unit, like an Order with its OrderLines).

A common point of confusion is distinguishing between value objects and entities. The key difference lies in identity:

• Entities have a unique identity that persists over time, even if their attributes change (e.g., a Customer is the same customer even if their address changes). They are defined by who they are.
• Value Objects have no conceptual identity; they are defined solely by their attributes (e.g., two Money objects representing 10 EUR are interchangeable). They are defined by what they are. If you change an attribute, you essentially have a different value object.

Choosing between them involves understanding the domain concept: Does it have an identity that needs tracking, or is it purely defined by its characteristics? For instance, a PostalAddress might be an Entity if we need to track its history, but often it's better modeled as a value object representing a specific location description.

Crucially, value objects help enforce domain invariants – business rules that must always hold true. Because a value object controls its own creation and ensures it's always in a valid state (as shown in the previous articles with validation logic), it inherently upholds the invariants related to the concept it represents. An Amount value object designed to always be positive guarantees that this invariant is maintained wherever the Amount is used.

Encapsulating Domain-Specific Behavior

A common mistake is treating value objects as simple data containers. However, a key principle of object-oriented design and DDD is to keep data and the behavior that operates on that data together. Value objects should encapsulate behavior that is intrinsically related to the concept they represent.

Instead of having service classes with methods like CalculateShippingCost(Address address, Weight weight), this logic can often reside within the value objects themselves, like:

• Arithmetic operators: Money + Money
• Querying/Checks: PostalCode.IsValidFor(CountryCode country)
• Formatting: DeliveryAddress.FormatForMailingLabel()
• etc.

Encapsulating behavior within value objects leads to:

• Higher Cohesion: Logic related to a concept is located with the data for that concept.
• Lower Coupling: Services become less dependent on the internal details of value objects.
• Improved Discoverability: Developers can find relevant operations directly on the object itself.
• Better Testability: Behavior can be unit-tested in isolation within the value object.

Let's explore this concept through a comprehensive example using the complex value object Money.

📝Following example mentions Smart Enums which provide a type-safe way to represent fixed sets of related constants with associated data and behavior.

First, we need to define a prerequisite value object CurrencyCode that Money will depend on:

// Currency (could also be a Smart Enum with fixed set of currencies)
[ValueObject<string>]
public partial class CurrencyCode
{
    // Well-known currencies, add others as needed
    public static readonly CurrencyCode EUR = Create("EUR");

    // Basic validation
    static partial void ValidateFactoryArguments(
        ref ValidationError? validationError, ref string value)
    {
        if (string.IsNullOrWhiteSpace(value) || value.Length != 3)
        {
            validationError = new ValidationError("Currency code must be 3 characters long.");
            return;
        }

        value = value.ToUpperInvariant(); // Normalization
    }
}

Now that we have our CurrencyCode, let's examine the value object Money that showcases how to encapsulate domain-specific behavior, like arithmetic operators and rounding:

[ComplexValueObject]
public partial struct Money :
    IAdditionOperators<Money, Money, Money>,    // Money + Money
    ISubtractionOperators<Money, Money, Money>, // Money - Money
    IMultiplyOperators<Money, int, Money>       // Money * int
{
    public decimal Amount { get; }
    public CurrencyCode Currency { get; }

    static partial void ValidateFactoryArguments(
        ref ValidationError? validationError, ref decimal amount, ref CurrencyCode currency)
    {
        if (amount < 0)
            validationError = new ValidationError("Money amount cannot be negative.");

        if (currency is null)
             validationError = new ValidationError("Currency must be specified.");

        // 📝 Alternatively, round the amount based on provided currency
        amount = Math.Round(amount, 2);
    }

    // Arithmetic operators
    public static Money operator +(Money left, Money right)
    {
        if (left.Currency != right.Currency)
            throw new InvalidOperationException("Cannot add money of different currencies.");

        // Use the factory method to ensure validation of the result
        return Create(left.Amount + right.Amount, left.Currency);
    }

    public static Money operator -(Money left, Money right) { ... }
    public static Money operator *(Money left, int right) { ... }
}

Building Aggregates with Value Objects

Aggregates are a core pattern in DDD, representing a consistency boundary around a group of related domain objects. An aggregate consists of a root entity (the aggregate root) and potentially other entities and value objects. The aggregate root is responsible for ensuring the consistency of the entire aggregate.

Value objects are vital components within aggregates:

• They encapsulate attributes and related logic, simplifying the aggregate root.
• They help maintain the aggregate's consistency boundary because they cannot exist in an invalid state.
• They make the aggregate's structure more expressive and aligned with the domain.

Let's examine a practical example from an e-commerce domain to see how value objects work together within an aggregate. We'll start by defining the individual value objects that will serve as building blocks, then show how they compose into a cohesive Order aggregate.

The following code demonstrates the "building blocks first" approach – we define each value object with its own validation and behavior, ensuring they can exist independently while being designed to work together:

// Type-safe, Guid-based identifiers
[ValueObject<Guid>]
public partial struct OrderId;

[ValueObject<Guid>]
public partial struct CustomerId;

[ValueObject<Guid>]
public partial struct ProductId;

// non-negative quantity
[ValueObject<int>(AllowDefaultStructs = true, DefaultInstancePropertyName = "Zero")]
public partial struct Quantity
{
    static partial void ValidateFactoryArguments(
        ref ValidationError? validationError, ref int value)
    {
        if (value < 0)
            validationError = new ValidationError("Quantity cannot be negative.");
    }
}

// Delivery address as a complex value object containing other value objects and Smart Enums
[ComplexValueObject]
public partial class DeliveryAddress
{
    public Street Street { get; }         // Assuming Street is a value object
    public City City { get; }             // Assuming City is a value object
    public PostalCode PostalCode { get; } // Assuming PostalCode is a value object
    public CountryCode Country { get; }   // Assuming CountryCode is a value object or Smart Enum

    // Address validation
    static partial void ValidateFactoryArguments(
        ref ValidationError? validationError,
        ref Street street,
        ref City city,
        ref PostalCode postalCode,
        ref CountryCode country)
        {
            /* ... */
        }
}

Before we show the complete Order, let's define the OrderLine that will be used within it. The OrderLine represents a single item in an order and demonstrates how value objects can encapsulate both data and behavior (like calculating the line total) while maintaining their own validation rules:

[ComplexValueObject]
public partial class OrderLine
{
    public ProductId ProductId { get; }
    public Quantity Quantity { get; }
    public Money UnitPrice { get; }

    public Money LineTotal => UnitPrice * Quantity;

    static partial void ValidateFactoryArguments(
        ref ValidationError? validationError,
        ref ProductId productId,
        ref Quantity quantity,
        ref Money unitPrice)
    {
       // Basic validations are done by Quantity and Money
       // Add further validation as needed...
    }
}

Now that we have our foundational value objects defined, let's see how they come together to form an Order. Notice how the aggregate root leverages the validation and behavior already encapsulated within each value object, allowing it to focus on orchestrating business logic rather than managing low-level validation concerns:

public class Order
{
    public OrderId Id { get; }
    public CustomerId CustomerId { get; }
    public Money TotalAmount { get; private set; }
    public DeliveryAddress ShippingAddress { get; private set; }

    private readonly List<OrderLine> _orderLines;
    public IReadOnlyList<OrderLine> OrderLines => _orderLines; // Expose as read-only

    // Constructor ensures initial valid state
    public Order(
        OrderId id, CustomerId customerId, DeliveryAddress shippingAddress, CurrencyCode currency)
    {
        Id = id;
        CustomerId = customerId;
        ShippingAddress = shippingAddress;
        TotalAmount = Money.Create(0m, currency);
        _orderLines = [];
    }

    public void AddOrderLine(ProductId productId, Quantity quantity, Money unitPrice)
    {
        // Ensure consistency within the aggregate
        if (TotalAmount.Currency != unitPrice.Currency)
        {
            throw new InvalidOperationException(
                $"Cannot add order line with currency {unitPrice.Currency} " +
                $"to an order with currency {TotalAmount.Currency}.");
        }

        // OrderLine creation enforces its own rules
        var orderLine = OrderLine.Create(productId, quantity, unitPrice);
        _orderLines.Add(orderLine);

        RecalculateTotal(); // Maintain internal aggregate consistency
    }

    private void RecalculateTotal()
    {
        // Leverages behavior defined within the Money value object
        TotalAmount = _orderLines.Aggregate(
            Money.Create(0, TotalAmount.Currency),
            (total, line) => total + line.LineTotal); // Using '+' operator from Money
    }
}

In this example, OrderId, CustomerId, ProductId, Quantity, CurrencyCode, Money, DeliveryAddress, and OrderLine are all value objects. The aggregate root Order uses these value objects, simplifying its own logic because it can trust that these components are always valid and consistent according to their own rules. The RecalculateTotal method leverages the + operator defined within the Money value object.

Cultivating a Ubiquitous Language

One of the cornerstones of DDD is the Ubiquitous Language – a common, shared language developed collaboratively by developers and domain experts. This language should be used in all forms of communication, including discussions, documentation, and, crucially, the code itself.

Value objects are powerful tools for cultivating this language in the codebase. Instead of passing around generic primitives like string or decimal, we use types that directly correspond to domain concepts:

• Instead of decimal price, use Money price.
• Instead of string zipCode, use PostalCode postalCode.
• Instead of int customerNumber, use CustomerId customerId.

This makes the code self-documenting and less ambiguous. Method signatures become clearer:
ProcessPayment(PaymentId paymentId, Money amount, AccountNumber targetAccount) is far more expressive than
ProcessPayment(Guid paymentId, decimal amount, string targetAccount).

Furthermore, the principle of aligning code with domain communication can sometimes extend to the natural language used by domain experts themselves. For teams working very closely with non-English speaking domain experts, using precise terms from their language directly in the code can further minimize friction and enhance understanding. A German financial team might naturally use a class named Beitragsbemessungsgrenze to represent the contribution assessment ceiling, preserving the exact terminology that domain experts use in their daily discussions. This approach eliminates the cognitive overhead of translating between business language and code, though it requires careful consideration of team composition and library interaction requirements.

Using value objects forces developers to think about the domain concepts they are modeling and helps ensure the code accurately reflects the business reality. This alignment reduces the "translation" effort required between business requirements and technical implementation, leading to fewer misunderstandings and more robust software.

Summary

Value objects are far more than just simple data wrappers; they are essential tools in the Domain-Driven Design toolkit. By accurately modeling domain concepts, enforcing invariants through self-validation, and encapsulating relevant behavior, they significantly improve the clarity, robustness, and maintainability of domain models.

Using value objects helps build aggregates with clear consistency boundaries and fosters a Ubiquitous Language that aligns the codebase directly with business terminology. This leads to software that not only functions correctly but is also easier to understand, evolve, and discuss with domain experts.

While the previous articles focused on how to implement value objects, this article highlighted why they are strategically important for building effective, domain-centric applications. In the next article, we'll explore advanced value object patterns and techniques for handling complex domain scenarios, including open-ended dates, composite identifiers, recurring dates, and hierarchical structures using discriminated unions.

---

About the Author

Pawel Gerr is architect and consultant at Thinktecture. He focuses on backends with .NET Core and knows Entity Framework inside out.