Design principles and best practices for

data entities
• 20/06/2017
• Tiempo de lectura: 4 minutos
•
o

This article describes design principles for data entities. It also includes guidelines for
the names of data entities, fields, relation roles, roles, and OData EntityTypes and
EntitySets.

Entity design principles

A data entity should provide a holistic object that encapsulates the relevant business
logic in a single consumable contract. The contract is then exposed through application
interfaces (APIs), such as OData, import and export, integration, and the programming
model. Each data entity should be designed to meet the following goals.

Encapsulation
• Each entity should provide an abstraction between the physical data model and the
consumer of the entity. The entity should encapsulate the underlying tables that, together,
can define an object that has a specific purpose in the business. Consumers of the entity
might be form clients, services, and integration.
• Each entity should encapsulate multiple related tables to represent the domain object. In
some situations, single table entities are acceptable.
A single public contract
• The public contract for an entity should be the same across all integration end points. For
example, the customer entity must expose the same fields or API to both OData and
import/export. This principle guarantees that the published schema for an entity is
consistent, regardless of the mechanism for consumer interaction.
• When an entity is consumed, the business logic that is executed within the entity during
CRUD operations must not vary based on the type of consumer.
Simplicity
• The consumer of an entity should be able to interact with the entity based on the
accepted industry or domain definitions of the entity. The behavior details of the entity
should be kept hidden and should be prevented from distorting the interaction.
• The consumer of an entity must be able to interact with the entity by using the natural key
of the entity. The consumer must not be required to use any keys that are
implementation-specific, such as any surrogate key that it generates.
Naming guidelines
Data entity names
DATA ENTITY NAMES

Do Don’t

Prefix the name with standard prefixes, because of the lack of namespaces. Don't include
underscores in
names.

Add the postfix "Entity" to the name to prevent conflicts with tables and classes that have the Don't use
same prefix. abbreviations in
conceptual names.

Give the entity a conceptual name that is aligned with the name in the en-us UI. For example,
the conceptual name of the entity that exposes records from the InventTable table should be
named ReleasedProduct, so that the full name of the entity will
be EcoResReleasedProductEntity.

Result: <prefix><ConceptualName>Entity

Data entity field names

DATA ENTITY FIELD NAMES

Do Don’t

Give the field name a conceptual name that is aligned with the name Don't include prefixes in field names. For
in the en-us UI. For example, use ItemNumber instead of ItemID as example, a field should not be
the field name to align with the UI, where the label is Item number. named InventLocationId.

Add the postfix "ID," "Number," and so on, to the name of a field that Don't include country/region-specific postfixes
is part of foreign keys to prevent collision with the navigation in field names. For example, a field should not
properties. For example, use WarehouseID instead of Warehouse as a be named InventoryProfileID_RU.
field name, because Warehouse is the navigation method to
the Warehouse entity.

Don't include underscores in field names.

Don't use abbreviations in field names.

Data entity relation role names
DATA ENTITY RELATION ROLE NAMES

Do Don’t

Use the plural form when you name roles that have a
cardinality that is higher than 1. For example, the foreign key
on Customer to Party should have the role name of
Customers, because the cardinality from Party to Customer is
0...N.
Don't include prefixes in relation role names. For
example, don’t use the
name WMSWarehouseLocation, even though the
referenced entity includes the prefix "WMS."

Use the singular form when you name roles that have a
cardinality of 0 (zero) or 1. For example, the foreign key on
Worker to Person should have the role name of Worker,
because the cardinality from Person to Worker is 0..1.
Don't add the postfix "Entity" to relation role names.
For example, don’t use the role
name WarehouseEntity in a relationship, even though
the referenced entity includes the name "Entity."
Instead, use the name Warehouse.

Consider adding the role of the relationship as a prefix. For Don't add country/region-specific postfixes to relation
example, to clearly describe the role of the relationship, name role names. For example, don’t use the role
a relationship BuyingLegalEntity instead of LegalEntity. name InventoryProfile_RU, even though the
relationship applies only in an RU country/region
format.

Don't include underscores in relation role names.

Data entity relation names

Do

• Give the relation name the same name as the related role name, in singular form. For
example, the relation that describes the foreign key from Customer to Party should be
named Party.
OData EntityType names

Do

• Give the EntityType a conceptual name. The name should be the same as the conceptual
name of the data entity, but without the prefix and without the "Entity" postfix. For
example, EcoResReleasedProductEntity becomes ReleasedProduct.
• Name the EntityType in singular form.
OData EntitySet (Entity Collection) names

Do
• Name the EntitySet in plural form. For example, the EntitySet for
the ReleasedProduct EntityType is ReleasedProducts.