View source for ICT:Data Model entity definitions v 5.0 - new

= Data Model – Entity Definitions (Version 5.0) =

This document defines the '''conceptual meaning''' of all entities in the Costasano Heritage Database.

It is the authoritative reference for:

* conceptual ER modeling
* DBML schema design
* Page Schemas and forms
* editorial workflows
* successor understanding

These definitions describe meaning and responsibility, not implementation details.

If an entity definition is unclear or disputed, implementation must be postponed.


== Scope ==

The conceptual model separates clearly between:

* '''Storage''' → File  
* '''Interpretation of files / sources''' → Asset  
* '''Subjects of research''' → Object, Person, Organisation  
* '''Spatial context''' → Place  
* '''Narrative structure''' → Chapter  

The conceptual flow is:

'''File → Asset → Research Entity → Place → Chapter'''

Each layer enriches the previous one without replacing it.


= Core Research Entities =

== Object ==

=== Definition ===
An '''Object''' represents a historical, conceptual, or material entity that is the subject of study.

It answers:

''“What is the thing we are studying?”''

Objects are the primary conceptual anchors of the research.

=== Examples ===
An Object may represent:

* a sanatorium  
* a building  
* a room or architectural element  
* a document or register  
* a site or complex  
* a conceptual or functional unit (e.g. “medical practice”)  
* an artifact (future research)  

=== What an Object is not ===
An Object is:

* not a digital file  
* not a person  
* not an organisation  
* not a chapter  
* not a technical record  

=== Structural behavior ===
Objects are '''recursive'''.

Each Object may:

* have zero or one parent Object  
* have zero or more child Objects  

This supports hierarchical structures such as:

Room → Building → Site → City

=== Place relationship ===
Each Object has '''one primary Place'''.

This Place represents:

* where the Object exists or existed  
* the Object’s physical or historical location  

Additional contextual places (e.g. “found in”, “stored in”) may be added in future extensions.

=== Temporal span ===
Objects may have:

* DateFrom  
* DateTo  

These describe the Object’s period of existence or relevance.

=== Relationships ===
An Object may:

* be documented by multiple Assets  
* designate one Asset as preferred representation  
* be linked to Persons with roles  
* be linked to Organisations with roles  
* have a Person or Organisation as holder  
* belong to multiple Chapters  
* be tagged with Keywords  

=== Purpose ===
Objects represent the historical “things” being studied and provide the backbone of the research domain.


== Person ==

=== Definition ===
A '''Person''' represents a historical or contemporary individual with agency.

It answers:

''“Who was involved historically?”''

=== Examples ===
* religious sisters  
* directors  
* architects  
* patients  
* shareholders  
* board members  

=== What a Person is not ===
A Person is:

* not a MediaWiki user  
* not an Object  
* not an organisation  

=== Relationships ===
A Person may:

* play roles in relation to Objects  
* play roles within Organisations  
* act as holder of Objects  
* be documented by Assets (portraits, letters, articles)  

Roles belong to relationships, not to the Person entity itself.

=== Purpose ===
Persons model historical agency, responsibility, and participation.


== Organisation ==

=== Definition ===
An '''Organisation''' represents a historical collective actor with institutional continuity.

It answers:

''“Which collective body acted or was responsible?”''

=== Examples ===
* religious congregations  
* companies  
* associations  
* institutions  
* managing bodies  

=== What an Organisation is not ===
An Organisation is:

* not a person  
* not an Object  
* not a Place  

=== Relationships ===
An Organisation may:

* play roles in relation to Objects  
* include Persons with roles  
* act as holder of Objects  
* be documented by Assets  
* be located in a Place  

=== Purpose ===
Organisations model collective responsibility and institutional continuity.


= Spatial Context =

== Place ==

=== Definition ===
A '''Place''' represents a geographical or spatial location.

It answers:

''“Where is or did this exist or occur?”''

Places provide spatial context only and do not possess agency.

=== Examples ===
A Place may represent:

* a city  
* a village  
* a building  
* a room  
* a site or complex  
* a region or landscape  
* a country  

=== What a Place is not ===
A Place is:

* not a person  
* not an organisation  
* not an Object  
* not an actor with responsibility  

=== Structural behavior ===
Places are '''recursive'''.

Each Place may:

* have zero or one parent Place  
* have zero or more child Places  

Example hierarchy:

Room → Building → Site → City → Region → Country

=== Geocoding ===
Places may have:

* latitude  
* longitude  

Coordinates describe the Place itself.

=== Relationships ===
A Place may:

* locate Organisations  
* locate Objects  
* provide creation or depiction context for Assets  

=== Purpose ===
Places provide structured geographic information and prevent misuse of Organisations for spatial data.


= Digital Representation and Sources =

== Asset ==

