========================
Data Model
========================

The Resource Registry manages a graph-based data model that represents the gCube Information System Model. 
The graph consists of instances of entities (Resources and Facets) connected by instances of relationships 
(IsRelatedTo and ConsistsOf). Contexts provide a visibility and access control layer over this graph.


**Model Characteristics:**

- **Resource-Centric Design**: The model is fundamentally resource-centric, where Resources represent 
  infrastructure components that need to be managed;
- **Facet-Based Resource Description**: Resources are described through Facets, which provide specific 
  aspects of the resource (metadata, configurations, states, etc.). This approach is also known as the 
  **Facet Based Resource Model**;
- **Semantic Relationships**: ConsistsOf relationships connect Resources to their descriptive Facets, 
  providing semantic meaning to each facet's role in describing the resource;
- **Resource Interactions**: IsRelatedTo relationships capture interactions and dependencies between 
  different Resources in the  infrastructure.

Graph Model Components
======================

The Resource Registry provides a set of **base types** that serve as the foundation for extending and 
defining custom information models. These base types can be specialized through inheritance to create 
domain-specific models that meet particular infrastructure requirements.

The `gCube Model <#gcube-model>`_ represents a comprehensive example of how these base types can be 
extended to create a complete information model for research infrastructure management.

**Important**: It is the **instances of the extended types** (not the base types themselves) that form 
the knowledge graph stored in the Information System. The base types provide the structural foundation, 
while the extended types define the specific semantics and properties needed for actual resource management.

Entities
--------

**Resource**
Base type representing an infrastructure resource (services, datasets, software, etc.). Resources are the 
main entities that describe "things" to be managed in the infrastructure. This base type must be extended 
to create specific resource types with domain-specific properties and validation rules.

**Facet**
Base type representing an aspect or characteristic of a resource (metadata, configurations, states, etc.). 
Facets contribute to "build" a description of a Resource. This base type must be extended to create 
specific facet types that capture particular aspects of resources.

Relationships
-------------

**IsRelatedTo**
Base relationship type that connects resources to each other (dependencies, usage, hosting, etc.). This 
relationship captures the various interactions between resources. Must be extended to create specific 
relationship types with semantic meaning and domain-specific properties.

**ConsistsOf**
Base relationship type that connects a resource to its facets. This relationship defines the characteristics 
and metadata of the resource. Every resource must have at least one facet. While in some cases it may be 
sufficient to create instances of the base ConsistsOf type, the type can be extended to create specific 
composition relationships with semantic constraints and validation rules.

Context Concept
===============

**Context** is a fundamental visibility and access control mechanism within the gCube Information System. 
Unlike Resources and Facets, Context is NOT a graph entity but rather an organizational and security boundary 
that controls access to graph entities and relationships.


**Key Characteristics:**

- **Visibility Layer**: Contexts define which entities and relationships are visible and accessible 
  to users and services;
- **Hierarchical Organization**: Contexts are organized in hierarchical structures that reflect 
  organizational and access boundaries (e.g., Infrastructure → VO (Gateway) → VRE);
  
  *Note: The system does not enforce a maximum of three levels or require a single root. In practice, 
  this three-level hierarchy represents the typical usage pattern for which gCube was designed. 
  Different organizations adopting this technology could choose to use more or fewer levels and/or 
  not leverage the hierarchical structure at all.*

- **Not Graph Entities**: Contexts are not part of the graph structure itself but overlay it as 
  access control boundaries;
- **Membership Control**: Every graph entity (Resource, Facet) and relationship (ConsistsOf, 
  IsRelatedTo) belongs to one or more contexts;
- **Scope Definition**: Contexts define the operational scope for queries, operations, and data access;
- **Hierarchical Visibility**: Users with specific administrative roles can request visibility of 
  instances from child contexts by explicitly enabling hierarchical parameters in read and query API calls.


**Examples of Hierarchical Context Organization:**
- Infrastructure level: ``/gcube``;
- VO (Gateway) level: ``/gcube/devsec`` (child of ``/gcube``);
- VRE level: ``/gcube/devsec/devVRE`` (child of ``/gcube/devsec``, descendant of ``/gcube``).

This hierarchical organization allows users with appropriate administrative privileges to access 
instances from child contexts when operating in parent contexts (e.g., instances belonging to 
``/gcube/devsec/devVRE`` can be accessed when operating in ``/gcube/devsec`` or ``/gcube``) by 
explicitly requesting hierarchical visibility in API calls. The reverse is not possible: instances 
in parent contexts are not automatically accessible from child contexts. This provides controlled 
bottom-up visibility while maintaining strict context boundaries for regular users.

When an entity or relationship "belongs" to a context, it means it is visible and manageable within 
that context's scope, but the context itself is not represented as a node or edge in the graph.
