Recursive Structures Explained

This page explains the meaning of the term recursive as used in the data model documentation.

It is written for non-technical readers.

No database knowledge is required.

Why this page exists

In several places the entity definitions state that an entity is recursive.

For example:

HeritageObjects are recursive
DigitalAssets are recursive
ResearchChapters are recursive
Places are recursive

For readers unfamiliar with technical terminology, the word “recursive” may sound complicated.

In our project it simply describes a very natural and everyday idea.

Simple definition

Recursive means:

An item may contain smaller items of the same type.

That is all.

Nothing more technical than that.

Everyday examples

Recursive structures are common in daily life.

Folders on a computer

A folder can contain:

files
other folders

Those folders can again contain:

more folders

This creates a hierarchy.

Folder → subfolder → subfolder → file

A book

A book contains:

chapters

A chapter contains:

sections

A section may contain:

subsections

Same type repeated at smaller levels.

A building

A building contains:

floors

A floor contains:

rooms

A room may contain:

smaller spaces

Each level is still part of the same whole.

A family tree

A person has:

children

Those children have:

children

Same relationship repeated.

What this means in our data model

Some of our entities behave in exactly this way.

They can be organized into parent–child hierarchies.

This allows us to represent complex structures naturally and clearly.

Where recursion is used in the project

HeritageObjects

A HeritageObject represents something we study.

Sometimes a HeritageObject is composed of smaller parts.

Example:

Sanatorium (whole site)

 * Main building
   * Ward A
   * Ward B
 * Chapel
 * Garden

Each of these is still a HeritageObject.

They simply form a hierarchy.

This allows us to describe:

parts of buildings
rooms
components
sub-objects

without creating different entity types.

ResearchChapters

ResearchChapters structure interpretation.

Chapters may contain subchapters.

Example:

Chapter 1 – Early history

 * 1.1 Foundation
 * 1.2 First expansions
 * 1.3 Daily life

This helps organize the narrative logically.

Places

Places may be nested geographically.

Example:

Italy

 * Lazio
   * Rome
     * Sanatorium site
       * Main building

Each level is still a Place.

This supports:

geographic searches
maps
grouping by region

DigitalAssets

DigitalAssets may derive from other DigitalAssets.

Example:

Original scan

 * cropped image
 * enhanced version
 * OCR transcription (PDF)

Each file has its own description, but they are related.

This records provenance (where something came from).

Why this design is useful

Using recursive structures allows us to:

keep the model simple
avoid unnecessary entity types
describe real-world structures naturally
group items logically
navigate from general to specific
expand later without redesign

Without recursion, we would need many special-case entities like:

BuildingPart
SubChapter
SubRegion
DerivedImage

This would make the system complicated and harder to maintain.

Recursion keeps things clean and flexible.

Important clarification

Recursive does NOT mean:

mathematical
circular
infinite
complicated

It simply means:

"something may contain smaller things of the same kind"

Summary

In this project, recursion means:

HeritageObjects can contain sub-objects
Chapters can contain subchapters
Places can contain smaller places
DigitalAssets can have derived versions

This mirrors how the real world is structured.

It makes the system more natural and easier to use.

Status

Explanatory note for contributors and reviewers.