View source for ICT:Recursive structures explained

= 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.