Embedding nested objects within parent entities

Fully embedded: nested objects within parent entities

This modeling style is particularly recommended when your ecosystem includes document-oriented databases, APIs, or other technologies that favor nested structures. In Polyglot modeling, when different paradigms must coexist, nesting generally takes precedence because it maximizes compatibility and flexibility across heterogeneous targets.

 

Different modeling situations can arise with this approach, each introducing its own considerations. Let’s explore them progressively.

 

Repository of examples

The sample models used in the examples below can be found in this repository.  They can be opened in the browser with the following links, provided proper license:

- 1-Polyglot.hck.json

- 2a-Embedding to normalization before modeler intervention-Oracle.hck.json

- 2b-Embedding to normalization after modeler intervention-Oracle.hck.json

 

Note also the naming convention applied to transform business names in the Polyglot model with Pascal case and spaces, into technical names int he physical models with lowercase and underscores)

 

Nesting object and array

In this first example, related objects are fully embedded within the parent entity in a straightforward structure. The Customer entity contains:

• An Address object (simple nested structure)
• An Orders array (list of nested objects)

 

 

 

This structure naturally fits document-oriented targets or API designs where hierarchical data is standard.

 

By deriving this Polyglot Model to a relational physical model with normalization, the structure transforms as follows:

• The Address object becomes a separate entity, linked to Customer with a 1-to-1 relationship.
• The Orders array becomes a separate entity, linked to Customer with a 1-to-many relationship.
• The Ordered product array, originally nested inside Order, also become a separate entity with a 1-to-many relationship.

 

 

For illustration purposes, entities generated from nested objects are displayed in blue in the screenshot to highlight their origin. You will also notice that primary keys and foreign keys have been automatically added to the physical model as part of the normalization process.

 

Handling shared nested objects across multiple entities

Let’s now extend our previous example to a slightly more complex but common scenario: the same nested object appears in multiple parent entities.

In this case:

• The Customer entity contains an embedded Address object
• The Supplier entity also contains an embedded Address object

 

This approach remains consistent with a Polyglot Logical Model that favors embedded structures, especially when document-oriented or API targets are involved.

 

 

When deriving this model to a relational physical target with normalization, the structure unfolds as follows:

• Each nested Address generates a corresponding entity, resulting in two separate Address entities in the physical model.

 

 

 

This is expected behavior in the derivation process, as the Polyglot Model remains agnostic to the technical constraints of specific targets. 

 

After derivation, the modeler must adjust the physical model to avoid unnecessary duplication:

• removing the superfluous Address entity — for example, the one generated from the Supplier nested object.
• creating a relationship between Supplier and the remaining shared Address entity, which originated from the nested object in Customer.

 

 

This illustrates a key trade-off in Polyglot Modeling:

• The logical model stays abstract and compatible with diverse targets.
• Minor adjustments are sometimes necessary in physical models to align with relational best practices.

 

Impact of nesting on inverse cardinalities

In a nested structure, the relationship between entities is always modeled from the perspective of the containing entity.

• If you nest a simple object: it results in a 1-to-1 relationship.
• If you nest an array: it results in a 1-to-many relationship.

 

However, this perspective does not always fully reflect the business reality, especially when the nested entity is shared across multiple occurrence of the containing entity. Let's illustrate with an example. The Customer entity contains a nested Membership plan object, which includes details like its name, its description...

 

 

 

From the Customer perspective, this looks like a simple 1-to-1 relationship: each customer has a single membership plan.

 

But in reality:

• Multiple customers can share the same Membership plan.
• The true relationship is many-to-1 from Customer to Membership plan.

 

When deriving this Polyglot Model to a relational physical model with normalization:

• The nested Membership plan becomes a separate entity.
• By default, the relationship generated reflects the original nesting: 1-to-1 between Customer and Membership plan.

 

 

This behavior is expected and consistent with the model's structure. Since the relationship is only modeled from the perspective of the containing entity (Customer) in the Polyglot model, the system cannot infer the true business cardinality in the opposite direction.

 

This is where the expertise of the data modeler is essential to manually adjust the cardinality to many-to-1, ensuring the physical model accurately represents the shared nature of membership plans.

 

 

This example highlights the importance of validating and adjusting relationships after derivation, especially when nested structures simplify the logical model but do not fully capture complex cardinalities required in certain physical implementations.