Child pages
  • Contributions

Entities and Datatatypes ONF




Is there any IPR and/or Patentable Interest Declaration associated with this contribution NO



Note that this paper was previously contributed to TM Forum


The Model


This paper investigates the use of Dataypes and Entities in an object oriented environment and aims to clarify which to use in a given situation.


Datatype and Entity Definition

Datatypes are also often called “Value Objects” (we will use the term Datatypes here to be consistent with Tigerstripe and IBM RSA/RSM tooling.).

Note that similarly, Entities may also be called “Reference Objects”.

Datatypes must not be confused with these implementation objects:

  • Data Transfer Object / Transfer Object (Entities are translated to DTOs to send over an application interface or API) [ PoEAA ]
  • Data Access Object (Used to abstract the database implementation)


Fowler notes :

“The key difference between reference and value objects lies in how they deal with equality. A reference object uses identity as the basis for equality—maybe the identity within the programming system, such as the built-in identity of OO programming languages, or maybe some kind of ID number, such as the primary key in a relational database. A Value Object bases its notion of equality on field values within the class. Thus, two date objects may be the same if their day, month, and year values are the same.” [PoEAA]

A value object is “ A small simple object, like money or a date range, whose equality isn’t based on identity. [ PoEAA]

“One clear division between entities and values is that values override the equality method (and thus hash) while entities usually don't.” [PoEAA]


Evans notes on Entities:

“Many objects are not fundamentally defined by their attributes, but rather by a thread of continuity and identity.” Note that this should refer to attribute values, not attributes.

“An object defined primarily by its identity is called an ENTITY. An Entity must be distinguishable from other Entities even though they might have the same attributes.” [Evans] Note that again this should refer to attribute values, not attributes.


Evans notes on Datatypes:

“These are the objects that describe things”

“Many objects have no conceptual identity. These objects describe some characteristic of a thing.”

“When you care only about the attributes of an element of the model, classify it as a VALUE OBJECT.”   Note again that this should refer to attribute values, not attributes.

“Treat the VALUE OBJECT as immutable. Don’t give it any identity and avoid the design complexities necessary to maintain ENTITIES.” [Evans]


Kent Beck gives this suggestion

“To implement value-style objects (that is, objects that act like integers rather than like holders of changing state), first draw the boundary between the world of state and the world of value.” [Beck]


Why Datatypes are required

If we don’t use Datatypes, then the only grouping mechanism we have for attributes is entities.

Just using ungrouped primitives (String, integer, float, dateTime…), means that :

  • It is hard to understand the relationship between attributes in an entity (check to see if each attribute in an entity makes sense on its own – if not, then a value object may be appropriate. For example a measure and its units are related)
  • It is hard to ensure that groups of attributes don’t become separated in implementations (e.g. over an interface method call)
  • It’s hard to enforce mutability constraints between attributes, such as when groups of attributes should be null or not-null at the same time. Also with something like a date range we want startTime before endTime and a datatype allows a good way to centralise this logic.
  • Method parameter lists become long and complex and hard to understand [Beck, Parameter Object]
  • It is not possible to show multiplicity relationships between attributes. See [Refactoring] “Primitive Obsession”


Suggestions on choosing the correct Artifact type

The real issue is that as Eric Evans notes [Evans] , whether something is an Entity or a Datatype can depend on the context of its use. For example if we just use text fields to model an owner, then this is a value only (match the strings). If we create a Party model though then the concept becomes an Entity where we have a central point of management of for instance name changes and we can allow for things like two people with the same name.

Note also that the concept of model aggregates (localizing scope boundaries) in models [Evans] , reduces the likelihood of associations into Entities, making it more likely that they can become Datatypes.

In his book [Vernon] , Vaughn Vernon explores this further, in a lot of detail with examples showing the same concepts modelled as Entities or Datatypes. He emphasises that value objects measure, quantify or describe something, they are not ‘things’ themselves.

Determining what equality means for an instance of the class seems to be a good test and how duplicates would be coped with. For instance, assume a model with Order, OrderItem where both are in an aggregate with Order as the root. Order must be an Entity, but in this case OrderItem, which is local could be a Datatype (which means that duplicates for the same product won’t be possible). However, if we use the three level order pattern and also have OrderFulfillment, which associates to OrderItem, then OrderItem must be an Entity.


