=====================================
Service Capabilities and Features
=====================================

The Resource Registry provides comprehensive infrastructure resource management through several key capabilities:

Context Management
==================

**Hierarchical Organization**
The service implements a sophisticated context hierarchy system that enables multi-level hierarchical 
structures. Contexts provide isolation and access control boundaries while supporting hierarchical 
visibility patterns.

**Dynamic Context Operations**
Instances can be dynamically shared across contexts, enabling flexible collaboration models between 
different context levels (Infrastructure → VO (Gateway) → VRE) while maintaining security boundaries.

**Hierarchical Visibility**
Users with appropriate administrative privileges can access entities from child contexts when operating 
in parent contexts through explicit hierarchical query parameters, providing controlled visibility 
across context boundaries.

Type System and Inheritance
===========================

**Rich Type Definitions**
The service supports a comprehensive type system with inheritance hierarchies for Resources, Facets, 
and Relationships (IsRelatedTo, ConsistsOf). Types define structure, validation rules, and behavioral 
characteristics of all graph elements.

**Type Inheritance Hierarchies**
All base types (Resource, Facet, IsRelatedTo, ConsistsOf) can be extended through inheritance to create 
specialized types with domain-specific properties and constraints. Child types inherit all properties 
and validation rules from their parent types while adding their own specific characteristics.

**Dynamic Schema Evolution**
New types can be registered and existing types can be extended through inheritance, supporting the 
evolution of the information model without breaking existing data. This allows the schema to grow 
organically while maintaining backward compatibility.

**Schema Validation**
All entity creation and modification operations are automatically validated against their defined 
types, ensuring data consistency and structural integrity. The validation includes both inherited 
and type-specific constraints.

Instance Management
===================

**Unified Entity Model**
Resources and Facets are managed through a unified instance management system that maintains their 
graph relationships (IsRelatedTo, ConsistsOf) while respecting context boundaries.

**Polymorphic Operations**
All operations on graph instances (resources, facets, and relationships) support polymorphic behavior 
where subtypes are automatically included in queries and operations. This can be controlled through the 
``polymorphic`` parameter, allowing both inclusive (default) and strict type matching. When polymorphic 
mode is enabled, querying for a parent type will automatically include all instances of its subtypes.

**Relationship Integrity**
The service ensures referential integrity across all relationships while supporting complex operations 
like context sharing that maintain relationship consistency across multiple contexts.

**Metadata Management**
All entities include comprehensive metadata (creation time, modification time, ownership) that is 
automatically managed by the service and can be filtered based on user authorization levels.

**Cross-Context Instance Views**
Administrative users can request hierarchical views that aggregate instances from child contexts, 
providing consolidated views of resources across context boundaries.

Advanced Query Capabilities
============================

The Resource Registry supports multiple sophisticated query mechanisms designed for different use cases:

**Instance Listing**
Direct type-based listing with support for pagination, polymorphic inclusion, metadata control, 
and hierarchical context aggregation. Suitable for browsing and inventory operations.

**JSON Structure Queries**
Declarative JSON-based queries that describe the desired structure and constraints. The service 
performs structure matching where graph elements must have the specified properties and relationships, 
with flexible constraint application.

**Key JSON Query Features:**
- **Structure Matching**: Queries describe the desired graph pattern using JSON that mirrors the data model structure;
- **Flexible Constraints**: Only specified properties and relationships need to match; unspecified elements are ignored;
- **Relation Traversal**: Automatic traversal of IsRelatedTo and ConsistsOf relationships to find matching patterns;
- **Logical Operators**: Support for complex constraints using logical operators (``_and``, ``_or``, ``_not``);
- **Comparison Operators**: Rich set of comparison operators for property filtering (``_eq``, ``_neq``, 
``_gt``, ``_gte``, ``_lt``, ``_lte``, ``_like``, ``_in``, etc.);
- **Mathematical Operations**: Support for mathematical operators (``_sum``, ``_minus``, ``_multiply``, etc.) 
to perform calculations on field values.

**Projection and Field Selection:**
JSON queries support advanced projection capabilities through the ``_emit`` operator, allowing selection 
of specific fields rather than complete instances:

**Field Projection**: Select specific properties from graph instances rather than complete instances 
  (e.g., ``{"_emit": {"name": "Service Name", "version": "Version"}}`` projects only the ``name`` and ``version`` 
  fields);
**Custom Field Naming**: Assign meaningful names to projected fields for enhanced result presentation 
  (e.g., ``{"_emit": {"name": "Service Name", "version": "Version"}}`` assigns custom labels "Service Name" 
  and "Version" to the projected ``name`` and ``version`` fields).

**Query Templates**
Parameterized JSON Queries that can be stored, reused, and executed with different parameter values. 
Templates support variable substitution (prefixed with ``$``) and provide a library of common 
query patterns for frequent operations.

**Prepared Queries**
Path-based queries using URL parameters to define resource-relation-entity patterns. These provide 
structured alternatives to free-form queries with built-in validation and type safety.

**Graph Queries (Development/Debug)**
Direct OrientDB SQL queries for development and debugging purposes, available only to administrators. 
These queries come with explicit warnings about production use and compatibility. They provide maximum 
flexibility but sacrifice portability and safety.

Query Response Control
======================

**Context Information**
Optional inclusion of context information showing where each entity is available across the 
context hierarchy through the ``includeContexts`` parameter.

**Pagination Support**
Comprehensive pagination support with ``limit`` and ``offset`` parameters for managing large 
result sets across all query types.

**Response Format Control**
Control over response detail level and structure through parameters like ``polymorphic``, 
``includeMeta``, ``allMeta``, ensuring optimal response sizes for different use cases.

**Metadata Inclusion Control**
Fine-grained control over metadata inclusion with role-based filtering:
- Basic users receive filtered metadata with sensitive information obfuscated
- Administrative users receive complete metadata including ownership and audit information
- ``allMeta`` parameter controls metadata inclusion for nested elements
