Resource Registry Service Documentation

Fundamentals and Model

• Introduction to Information Systems What is an Information System for a Federated Research Infrastructure and why does it need a DDL (Data Definition Language)? The academic and business context.

• Normative Terminology & Typographic Conventions The strict terminology guide required to accurately understand and discuss the model and APIs.

• The Information System Model — Core Topology The theoretical manifesto of the Graph Model, Contexts, and Types.

• The Information System Model — Mutations & Avalanches Detailed mechanics of graph transitions, including Add Propagation, Remove Propagation, and Recursive Avalanches.

Data Representation

• Data Representation (Schemas) How Contexts and Type schemas translate into JSON payloads.

• Data Representation (Instances) How graph Instances, Query Templates, and Operation Envelopes are serialized in JSON.

REST API Reference

• REST API Foundations & Roles The operational manual for the REST transport: HTTP methods, Idempotency, Authentication, and the IAM Roles.

• API Management (Contexts & Types) Administrative endpoints for defining the infrastructure scope and validating schemas.

• API Management (Instances & Admin) The core of the Graph database: structural mutations, local copy-on-write, subtree synchronization, and whole-system maintenance, diagnostics, and destructive operations.

• API Access & Query Templates The execution environment: managing stored templates and invoking the read-only facade.

• API Query Parameters Reference A deep dive into parameters dictating the shape, depth, and hierarchical boundary of queries.

Architecture

• Architectural Decisions A manifesto of the fundamental implementation choices, tracking why the model behaves the way it does.

• References The origins of the architecture and consolidated bibliography.

---

Appendices

• Formal Semantics The mathematical set theory defining Context membership and intersections.

• Element Category Matrix A quick reference for the structural differences and capabilities of the various categories of elements within the Information System.

• Complex Topology Scenarios Advanced scenarios, including cyclic graphs and their resolution during avalanches.

• Response Shape Matrix A unified reference for how query parameters and HTTP headers alter the structural density and schema of the JSON response payload.

• API Operational Cookbook Real-world operational patterns, including Facet Forking, Hierarchical Distribution, and surgical Relation deletion.

• Ecosystem Tooling & Clients The Java ecosystem: annotations, documentation generators, and modular REST clients.

• JSON Query Syntax Reference Manual for executing structured JSON queries with _emit, _or, _and.

• HATEOAS Navigation Controls The exact matrix of Hypermedia HTTP Link relations emitted by the various API endpoints.

• X-Result-Scope Conventions The normative values emitted by the X-Result-Scope header to signal dynamic visibility filtering.

• A Case: the State of a Service in One Context A shared Resource whose situation differs in one Context: three ways of modelling it, and the one chosen.

Type Dictionaries

Both the foundational IS-Model types (Resource, Facet, IsRelatedTo, ConsistsOf, Property) and this deployment’s gcube-model types — registered at runtime and immutable once registered — are documented at /model-docs, generated directly from this instance’s live schema so it is never out of date with what is actually registered. gcube-model types can also be queried directly (GET /types/{type-name}, QUERY /types).