# Resource Registry Service Documentation

```eval_rst
.. toctree::
   :hidden:
   :maxdepth: 2

   01-introduction
   02-normative-terminology
   03-is-model-core-topology
   04-is-model-mutations-and-avalanches
   05-data-representation-contexts-schemas
   06-data-representation-instances-envelopes
   07-api-foundations-and-roles
   08-api-contexts-and-types
   09-api-instances-and-admin
   10-api-query-templates-and-access
   11-api-query-parameters
   12-is-architectural-decisions
   13-references
   appendix/01-is-model-formal-semantics
   appendix/02-element-category-matrix
   appendix/03-complex-topology-scenarios
   appendix/04-response-shape-matrix
   appendix/05-api-operational-cookbook
   appendix/06-ecosystem-tooling-and-clients
   appendix/07-json-query-syntax-reference
   appendix/08-hateoas-navigation
   appendix/09-result-scope-conventions
   appendix/10-case-state-of-a-service-per-context
```

```eval_rst
.. toctree::
   :hidden:
   :caption: Conventions (non-normative)

   conventions/query-template-naming
```

## Fundamentals and Model

* [Introduction to Information Systems](01-introduction.md)
  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](02-normative-terminology.md)
  The strict terminology guide required to accurately understand and discuss the model and APIs.
* [The Information System Model — Core Topology](03-is-model-core-topology.md)
  The theoretical manifesto of the Graph Model, Contexts, and Types.
* [The Information System Model — Mutations & Avalanches](04-is-model-mutations-and-avalanches.md)
  Detailed mechanics of graph transitions, including Add Propagation, Remove Propagation, and Recursive Avalanches.

## Data Representation

* [Data Representation (Schemas)](05-data-representation-contexts-schemas.md)
  How Contexts and Type schemas translate into JSON payloads.
* [Data Representation (Instances)](06-data-representation-instances-envelopes.md)
  How graph Instances, Query Templates, and Operation Envelopes are serialized in JSON.

## REST API Reference

* [REST API Foundations & Roles](07-api-foundations-and-roles.md)
  The operational manual for the REST transport: HTTP methods, Idempotency, Authentication, and the IAM Roles.
* [API Management (Contexts & Types)](08-api-contexts-and-types.md)
  Administrative endpoints for defining the infrastructure scope and validating schemas.
* [API Management (Instances & Admin)](09-api-instances-and-admin.md)
  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](10-api-query-templates-and-access.md)
  The execution environment: managing stored templates and invoking the read-only facade.
* [API Query Parameters Reference](11-api-query-parameters.md)
  A deep dive into parameters dictating the shape, depth, and hierarchical boundary of queries.

## Architecture

* [Architectural Decisions](12-is-architectural-decisions.md)
  A manifesto of the fundamental implementation choices, tracking why the model behaves the way it does.
* [References](13-references.md)
  The origins of the architecture and consolidated bibliography.

---

## Appendices

* [Formal Semantics](appendix/01-is-model-formal-semantics.md)
  The mathematical set theory defining Context membership and intersections.
* [Element Category Matrix](appendix/02-element-category-matrix.md)
  A quick reference for the structural differences and capabilities of the various categories of elements within the Information System.
* [Complex Topology Scenarios](appendix/03-complex-topology-scenarios.md)
  Advanced scenarios, including cyclic graphs and their resolution during avalanches.
* [Response Shape Matrix](appendix/04-response-shape-matrix.md)
  A unified reference for how query parameters and HTTP headers alter the structural density and schema of the JSON response payload.
* [API Operational Cookbook](appendix/05-api-operational-cookbook.md)
  Real-world operational patterns, including Facet Forking, Hierarchical Distribution, and surgical Relation deletion.
* [Ecosystem Tooling & Clients](appendix/06-ecosystem-tooling-and-clients.md)
  The Java ecosystem: annotations, documentation generators, and modular REST clients.
* [JSON Query Syntax Reference](appendix/07-json-query-syntax-reference.md)
  Manual for executing structured JSON queries with `_emit`, `_or`, `_and`.
* [HATEOAS Navigation Controls](appendix/08-hateoas-navigation.md)
  The exact matrix of Hypermedia HTTP `Link` relations emitted by the various API endpoints.
* [X-Result-Scope Conventions](appendix/09-result-scope-conventions.md)
  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](appendix/10-case-state-of-a-service-per-context.md)
  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`](../model-docs/index.html), 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`).
