Modeling the domain

At the heart of any domain-driven application is the model that represents the system’s core knowledge and business rules. Modeling the domain well means translating real-world concepts into expressive, cohesive, and consistent software structures.

Entities

An entity is an object defined primarily by its identity and not just by its attributes. Even if the attributes change over time, the identity of an entity remains the same.

Main characteristics:

Has a unique identity (usually an Id).
What matters is who the entity is, not just what it contains.
Its attributes may change over time.

Creating an entity with Lino

To create a new entity using Lino, run:

lino entity new

The CLI wizard will ask for:

Service – The service where the entity will be created.
Module – The module where the entity will be created (only in modular services).
Entity name – The name used in the domain and in the database table.

Then, you will define the fields that make up the entity, configuring each one.

Available field types

Type	Description	Range / Notes
`short`	16-bit integer	-32,768 → 32,767
`int`	32-bit integer	-2,147,483,648 → 2,147,483,647
`long`	64-bit integer	-9,223,372,036,854,775,808 → 9,223,372,036,854,775,807
`string`	Text	Up to ~2 billion characters
`bool`	Boolean value	`true` or `false`
`Guid`	Globally unique identifier	Distributed uniqueness
`decimal`	High-precision decimal number	Ideal for monetary values
`float`	Floating point (32-bit)	≈ 6–9 digits of precision
`double`	Floating point (64-bit)	≈ 15–17 digits of precision
`DateTime`	Date and time	Includes time zone
`DateOnly`	Date only (C# 10+)	–
`TimeOnly`	Time only (C# 10+)	–
`Entity`	Reference to another entity	1:1 or 1:N
`Value Object`	Immutable value object	e.g., Address, CPF
`Enum`	Enumeration	Fixed set of values
`List<Entity>`	List of entities	1:N
`ManyToMany`	Many-to-many	Requires a join table

Example

Creating the entity Person:

┌────┬────┬───────────────┬────────┬────────┬───────────┬────────────────┐
│ PK │ FK │ Property name │ Type   │ Length │ Required  │ Auto-increment │
├────┼────┼───────────────┼────────┼────────┼───────────┼────────────────┤
│ x  │    │ Id            │ int    │        │     x     │       x        │
├────┼────┼───────────────┼────────┼────────┼───────────┼────────────────┤
│    │    │ Name          │ string │  100   │     x     │                │
└────┴────┴───────────────┴────────┴────────┴───────────┴────────────────┘

Structure generated by Lino:

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Domain/
                ├── MyApp.MyService.Domain.csproj
                └── Aggregates/
                    └── People/
                        ├── Person.cs
                        ├── Errors/
                        │   └── PersonErrors.cs
                        ├── Repositories/
                        │   └── IPersonRepository.cs
                        └── Resources/
                            └── Person/
                                ├── PersonResources.resx
                                ├── PersonResources.en.resx
                                └── PersonResources.pt-BR.resx

After defining your entities, use Lino itself to manage the Migrations and keep the database synchronized. We will cover this process in detail in the Persistence Layer section.

Value Objects

A value object represents a domain concept defined only by its attributes – it does not have its own identity. Two value objects are considered equal if all their values are equal.

Main characteristics:

Immutable after creation.
Do not have an Id.

Creating a value object with Lino

Run:

lino value-object new

The CLI will ask for:

Service – Service in which the object will be created.
Module – Module in which the object will be created (only in modular services).
Location – Domain root or specific aggregate.
Value object name.

Then, define the fields that make up the object.

Available field types

Type	Description	Notes
`short`	16-bit integer	-32,768 → 32,767
`int`	32-bit integer	-2,147,483,648 → 2,147,483,647
`long`	64-bit integer	-9,223,372,036,854,775,808 → 9,223,372,036,854,775,807
`string`	Text	Up to ~2 billion characters
`bool`	Boolean	`true`/`false`
`decimal`	Precise decimal	Monetary values
`float`	Floating point (32-bit)	≈ 6–9 digits
`double`	Floating point (64-bit)	≈ 15–17 digits
`DateTime`	Date/time	Includes timezone
`DateOnly`	Date only	C# 10+
`TimeOnly`	Time only	C# 10+

Example

Value object Address:

┌───────────────┬────────┬────────┬───────────┐
│ Property name │ Type   │ Length │ Required  │
├───────────────┼────────┼────────┼───────────┤
│ Street        │ string │  100   │     x     │
├───────────────┼────────┼────────┼───────────┤
│ Number        │ string │   10   │     x     │
├───────────────┼────────┼────────┼───────────┤
│ Neighborhood  │ string │   50   │           │
├───────────────┼────────┼────────┼───────────┤
│ City          │ string │  100   │     x     │
├───────────────┼────────┼────────┼───────────┤
│ State         │ string │   2    │     x     │
├───────────────┼────────┼────────┼───────────┤
│ PostalCode    │ string │   20   │     x     │
├───────────────┼────────┼────────┼───────────┤
│ Country       │ string │  100   │     x     │
└───────────────┴────────┴────────┴───────────┘

Generated file structure (aggregate Person):

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Domain/
                ├── MyApp.MyService.Domain.csproj
                └── Aggregates/
                    └── People/
                        ├── Person.cs
                        ├── ValueObjects/
                        │   └── Address.cs
                        ├── Errors/
                        │   ├── AddressErrors.cs
                        │   └── PersonErrors.cs
                        ├── Repositories/
                        │   └── IPersonRepository.cs
                        └── Resources/
                            ├── Address/
                            │   ├── AddressResources.resx
                            │   ├── AddressResources.en.resx
                            │   └── AddressResources.pt-BR.resx
                            └── Person/
                                ├── PersonResources.resx
                                ├── PersonResources.en.resx
                                └── PersonResources.pt-BR.resx

As with entities, Migrations can be managed by Lino to keep the data model in sync.

Enumerations

In DDD, enumerations can go beyond the traditional C# enum. They can be rich objects that represent fixed states, containing validations, helper methods, and even behavior.

Motivation:

C# enums are limited to an integer or string value.
Modeling an Enumeration as a class offers greater flexibility and expressiveness.

Main characteristics:

They are classes inheriting from a common base, encapsulating Id and Name.
Allow adding validations, helper methods, and behavior.

Creating an enumeration with Lino

Run:

lino enum new

The assistant will ask for:

Service.
Module (if applicable).
Location – Root of the domain or aggregate.
Enumeration name.
Type – Traditional enum or Smart Enum (class).
Storage – int or string in the database.

Example

Enumeration PersonStatus:

┌───────┬───────────┬──────────────┐
│ Value │ Name      │ Display Name │
├───────┼───────────┼──────────────┤
│ 1     │ Active    │ Active       │
├───────┼───────────┼──────────────┤
│ 2     │ Inactive  │ Inactive     │
├───────┼───────────┼──────────────┤
│ 3     │ Suspended │ Suspended    │
├───────┼───────────┼──────────────┤
│ 4     │ Deleted   │ Deleted      │
└───────┴───────────┴──────────────┘

Generated structure:

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Domain/
                ├── MyApp.MyService.Domain.csproj
                └── Aggregates/
                    └── People/
                        ├── Person.cs
                        ├── Enums/
                        │   └── PersonStatus.cs
                        ├── ValueObjects/
                        │   └── Address.cs
                        ├── Errors/
                        │   ├── AddressErrors.cs
                        │   └── PersonErrors.cs
                        ├── Repositories/
                        │   └── IPersonRepository.cs
                        └── Resources/
                            ├── Address/
                            │   ├── AddressResources.resx
                            │   ├── AddressResources.en.resx
                            │   └── AddressResources.pt-BR.resx
                            ├── Person/
                            │   ├── PersonResources.resx
                            │   ├── PersonResources.en.resx
                            │   └── PersonResources.pt-BR.resx
                            └── PersonStatus/
                                ├── PersonStatusResources.resx
                                ├── PersonStatusResources.en.resx
                                └── PersonStatusResources.pt-BR.resx

Storing an enumeration value as a string is valid and can improve readability, but tends to be less efficient in terms of performance and storage. Therefore, we recommend storing the value as an int, and to maintain referential integrity and ease maintenance, create an auxiliary entity (table) where the primary key corresponds to the enumeration value.

After defining your enumerations, use Lino to generate and apply Migrations, ensuring the database reflects the domain model. See details in the Persistence Layer section.