Skip to content
Skills Library
Programming · Building & coding

value-object

/value-object

Define a Protean value object, an immutable domain element without identity, defined by its attributes. Value objects represent descriptive concepts like Money, Email, Address, or Coordinates. Use when modeling concepts where identity doesn't matter, only the values do. Use when the user asks to "create a value object", "add a VO", "model money/email/address", or describes something that measures or describes (amounts, locations, contact info). Value objects are always embedded in aggregates or entities, never exist independently, and two instances with the same attributes are considered equal

Repository
protean ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
16
Scripts
7
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 7 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: assets/value_object_in_aggregate.py, assets/value_object_in_entity.py, assets/value_object_nested.py, assets/value_object_simple.py, assets/value_object_with_invariants.py, assets/value_object_with_methods.py, assets/value_object_with_validation.py

What it does and when to use it

Define a Protean value object, an immutable domain element without identity, defined by its attributes. Value objects represent descriptive concepts like Money, Email, Address, or Coordinates. Use when modeling concepts where identity doesn't matter, only the values do. Use when the user asks to "create a value object", "add a VO", "model money/email/address", or describes something that measures or describes (amounts, locations, contact info). Value objects are always embedded in aggregates or entities, never exist independently, and two instances with the same attributes are considered equal

Triggers from the description

t matter, only the values do. Use when the user asks toadd a VOmodel money/email/address
Original author description

Define a Protean value object, an immutable domain element without identity, defined by its attributes. Value objects represent descriptive concepts like Money, Email, Address, or Coordinates. Use when modeling concepts where identity doesn't matter, only the values do. Use when the user asks to "create a value object", "add a VO", "model money/email/address", or describes something that measures or describes (amounts, locations, contact info). Value objects are always embedded in aggregates or entities, never exist independently, and two instances with the same attributes are considered equal

How it works

  1. Important context: Value vs Entity decision
  2. Basic structure
  3. Key rules
  4. Defining value objects
  5. Embedding in aggregates and entities
  6. Initialization patterns
  7. Nested value objects
  8. Immutability
  9. Equality
  10. Common mistakes
Original SKILL.md headings · 378 lines, 1,558 words
SKILL.md preview
---
name: value-object
description: Define a Protean value object, an immutable domain element without identity, defined by its attributes. Value objects represent descriptive concepts like Money, Email, Address, or Coordinates. Use when modeling concepts where identity doesn't matter, only the values do. Use when the user asks to "create a value object", "add a VO", "model money/email/address", or describes something that measures or describes (amounts, locations, contact info). Value objects are always embedded in aggregates or entities, never exist independently, and two instances with the same attributes are considered equal.
license: Apache-2.0
compatibility: Requires Python 3.11+, protean framework
metadata:
  author: proteanhq
  version: "0.1"
  category: element
  diagnostic_codes:
    - VALUE_OBJECT_MUTABLE_FIELD
    - VALUE_OBJECT_INVARIANT_FAILED
---

# Value Object

Value objects are immutable domain elements that represent descriptive concepts without identity. They are defined entirely by their attribute values: two value objects with the same attributes are considered equal, regardless of instance.

## Important context: Value vs Entity decision

A critical question: does this concept need identity?

**Example: Currency note**
- In most domains: Value Object (a $10 bill is a $10 bill)
- For a federal bank printing money: Entity (specific note with serial number matters)

**Key questions:**
- Does identity matter more than attributes?
- Can two instances with same attributes be swapped?
- Should it be immutable?

If identity matters → Use Entity or Aggregate instead.
If values matter → Use Value Object.

