Domain Entity

Origin & evolution

Eric Evans named the distinction in Domain-Driven Design (2003). His formulation is that many objects "are not fundamentally defined by their attributes, but rather by a thread of continuity and identity." An entity needs🫀NeedUserA user need, pain, desire, or constraintView reference → a way to answer one question after time has passed: is this the same object? A value object💎Value ObjectEngineeringA DDD value objectView reference →, by contrast, is defined entirely by its attributes, holds no identity of its own, and two value objects with equal attributes are interchangeable.

Evans' contribution was to tie the choice to the domain model and its language, so that identity becomes a modelling decision⚖️DecisionStrategyA recorded decision with context, rationale, and consequencesView reference → about the business, not a database artefact. The practical test he gave: if you care whether two things are the same one (this order, that order), it is an entity; if you only care that two things are equal (this £20, that £20), it is a value object.

The line has stayed stable, and the live debate has moved to how strictly to apply it. Functional and event-sourced styles push more concepts toward immutable value objects and reconstruct identity from a stream of events, which narrows the set of things modelled as mutable entities. The judgement Evans asked for is the same one teams still make.

How it works in practice

A logistics platform models a Shipment as a domain entity with a shipment_id assigned at creation. Over its life the shipment moves through booked, in-transit, customs-held, and delivered; its carrier changes twice, its estimated arrival is revised nine times, and its weight is corrected after a re-scan. None of these attribute changes creates a new shipment. The identity is stable, so a dispute three months later can be settled by replaying that one shipment's history.

The same platform models the delivery Address as a value object. When a customer corrects a typo in a postcode, the system replaces the old value with a new one, because no one needs to ask whether two addresses are the same instance, only whether they are equal.

Domain entity vs. its neighbours

• Value object has no identity and is compared by attribute equality. A domain entity is compared by identity, so it can change every attribute and remain itself. Mixing the two (giving a value object a surrogate id) is a common modelling error that quietly invents identity no one needs.
• Aggregate is a cluster of entities and value objects with one entity as its root and a consistency boundary around the whole. A domain entity is a member of that cluster; the aggregate decides which entities are reachable only through the root.
• Data model🗃️Data ModelData & AnalyticsA data model or schemaView reference → describes how data is structured and stored (tables, columns, types). A domain entity is a behaviour-bearing concept in the domain language; the same entity may be persisted across several tables, and the same table may hold parts of several entities.

Robert C. Martin's Clean Architecture reinforces this separation from a different angle. In his layered model, entities occupy the innermost ring and encapsulate enterprise-wide business rules — the policies least likely to change when something external shifts. By that framing, a domain entity is not a row in a table or a DTO moving through the application; it is the stable core that outer layers — use cases, controllers, databases — depend on, not the reverse. The dependency⛓️DependencyTeam & OrganisationA cross-team or system dependencyView reference → rule runs inward, so the entity's identity and behaviour are insulated from persistence details, which is why the same entity can span several tables without the model caring how storage is arranged.

In the graph

In the Unified Product Graph, domain_entity📦Domain EntityEngineeringA DDD domain entity: a core object with a distinct identity and lifecycle inside a bounded context sits in the Engineering & Platform region, whose mental model runs from bounded context🔲Bounded ContextEngineeringA DDD bounded context defining a service boundaryView reference → through service to the leaves that carry domain meaning. It is held by its aggregate via aggregate_contains_domain_entityAggregatecontainsDomain Entityhierarchy, the hierarchy edge that encodes Evans' consistency boundary. Two semantic and causal edges then connect it outward: api_endpoint_references_domain_entityAPI EndpointreferencesDomain Entitysemantic records which endpoints expose or accept it, and data_flow_transports_domain_entityData FlowtransportsDomain Entitycausal traces it as it moves between services. Together these make a single question answerable across the graph: where does this identity-bearing concept live, who reads it, and where does it travel.