=== Definition ===
An '''Asset''' represents the scholarly interpretation and extended metadata of '''exactly one File'''.

It answers:

''“How do we interpret and describe this specific digital file as a research source?”''

Assets are the human, scholarly layer that gives meaning to files.

=== Core principle ===
'''One Asset corresponds to exactly one File.'''

This rule is strict.

Each version of a source (TIFF, JPEG, AI‑processed, cropped detail) receives its own Asset.

=== Examples ===
An Asset may represent:

* a photograph  
* a scanned document  
* a cropped detail  
* a newspaper article  
* a portrait  
* a letter or archival record  
* an AI‑processed derivative  

=== Relationship to Files ===
An Asset:

* always references exactly one File  
* does not manage storage  
* does not replace Drupal file handling  

Files are storage.  
Assets are interpretation.

=== Recursive behavior ===
Assets are '''recursive'''.

An Asset may:

* derive from another Asset  
* have multiple derived children  

This models:

* versioning  
* derivative chains  
* multi‑representation sequences  
* cross‑media transformations  

=== Relationships to research entities ===
An Asset may document one or more:

* Objects  
* Persons  
* Organisations  

=== Spatial context ===
An Asset may optionally reference a Place to record:

* place of creation  
* place depicted  
* place of discovery  

=== Publication and citation role ===
Assets may store:

* bibliographic citation text  
* repository information  
* permalinks  
* rights information  
* publication suitability  
* AI‑processing status  

=== What an Asset is not ===
An Asset is:

* not a file  
* not a container of files  
* not a historical object  
* not merely technical metadata  

=== Purpose ===
Assets separate meaning from storage and provide rich research metadata.


= Narrative Structure =

== Chapter ==

=== Definition ===
A '''Chapter''' represents a conceptual or narrative unit of interpretation.

It answers:

''“Where does this belong in the research story?”''

=== Characteristics ===
A Chapter:

* structures interpretation  
* is not merely a date range  
* may be thematic or chronological  
* may overlap with other chapters  

=== Structural behavior ===
Chapters are '''recursive'''.

A Chapter may contain subchapters.

=== Temporal span ===
Chapters may have:

* StartYear  
* EndYear  

These describe the narrative period, not the Object’s existence.

=== Relationships ===
A Chapter may include multiple Objects.  
An Object may belong to multiple Chapters.

=== Purpose ===
Chapters organize interpretation rather than historical reality.


= Typing Entities =

== ObjectType ==
Defines the '''category of Object'''.

Examples:

* Building  
* Room  
* Document  
* Artifact  
* Collection  
* Site  

Purpose:

* supports classification  
* improves filtering and navigation  
* does not encode logic  


== AssetType ==
Defines '''what kind of thing the Asset is'''.

Examples:

* Image  
* Map  
* Document  
* Audio  
* Video  
* Drawing  
* Blueprint  
* Postcard  

Purpose:

* clarifies the nature of the source  
* supports UI grouping  
* does not imply workflow  


== AssetSourceType ==
Defines '''how the Asset was obtained'''.

Examples:

* Scan  
* Photograph  
* Archive reproduction  
* AI‑processed derivative  
* OCR transcription  
* Screenshot  
* Cropped detail  

Purpose:

* documents provenance  
* clarifies origin of the digital representation  


== AssetRole ==
Defines the '''role of an Asset relative to an Object'''.

Examples:

* Depicts  
* Documents  
* Contains  
* Shows detail of  
* Preferred representation  
* Technical reproduction  

Purpose:

* clarifies the interpretive relationship  
* supports multiple Assets per Object  


== PersonRole ==
Defines the '''role of a Person relative to an Object'''.

Examples:

* Architect  
* Director  
* Owner  
* Builder  
* Patient  
* Photographer  
* Author  

Purpose:

* expresses historical agency  
* belongs to the relationship, not the Person  


== OrganisationRole ==
Defines the '''role of an Organisation relative to an Object'''.

Examples:

* Managing body  
* Owner  
* Builder  
* Operator  
* Sponsor  
* Religious congregation  

Purpose:

* expresses institutional responsibility  


== Keywords ==
Keywords provide flexible thematic tagging.

Examples:

* Architecture  
* Healthcare  
* Maritime  
* Industrialisation  
* Daily life  

Purpose:

* supports discovery  
* does not define structure  


= Supporting Concepts =

== Holder ==
Represents the '''current custodian''' of an Object.

A holder may be:

* a Person  
* an Organisation  

Only one should be used per record.


== Treatment of Uncertainty ==
Uncertainty is expressed through:

* wording  
* ranges  
* notes  
* citations  

No structural certainty levels are implemented.


= Status =

This document defines the agreed conceptual meaning of all entities – Version 5.0.

All ER diagrams, DBML definitions, schemas, and implementations must conform to these definitions.