See [Deciding Between Elements](https://docs.proteanhq.com/concepts/building-blocks/choosing-element-types/) for comprehensive guidance.

## Basic structure

A value object is defined using the `@domain.value_object` decorator:

```python
from decimal import Decimal as D

from protean import Domain
from protean.fields import Decimal, String

domain = Domain()

@domain.value_object
class Money:
    currency: String(max_length=3, required=True)
    amount: Decimal(precision=19, scale=4, required=True, min_value=0)
```

Use the `Decimal` field for money, never `Float`. A float cannot hold most cents exactly. The field stores a standard-library `decimal.Decimal`, so do arithmetic on money with decimals too. Import the standard-library class under an alias (`from decimal import Decimal as D`) so it does not clash with the field of the same name.

## Key rules

1. **Value objects are immutable**: Cannot be changed once created
2. **Value objects have no identity**: Cannot use `identifier=True` or `unique=True`
3. **Equality is by attributes**: Two VOs with same values are equal
4. **Value objects are embedded**: Always part of aggregates or entities
5. **Value objects are self-contained**: Should not reference entities
6. **Replace, don't modify**: Create new instance to "change" a value object
7. **Can contain other value objects**: Nesting is allowed and encouraged
8. **Should encapsulate validation**: **All business validations should be codified as granular invariants** using `@invariant.post` (one rule per invariant)

## Defining value objects

### Simple value object

```python
@domain.value_object
class Balance:
    """Currency and amount with field-level validations."""
    currency: String(max_length=3, min_length=3, required=True)  # ISO code
    amount: Decimal(precision=19, scale=4, required=True, min_value=0)  # No negative amounts
```

**Common field validation parameters**:
- **All fields**: `required`, `default`, `unique`, `choices`, `validators`
- **String**: `max_length`, `min_length`, `sanitize`
- **Integer/Float/Decimal**: `min_value`, `max_value`
- **Decimal**: `precision`, `scale`

### Value object with field-level validation

Use field validators for single-field data type validations:

```python
from protean.exceptions import ValidationError


class EmailValidator:
    def __init__(self):
        self.error = "Invalid email address"

    def __call__(self, value):
        if "@" not in value or value.startswith("@"):
            raise ValidationError(self.error)


@domain.value_object
class Email:
    address: String(
        max_length=254,
        required=True,
        validators=[EmailValidator()]
    )
```

**When to use field validators**: For single-field format validations (email format, phone format, etc.). For business rules involving multiple fields, use invariants instead.

### Value object with methods

```python
@domain.value_object
class Money:
    currency: String(max_length=3, required=True)
    amount: Decimal(precision=19, scale=4, required=True)

    def add(self, other: "Money") -> "Money":
        """Add two Money values, ensuring same currency."""
        if self.currency != other.currency:
            raise ValueError("Cannot add different currencies")
        # Return NEW instance (immutability)
        return Money(
            currency=self.currency,
            amount=self.amount + other.amount
        )

    def multiply(self, factor: int | D) -> "Money":
        """Multiply money by a whole number or a decimal."""
        return Money(
            currency=self.currency,
            amount=self.amount * factor
        )
```

### Value object with invariants

Value objects only support `@invariant.post` (since they're immutable and created atomically). Invariants run automatically after initialization.

```python
from protean import invariant

@domain.value_object
class DateRange:
    start_date: String(required=True)
    end_date: String(required=True)

    @invariant.post
    def end_must_be_after_start(self):
        """End date must not come before start date."""
        if self.end_date < self.start_date:
            raise ValidationError(
                {"date_range": ["End date must be after start date"]}
            )


@domain.value_object
class Price:
    # Use field-level validation for data type constraints
    currency: String(max_length=3, min_length=3, required=True)
    amount: Decimal(precision=19, scale=4, required=True, min_value=0)  # No negative amounts

    @invariant.post
    def currency_must_be_valid_ISO_code(self):
        """Currency must be one of the supported ISO codes."""
        valid_currencies = ["USD", "EUR", "GBP", "JPY"]
        if self.currency not in valid_currencies:
            raise ValidationError(
                {"currency": [f"Currency must be one of {valid_currencies}"]}
            )
```

**Best practices for value object invariants**:
1. **Use descriptive names**: Clearly describe the business constraint
2. **Field parameter or invariant**: `amount > 0` → Use `Decimal(precision=19, scale=4, min_value=D("0.01"))` (field validation), not an invariant. `end_date > start_date` → Use `@invariant.post` (cross-field business rule)

## Embedding in aggregates and entities

### In aggregates

```python
@domain.aggregate
class Account:
    balance = ValueObject(Balance, required=True)
    account_number: String(required=True, max_length=20)
```

### In entities

```python
@domain.entity(part_of="Order")
class LineItem:
    product_id: String(required=True)
    quantity: Integer(required=True, min_value=1)
    unit_price = ValueObject(Money, required=True)

    @property
    def line_total(self) -> Money:
        """Calculate line total using Money's multiply method."""
        return self.unit_price.multiply(self.quantity)
```

### Multiple value objects

```python
@domain.value_object
class Address:
    street: String(required=True, max_length=100)
    city: String(required=True, max_length=50)


@domain.aggregate
class Order:
    order_number: String(required=True, identifier=True)
    shipping_address = ValueObject(Address, required=True)
    billing_address = ValueObject(Address)
    total = ValueObject(Money, required=True)
    discount = ValueObject(Money)  # Optional
```

## Initialization patterns

Building an aggregate needs an initialized domain and an active domain context.

### Initialize with complete object

```python
domain.init(traverse=False)

with domain.domain_context():
    account = Account(
        balance=Balance(currency="USD", amount=D("100.00")),
        account_number="ACC-12345"
    )
```

### Initialize by attributes

```python
with domain.domain_context():
    # Attribute names: {field_name}_{vo_field_name}
    account = Account(
        balance_currency="USD",
        balance_amount=D("100.00"),
        account_number="ACC-12345"
    )
```

Both approaches produce identical results. Attribute initialization works one level deep, on the aggregate or entity that holds the value object, and only when you create it. It does not work for updating a value object later: `account.balance_amount = D("5")` raises no error, but it sets a stray attribute and leaves `account.balance` unchanged. A value object's own constructor does not accept flattened attributes either.

## Nested value objects

Value objects can contain other value objects:

```python
@domain.value_object
class Coordinates:
    latitude: Float(required=True, min_value=-90.0, max_value=90.0)
    longitude: Float(required=True, min_value=-180.0, max_value=180.0)


@domain.value_object
class Address:
    street: String(required=True, max_length=100)
    city: String(required=True, max_length=50)
    state: String(required=True, max_length=50)
    postal_code: String(required=True, max_length=20)
    country: String(required=True, max_length=50)
    coordinates = ValueObject(Coordinates)  # Nested VO


# Pass the nested value object as an object (or as a dict, see below)
address = Address(
    street="123 Broadway",
    city="New York",
    state="NY",
    postal_code="10012",
    country="USA",
    coordinates=Coordinates(latitude=40.7128, longitude=-74.0060)
)
```

A value object's constructor takes only its own fields. `Address(coordinates_latitude=40.7128)` fails with "Extra inputs are not permitted". Build the inner value object first and pass it in.

A `ValueObject` field also takes a plain dict of the inner value object's fields, at any depth: `coordinates={"latitude": 40.7128, "longitude": -74.0060}`. Protean builds the value object from the dict and validates it the same way, so a dict with a wrong or missing key raises `ValidationError`.

## Immutability

Value objects cannot be modified after creation:

```python
from protean.exceptions import IncorrectUsageError

balance = Balance(currency="USD", amount=D("100.00"))

try:
    balance.currency = "EUR"
except IncorrectUsageError:
    print("Value objects are immutable")

try:
    balance.amount = D("200.00")
except IncorrectUsageError:
    print("Value objects are immutable")
```

To "change" a value object, replace it entirely:

```python
with domain.domain_context():
    account.balance = Balance(currency="USD", amount=D("200.00"))
```

Methods in value objects must return NEW instances, not modify self:

```python
m1 = Money(currency="USD", amount=D("100.00"))
m2 = Money(currency="USD", amount=D("50.00"))

# add() returns NEW Money instance
m3 = m1.add(m2)

# Originals unchanged
assert m1.amount == D("100.00")
assert m2.amount == D("50.00")
assert m3.amount == D("150.00")
```

## Equality

Two value objects with the same attribute values are equal:

```python
bal1 = Balance(currency="USD", amount=D("100.00"))
bal2 = Balance(currency="USD", amount=D("100.00"))
bal3 = Balance(currency="EUR", amount=D("100.00"))

assert bal1 == bal2  # same values
assert bal1 != bal3  # different currency
```

This is fundamentally different from entities, where identity matters:
- **Value Object**: Same values → Equal
- **Entity**: Same ID → Equal (even if other attributes differ)

## Common mistakes

- **Trying to modify value objects**: VOs are immutable. Replace the entire VO instead: `account.balance = Balance(currency="USD", amount=D("200.00"))`
- **Adding identity fields**: VOs cannot have fields marked `identifier=True` or `unique=True`; registering one raises `IncorrectUsageError`. A plain `Auto()` field is accepted, but it generates a new value per instance and breaks equality. Use Entity if you need identity.
- **Using primitives instead of VOs**: Use `total = ValueObject(Money)` instead of separate `total_amount`/`total_currency` fields.

See [Anti-patterns](references/anti-patterns.md) for detailed examples of each mistake.

### What `check` reports

`check` inspects your value objects and reports this diagnostic:

- `VALUE_OBJECT_MUTABLE_FIELD`: the value object has a mutable collection field (such as a `List`), which breaks its value semantics. Replace it with an immutable representation, or move the collection onto the containing entity or aggregate. If the values carry their own identity, model them as an entity.

A second diagnostic surfaces at runtime. It depends on the values a value object is built from, so `check` cannot report it statically:

- `VALUE_OBJECT_INVARIANT_FAILED`: an `@invariant.post` on the value object did not hold when it was built, so construction raised a `ValidationError` carrying this code. It is the default code for a failed post-invariant; an invariant declared with `@invariant.post(code=...)` carries that code instead. Build the value object from values that satisfy its invariants, or catch the `ValidationError`. The messages on the error are the ones the invariant itself raised, keyed by field.

## Examples

- [Simple value object](assets/value_object_simple.py): a minimal value object

## Detailed references

- [Value Objects with Validation](references/with-validation.md): Custom validators and validation patterns
- [Value Objects with Methods](references/with-methods.md): Adding business logic and operations
- [Value Objects with Invariants](references/with-invariants.md): Cross-field validation rules
- [Nested Value Objects](references/nested-value-objects.md): Composition and nesting patterns
- [Value Objects in Aggregates](references/in-aggregates.md): Using VOs in aggregates
- [Value Objects in Entities](references/in-entities.md): Using VOs in entities
- [Equality and Immutability](references/equality-and-immutability.md): Core concepts explained
- [Anti-patterns](references/anti-patterns.md): Common mistakes and how to avoid them

## Related skills

- [aggregate](../aggregate/SKILL.md): Aggregates contain value objects
- [entity](../entity/SKILL.md): Entities contain value objects

## Verify your work

- [Verify with check](../../references/verify-with-check.md): run `check` and resolve what it reports
Files in this package (16)
  • SKILL.md 14 KB
  • assets/value_object_in_aggregate.py 9 KB
  • assets/value_object_in_entity.py 10 KB
  • assets/value_object_nested.py 7 KB
  • assets/value_object_simple.py 3 KB
  • assets/value_object_with_invariants.py 5 KB
  • assets/value_object_with_methods.py 5 KB
  • assets/value_object_with_validation.py 4 KB
  • references/anti-patterns.md 12 KB
  • references/equality-and-immutability.md 8 KB
  • references/in-aggregates.md 11 KB
  • references/in-entities.md 8 KB
  • references/nested-value-objects.md 8 KB
  • references/with-invariants.md 9 KB
  • references/with-methods.md 9 KB
  • references/with-validation.md 5 KB

Versions

The database has no other skills named value-object.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 26472297842c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100entity
    Define a Protean entity, a domain object with unique identity that is part of an aggregate. Entities are similar to aggregates but don't manage their own persistence; they're always accessed through their parent aggregate. Use when adding objects with identity to an existing…
  • 100refactor-extract-value-object
    Extract value objects from primitive fields in Protean aggregates, entities, and commands. Detects primitive obsession (raw String/Float/Integer fields representing domain concepts that deserve their own type) and refactors them into proper value objects. Use when the user says…
  • 100domain-driven-design
    Use when modeling a domain in Symfony — aggregates, entities, value objects, domain events, repositories, and the ubiquitous language. Use when the task mentions DDD, aggregate, value object, domain event, or invariant.
  • 100domain-model
    Create or review a domain model — bounded contexts, entities, value objects, aggregates, domain events, relationships. Use when: domain model, bounded context, ubiquitous language, context map, domain design, domain analysis, domain events, aggregate, entities, DDD analysis.
  • 100b2c-object-types
    Inspect and manage system object type attribute definitions and attribute groups on a live B2C Commerce instance with the b2c CLI (SCAPI Object Definitions API). Use this skill whenever the user needs to find which custom attributes exist on Product, Order, Profile,…
  • 100domain-modeling
    Domain-Driven Design: aggregates, bounded contexts, ubiquitous language, value objects, domain events, repository pattern, anti-corruption layer. When to use DDD vs simple CRUD. Entity vs value object distinction. TypeScript implementations with invariant enforcement. Use when…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.