Software ArchitectureAtlas

Software Architecture Atlas

Gain an overview. Understand the connections.

Standalone conceptConceptChapter I · Domain · Building block 8 of 18

Value object

A value object groups values whose combination and equality have business meaning.

By Michael Meierhoff · Meierhoff Systems

  1. ComponentsAmount and currency form one business value.
  2. Value equalityAll relevant components match.
  3. Replacement valueA business change creates a new value.

Context

Why this is important

An amount without a currency is incomplete. A value object keeps related business data and rules together. A change is expressed as a new value; earlier values remain traceable.

Business value modeling without an independent object identity.

At a glance · Values determine equality

A different amount creates a different value.
Shop example · Equality test

Same values, same monetary amount

The two mugs in B-1042 cost 49.90 EUR in total. Compare identical amounts, different currencies and matching address details. The USD variant is used only for comparison.

This is how you read the picture

  1. Components Both fields are highlighted as comparison fields.
  2. Value equality 49.90 EUR equals 49.90 EUR, but differs from 49.90 USD.
  3. Replacement value The comparison shows values; the timeline shows their replacement.

Monetary amount

  • Amount49.90 (comparison field)
  • CurrencyEUR (comparison field)

Monetary amount

  • Amount49.90 (comparison field)
  • CurrencyEUR (comparison field)

Same valueComparison of Values. The amount and the currency are the same. There is no separate identifier, so both amounts are interchangeable.

Amount and currency jointly define the monetary value. Select the USD variant: the same number alone is not enough.

The order remains the same entity even if a contained value changes before confirmation.Follow identity over time

A new value replaces the old one

  1. 01

    Original value · 49.90 EUR

    Amount and currency are stored together.

  2. 02

    Calculate discount · 44.90 EUR

    The calculation creates a new valid monetary value.

  3. 03

    Use the new value

    The current calculation uses 44.90 EUR. The original value remains unchanged.

Hypothetical discount variant before order confirmation. Historical order values are preserved.

Benefits & limitations

Helps if:

  • Primitive fields together form a meaningful unit or have their own rules.
  • Value equality matches business comparison and is independent of storage identity.

Boundaries

  • A value object is not automatically immutable everywhere; immutability is a design choice with clear benefits.
  • Historical values must be retained when a change must not retroactively alter past transactions.

In practice

  1. Determine which values form one business unit and which combinations would be invalid. Group fields only when domain experts assign them shared meaning.
  2. Specify which fields determine value equality and which rules the value validates. State comparison so business logic and tests use the same definition of equality.
  3. Model a value change by replacing it with a new value and check whether completed orders must retain the confirmed state. Use a copy or version rather than silent mutation.
Read the detailed explanation

Value objects encapsulate rules for their values and are usually made immutable. Two instances with the same relevant values are equal in the model. A change creates a new value instead of silently mutating the same instance.

Equality follows the meaning of the model: amount and currency may form a value for money, while relevant address fields define an address. Aggregates determine which relationships and changes remain consistent.

A stable identity characterises an Entity; an Aggregate keeps related changes consistent.

Check your understanding

Test yourself in three stages

  1. ReadingCheck in the picture

    Why are 49.90 EUR and 49.90 USD different values?

    View the solution with justification

    Currency is part of value equality. Identical numbers with different currencies represent different monetary values.

  2. ApplyingTransferred to a new situation

    The customer changes address. How is the new value represented?

    View the solution with justification

    As a new value object replacing the previous address.

  3. EvaluateWeighing an alternative

    Why might a past order need its old address?

    View the solution with justification

    So that a change does not retroactively alter the historical transaction.

Explore further

These building blocks continue the thoughts of this page.

DomainEntities & Value ObjectsContext and comparisonOpening DomainEntityConceptual connectionOpening DomainAggregateConceptual connectionOpening

References

Continue on the learning path

Next in Domain Modelling & DDD: Entity.

18 Building blocks

Continue withEntity