What is entity object

According to the Clean architecture entity is the object that reflect some object from business domain. Entity description from DDD is much deeper and a bit different but does not go in conflict with definition given by Clean architecture.

There are 2 main types of objects: entities and value objects. Value object is distinguished by it's contents, while entity is represented by it's identity (ID).

Real life example of entity

Disclaimer: I do not know any real cases of the story below, it was more like a city legend discussed by teenage boys who lived near the border with EU countries.

In the early 2000s Ukrainian import taxes for used cars were enormously big, and usually those taxes were twice as big as the car price you want to import. And there was a popular scheme to overcome this. All you need to do is to find and buy some old or totally damaged car of the same model you want to import, but already registered in Ukraine. Then declare the imported car not as the whole vehicle but as pile of car parts. The next step was to contact motor vehicle government body and report the magical-virtual fix when each part of your crap car was replaced by the shiny new part imported abroad. Practically those were 2 different cars but on paper it was the same car but fixed.

Car papers does represent the entity in this case. Treating the car as the same is the whole idea of the entity. Dealing with entity you do not care about the object contents, you care about the object identity. Entity represents is something worthy to have own ID card, and only this document means something to the system, not the content.

Indeed any car part does represent the value object - you can swap any of them and car would remain the same for the system.

Software example

Usually there is temptation to use entities for every object stored into the database. This is the bias of object design based on relational model. When making relational schema each row should have primary key which is usually a generic auto incremented id.

Classical example with the e-commerce shop. We have Orders containing all details like customer and date and child list of OrderItems having the Product and amount.

Order {
    id
    clientId
    creationDate
}

OrderItem {
    id
    orderId
    productId
    countItems
}

Product {
    id
    price
    name
}

What can go wrong here? Any change of the product price would affect old historical orders. The obvious fix is to copy the price of the product when creating OrderItem.

Order {
    id
    clientId
    creationDate
}

OrderItem {
    id
    orderId
    productId
    productPrice
    countItems
}

Product {
    id
    price
    name
}

In fact we'd swapped the productId entity relation by the value object { productId, productPrice } , and in future it  can be extended with some fields like productDiscount or name if product tends to change the name but we want to keep the old one in executed orders.

So in other words, when the order is executed we'd better copy all the needed fields from Product entity into a value object contained in the OrderItem and just keep and treat the Product entity as a template.

Order {
    id
    clientId
    creationDate
}

OrderItem {
    id
    orderId
    product {
      price
      discount
      name
    }
    countItems
}

Product {
    id
    price
    name
    discount
}

We'll maybe losing the relation to the parent template is a bad idea in terms of collecting statistics or forwarding user to the product page when clicking on existing order, so we can keep the productId reference in the product object.

OrderItem {
    id
    orderId
    product {
      price
      discount
      name
      parentProductId
    }
    countItems
}

I named the field parentProductId to highlight that this is some external reference, and it should be used more for informational purposes rather than for business ones - like calculating the order price or generating an invoice.

***

Well that's it. To wrap up: Entity is the object that is uniq and proves it's uniqueness by it's unique id filed value. Value object is something that can survive without an id and usually is copied all over. If you want to create an entity instead of a value object, because it's reused in several places, maybe you want to create a template entity for value objects creating. Don't create more entities than you need, entities are expensive to maintain while value objects are cheap.