Domain model versus DTO: what is the difference, why should you keep them separate, and how do you map between them in a .NET application? Discuss over-posting, API versioning, EF Core entities and when sharing one type is acceptable.

1. Where DTOs live in a layered/clean architecture

API layer:          Request/Response DTOs, validation, mapping, ProblemDetails
Application layer:  Commands/queries (often records), use-case handlers
Domain layer:       Entities, value objects, domain services, events (no DTOs)
Infrastructure:     EF Core DbContext, configurations, external API DTOs (anti-corruption layer)

External API clients also have their own DTOs (e.g. Stripe's JSON shapes), translated to domain types in an anti-corruption layer so provider changes don't leak inward.

2. EF Core entities: domain model, persistence model or both?

Two common approaches:

• Domain model = EF entities (most common in .NET): rich classes with private setters, backing fields and owned/complex types, configured via IEntityTypeConfiguration<T>. EF Core supports private constructors and fields, so a reasonably pure domain model is achievable.
• Separate persistence models: domain objects mapped to/from EF-specific classes. Purer but more mapping; worthwhile when persistence and domain shapes diverge significantly.

Either way, EF entities are not API DTOs.

3. Over-posting in detail

Model binding sets any public settable property present in the request. Mitigations:

• Use request DTOs with only allowed fields (best).
• [BindNever]/[Bind("Name,Phone")] attributes (MVC) — brittle allow/deny lists.
• JsonUnmappedMemberHandling.Disallow (.NET 8) to reject unknown JSON properties.
• Authorisation per property (e.g. only admins may set certain fields) handled in the use case, not by binding.

The related under-posting problem: missing fields bind as defaults (e.g. IsActive=false) and overwrite data in full updates — use required members, PATCH semantics (JSON Patch or explicit optional wrappers), and validation.

4. API versioning with DTOs

• Keep DTOs per version (V1.OrderResponse, V2.OrderResponse), mapped from the same domain model.
• Additive changes (new optional fields) are usually non-breaking; renames/removals require a new version.
• Asp.Versioning.Http supports URL/header/media-type versioning; OpenAPI documents per version.
• Contract tests (snapshot the OpenAPI JSON or use Pact) catch accidental breaking changes.

5. Mapping performance and correctness

• Projections (Select) avoid loading entities and tracking — the fastest read path.
• Manual/Mapperly mappings are compile-time and allocation-efficient.
• Reflection mappers add start-up cost and run-time configuration validation; use AssertConfigurationIsValid in tests if you use them.
• Unit-test mapping only where logic exists (formatting, calculations); trivial mappings are covered by integration tests.

6. Validation layers

• DTO validation: shape and format (required fields, lengths, email format) via data annotations, FluentValidation, or .NET 10 minimal API validation.
• Domain validation: business rules and invariants (can't ship an unpaid order) inside entities/value objects.
• Don't duplicate business rules in DTO validators; don't put format validation for HTTP concerns in the domain.

Try it yourself

1. Bind an EF entity directly in a minimal API and exploit over-posting with an extra JSON property.
2. Replace it with a request DTO and a domain method call; enable JsonUnmappedMemberHandling.Disallow.
3. Write a projection query to a response DTO and compare the SQL with Include + mapping.
4. Generate a mapper with Mapperly and introduce an unmapped property to see the compile-time diagnostic.

// DTOs: contracts at the boundary
public sealed record UpdateCustomerRequest(string Email, string? Phone);
public sealed record CustomerResponse(Guid Id, string Name, string Email, string? Phone);

// Domain model: rules live here
public sealed class Customer
{
    public Guid Id { get; private set; }
    public string Name { get; private set; } = "";
    public string Email { get; private set; } = "";
    public string? Phone { get; private set; }
    public decimal CreditLimit { get; private set; }     // never set from a request

    public void UpdateContactDetails(string email, string? phone)
    {
        if (!MailAddress.TryCreate(email, out _)) throw new DomainException("Invalid email");
        Email = email.Trim().ToLowerInvariant();
        Phone = phone?.Trim();
    }
}

// Inbound: DTO -> domain method (no property-by-property mapping onto the entity)
app.MapPut("/customers/{id:guid}", async (Guid id, UpdateCustomerRequest req, AppDb db, CancellationToken ct) =>
{
    var customer = await db.Customers.FindAsync([id], ct);
    if (customer is null) return Results.NotFound();
    customer.UpdateContactDetails(req.Email, req.Phone);
    await db.SaveChangesAsync(ct);
    return Results.Ok(customer.ToResponse());
});

// Outbound: manual mapping or Mapperly
public static class CustomerMappings
{
    public static CustomerResponse ToResponse(this Customer c) => new(c.Id, c.Name, c.Email, c.Phone);
}

[Mapper]
public static partial class OrderMapper
{
    public static partial OrderResponse ToResponse(Order order);   // generated at compile time
}

// Reads: project straight to the DTO
var page = await db.Customers
    .OrderBy(c => c.Name)
    .Select(c => new CustomerResponse(c.Id, c.Name, c.Email, c.Phone))
    .Take(50)
    .ToListAsync(ct);