Suggestions on using Datatypes

  • Datatypes can have attributes that are either Datatypes, Enumerations, or primitive types. Datatypes must not have an identity (no “id”).
  • Datatypes may specialize other Datatypes.
  • Datatypes should not participate in associations; they will only be used as (Datatype or Entity) attribute types and as method parameter or return values. (An association end can’t reference a Datatype instance since it has no identity !
    While in theory a Datatype could have an outgoing association to an Entity, it will be better shown as an attribute with a type of the Entity id (OK since the id of an Entity is immutable). The book [Vernon] c overs this in a lot of detail.
  • A Datatype can be defined to be abstract. In this case, concrete subclasses can be defined. An abstract Datatype can be used as a type of a property in an Entity Class or another Datatype.
  • Datatypes should be implemented as immutable objects
  • Datatypes with subclasses should be treated similar to XML choice (where the options are fully defined at compile time) “soft final”.
  • Datatypes without subclasses should be implemented as being final (to prevent the need to support polymorphism)


Datatype hierarchies should be kept small and created only when really needed to avoid implementation issues.

Figure 1 – Datatype inheritance example


Nesting is easier to implement than inheritance, but it should be limited to a depth of perhaps two or three levels.

Note that we will define an attribute that is a primitive as having a nesting of 0 (no nesting).

In the figure below:

  • c1, da1, db1, dc1, dc2 have a nesting of 0
  • db2 has a nesting of 1
  • da2 has a nesting of 2
  • c2 has a nesting of 3 (eg. DA.da2.db2.dc1)

Figure 2 – Datatype nesting example

Suggestions on using Entities

  • Subclasses are always substitutable for their parent Entities.
  • Entities can have attributes that are either Datatypes, Enumerations, or primitive types.
  • A type must always be specified for an attribute.
  • An Entity must never appear in the model as an attribute type in an Entity or a Datatype, references between Entities are done using associations.
  • An Entity can be used as a type of an argument to a method of an operational interface, but converting it to a DTO would be better.


Appendix A - Business Events

As well as Entities and Datatypes, in an update to his book he defines an additional meta-element “Domain Event” [Evans Overview] [Fowler Event] .

Here the concept will be called Business Event to avoid confusion with software messages.

The notes suggest that BusinessEvents should be immutable (like a Value Object) and since they represent a past happening they should be named in the past tense.

BusinessEvents should have identity (like an Entity) even though they are immutable (as we may have two or more BusinessEvent instances with the same attribute values). Giving BusinessEEvents identity, also allows them to be associated to.


Appendix B – Modelling Guidelines

Guideline 1 – Model Everything as an Entity

This is a good simple catch all guideline. In keeping with Martin Fowler’s “small, simple” thoughts; we don’t want or need to have huge amounts of datatypes.


Guideline 2 – Create datatypes for common groups of attributes

For instance we may have a large number of Entities that we add a validity period to (start dateTime and end dateTime).

These two attributes don’t make sense on their own, and could be used sensibly as method parameters or return values, so creation of a TimePeriod datatype makes sense.

The TMF SID defines a number of base types [SID BT] that show this form of usage.


Figure 1 - SID Base Types


Note that we have two ways we can ‘build up’ datatypes :

  1. Using subclassing – create datatype hierarchies
  2. Using datatypes as attributes of Datatypes (e.g. Rate above uses Quantity as an attribute type)

Of course we can also combine these two ways together. The issue comes when the complexity really warrants an Entity.


Guideline 3 – IF the Datatype Model becomes too complex, replace it with Entities

It is impossible to give simple numeric formulae, but perhaps anything exceeding these guidelines needs to be carefully looked at :

  • Datatype inheritance depth > 1 levels
  • Datatype attribute type depth > 1 levels
  • Combination of inheritance depth plus attribute type depth > 2


Figure 2 - within guideline 3

Note that each colour denotes a separate group of datatypes.

Figure 3 – not within guideline 3






Note that some of these references point to products or implementations. These are not recommendations for those products and are provided as examples only.


Domain-Driven Design: Tackling Complexity in the Heart of Software, Eric Evans

ISBN-10: 0-321-12521-5


Patterns of Enterprise Application Architecture, Martin Fowler; David Rice; Matthew Foemmel; Edward Hieatt; Robert Mee; Randy Stafford

ISBN-10: 0-321-12742-0


Implementation Patterns, Kent Beck

ISBN-10: 0-321-41309-1


Value Object


Refactoring: Improving the Design of Existing Code, Martin Fowler; Kent Beck; John Brant; William Opdyke; Don Roberts

ISBN-10: 0-201-48567-2


When to Make a Type

[Evans Overview]

Domain-Driven Design Reference

[Fowler Event]

Domain Event


Implementing Domain Driven Design, Vaughn Vernon
ISBN 0-321-83457-7



Document Changes




Initial Version