Merge branch 'main' into feature/CAT-FR-LM-02-align-provenance

Signed-off-by: Eric Nowak <eric.nowak@msg.group>

Author: noVaSon

federated-catalogue/README.md

@@ -1,15 +1,39 @@
 # Architecture document for the GXFS Catalogue
+
 ## XFSC Federated Catalogue
-The content of the document is available here
-* [PDF](
-https://gitlab.com/gaia-x/data-infrastructure-federation-services/cat/architecture-document/-/jobs/artifacts/main/raw/build/pdf/architecture/catalogue-architecture.pdf?job=generate_pdf)
-* [Website](https://gaia-x.gitlab.io/data-infrastructure-federation-services/cat/architecture-document/architecture/catalogue-architecture.html)
 
-## FACIS - XFSC Catalogue Enhancements
-The XFSC Federated Catalogue (CAT) manages metadata objects (typically credentials or other RDF descriptions, e.g., of Providers, their Service Offerings and Resources) throughout their life cycle and exposes them to Consumers. It enables verification of these objects against given schemas and/or trust anchors. 
+The rendered architecture document (HTML site + PDF) is produced by the
+[`Run docToolchain`](https://github.com/eclipse-xfsc/docs/actions/workflows/buildDocs.yml) workflow on every push to
+`main` and uploaded as the `Documentation` artifact (containing
+`federated-catalogue/build/pdf/architecture/catalogue-architecture.pdf` and the full `build/html5/` site).
+
+Get the latest rendered docs:
+
+1. Open the [latest successful `Run docToolchain` run on `main`](https://github.com/eclipse-xfsc/docs/actions/workflows/buildDocs.yml?query=branch%3Amain+is%3Asuccess).
+2. Scroll to the **Artifacts** section and download `Documentation.zip`.
+3. Unzip — open `catalogue-architecture.pdf` for the PDF or `html5/architecture/catalogue-architecture.html` for the website.
+
+> Note: GitHub Actions artifacts expire after 90 days. For a permanent reference, link to the workflow run's commit SHA.
+
+The architecture is built by
+the [buildDocs workflow](https://github.com/eclipse-xfsc/docs/actions/workflows/buildDocs.yml) in the
+`eclipse-xfsc/docs` repository. Each workflow run uploads a `Documentation.zip` artifact containing the rendered static
+HTML and PDF; download it from the "Artifacts" section of the most recent successful run.
+
+> TODO: replace the workflow-run download with a stable, versioned public URL (e.g. GitHub Pages or a release asset)
+> once that publication channel is in place.
+
+## About the Catalogue
+
+The XFSC Federated Catalogue manages metadata objects — typically verifiable credentials or RDF descriptions of
+providers, service offerings, and resources — throughout their life cycle and exposes them to consumers. It verifies
+these objects against schemas and trust anchors.
 
-This enhancement of the CAT modularizes its verification of credentials against trust anchors and generalizes its management of metadata objects beyond the former focus on credentials; thus, it will also be able to function as a Template Repository for the FACIS Digital Contract Service (DCS).
+The current generation of the catalogue modularizes credential verification against trust anchors and generalizes
+metadata-object management beyond credentials, enabling reuse as a template repository for adjacent services.
 
-The enhanced specification document can be found here : [PDF](https://github.com/eclipse-xfsc/docs/blob/main/federated-catalogue/src/docs/CAT%20Enhancement/CAT_Enhancement_Specifications%20v1.0.pdf)
+The full functional and non-functional specification is published in the same documentation repository and linked from
+the rendered website above.
 
-The implementation of the federated catalogue can be found here : [`implementation/federated-catalogue`](https://github.com/eclipse-xfsc/federated-catalogue)
+The reference implementation lives
+at [eclipse-xfsc/federated-catalogue](https://github.com/eclipse-xfsc/federated-catalogue).

federated-catalogue/src/docs/architecture/catalogue-architecture.adoc

@@ -5,7 +5,7 @@
 //
 // ====================================
 
-= Architecture Gaia-X Federated Catalogue image:Federated-Catalogue.png[Federated Catalogue]
+= XFSC Federated Catalogue — Architecture image:Federated-Catalogue.png[Federated Catalogue]
 // toc-title definition MUST follow document title without blank line!
 :toc-title: Table of Contents
 :toclevels: 3

federated-catalogue/src/docs/architecture/chapters/01_introduction_and_goals.adoc

@@ -15,15 +15,14 @@ This document gives a short overview of the architectural design decisions for t
 
 === Requirements Overview
 
-The requirements for implementing the Gaia-X Federated Catalogue are given in its specification documentfootnote:[Gaia-X Federation Services. Core Catalogue Features. 2021. https://www.gxfs.eu/download/1740/]. Individual requirements were changed during the implementation in mutual agreement, for reasons including the following:
+The requirements for implementing the Federated Catalogue originate in its specification documentfootnote:[Gaia-X Federation Services. Core Catalogue Features. 2021. https://www.gxfs.eu/download/1740/], published as part of the GXFS programme from which XFSC emerged.
+Individual requirements were refined during implementation in mutual agreement, for reasons including the following:
 
 * The specification of a requirement turned out to be unsatisfiable for conceptual or practical reasons.
 * The understanding of an underlying concept had evolved during the further work of the Gaia-X Technical Committee and its working groups after the original publication of the requirements specification.
 
-The catalogue specification has been updated with new requirements, identified by IDs starting with CAT-FR-*.
-While these requirements are not fully implemented yet, they are planned to be completed by 2026.
-The catalogue's architecture is designed to support the implementation of these new requirements.
-In cases of conflict, the newer requirements take precedence over the older ones.
+The catalogue specification has since been extended by a successor set of functional and non-functional requirements (identified, in the SRS, by IDs beginning with `CAT-FR-` and `CAT-NFR-`).
+The architecture is designed to support these requirements; where they conflict with the original specification, the newer requirements take precedence.
 
 For more details, refer to the document "Enhancement of the XFSC Federated Catalogue" footnote:[Enhancement of the XFSC Federated Catalogue. 2025. https://github.com/eclipse-xfsc/docs/blob/9a178c30f76610e5924fd72c39d259d6a8ae0461/federated-catalogue/src/docs/CAT%20Enhancement/CAT_Enhancement_Specifications%20v1.0.pdf].
 
@@ -36,12 +35,16 @@ Quality goals regarding, e.g., performance, safety, security, and standards conf
 [options="header",cols="1,2,2"]
 |===
 |Role/Name|Contact|Expectations
-| leader and implementation partners of the GXFS project | https://gxfs.eu/ | The implementation conforms to the requirements, i.e., the functionality behind the interfaces is implemented as specified, thus facilitating integration of the Federated Catalogue with other Federation Services.  The architecture facilitates this conformance by bridging between the high level of the requirements specification and concrete design and implementation choices.
+| Original specification authors (GXFS programme, 2021–2024) | https://gxfs.eu/ | The implementation conforms to the requirements, i.e., the functionality behind the interfaces is implemented as specified, thus facilitating integration of the Federated Catalogue with other Federation Services. The architecture facilitates this conformance by bridging between the high level of the requirements specification and concrete design and implementation choices.
 | Participants in a Gaia-X ecosystem | n/a | Participants can interact with a Catalogue as expected.
 |===
 
 === Assumptions
 
+NOTE: The assumptions below are **historical context** from the 2022 reference implementation, captured here so that present-day architecture choices remain understandable.
+Several of them no longer hold literally — Gaia-X has since matured (Loire 25.05 architecture, ICAM 24.07, 25.11 ontology), and the catalogue has generalised "Self-Description" to "Asset" and "Credential".
+Where a present-day statement contradicts an assumption below, the present-day statement (and the relevant ADR) wins.
+
 Since this project is conducted in an early stage of the Gaia-X development there is no experience how credentials (formerly called Self-Descriptions) will look like in practice. Therefore, several assumptions regarding their characteristics have to be made. These assumptions will be explained in this section.
 
 * Credentials usually contain 20 to 50 claims. Bigger credentials rarely exist. Usually, the more complex ones are built by a set of complementing Verifiable Credentials.

federated-catalogue/src/docs/architecture/chapters/02_architecture_constraints.adoc

@@ -11,6 +11,10 @@ ifndef::imagesdir[:imagesdir: ../../images]
 [[section-architecture-constraints]]
 == Architecture Constraints
 
-The constraints are written in the specification of the Federated Catalogue.
+The detailed constraints on the Federated Catalogue (functional and non-functional requirements, quality scenarios, compliance obligations) are owned by the Software Requirements Specification and the successor "XFSC Federated Catalogue Enhancement" document, not restated here.
+This chapter records only the cross-cutting constraints that shape every architectural decision below.
 
-One main requirement to mention at this place is the requirement that all used components must be compliant with https://www.apache.org/licenses/LICENSE-2.0[Apache License, Version 2.0]
+* **License.** All components used by the Federated Catalogue must be compatible with the https://www.apache.org/licenses/LICENSE-2.0[Apache License, Version 2.0].
+This rules out copyleft-licensed dependencies for embedded use.
+* **Target trust framework.** The current implementation is maintained against Gaia-X Loire (see ADR 9 and the NOTE in chapter <<section-solution-strategy>>); compliance with Loire is therefore an architectural constraint, not a per-deployment choice.
+* **Federated context.** The catalogue runs in a federated ecosystem spanning operators, jurisdictions, and time zones; design decisions must not assume a single authoritative deployment, single trust anchor, or single time zone.

federated-catalogue/src/docs/architecture/chapters/03_system_scope_and_context.adoc

@@ -9,19 +9,30 @@ ifndef::imagesdir[:imagesdir: ../../images]
 :toc:
 
 [[section-system-scope-and-context]]
+== System Scope and Context
+
+The Federated Catalogue is a federation-services component: it is operated by one party (the *Federator*) and consumed by many (Participants in the federation, acting in Provider or Consumer roles).
+It does not have a direct end-user interface — clients interact with it through a Portal or through their own services that speak the catalogue's API.
+The technical deployment topology, including the surrounding Keycloak, PostgreSQL, and graph store, is described in <<section-deployment-view>>.
+
 === Business Context
 The following table shortly lists the Stakeholders for the federated catalogue:
 
 [options="header",cols="1,2"]
 |===
 | Stakeholder | Description
 | Federator | Responsible for operating the Federated Catalogue.
-| Participant (in a Federation), typically in the Provider role | Onboarded entity, according to http://docs.gaia-x.eu/technical-committee/architecture-document/latest/conceptual_model/#participants[this] definition. A Participant has a Gaia-X credential.
+| Participant (in a Federation), typically in the Provider role | Onboarded entity, according to https://docs.gaia-x.eu/technical-committee/architecture-document/25.05/trust_framework_architecture/#definitions[this] definition. A Participant has a Gaia-X credential.
 | Provider | Special type of _Participant_, who might submit credentials to the Catalogue.
 | Consumer | Special type of _Participant_, who can consume services in Gaia-X
 | User | Usually a person action on behalf of a _Participant_. A users interacts (maybe with the help of other components, like the portal) with the federated catalogue. The accessible endpoints depend on the rule, a user has.
 |===
 
-More information can be found in the http://docs.gaia-x.eu/technical-committee/architecture-document/latest/[Gaia-X Architecture document].
+More information can be found in the https://docs.gaia-x.eu/technical-committee/architecture-document/25.05/[Gaia-X Architecture Document — Loire 25.05].
+
+NOTE: The Gaia-X document set releases its sub-documents on independent version tracks.
+For the Loire release these are: **Architecture 25.05**, **Compliance 25.10**, **ICAM 24.07**, **Data Exchange 25.07**, **Ontology 25.11** (source: https://docs.gaia-x.eu/).
+External Gaia-X links throughout this document are intentionally pinned to the corresponding Loire-track version per sub-document.
+Do **not** rewrite them to `/latest/`: a future Gaia-X release would silently change the reader's interpretation of statements authored against Loire.
 
 

federated-catalogue/src/docs/architecture/chapters/04_solution_strategy.adoc

@@ -11,11 +11,21 @@ ifndef::imagesdir[:imagesdir: ../../images]
 [[section-solution-strategy]]
 == Solution Strategy
 
-This chapter describes some basic concepts and details, when handling credentials and Schemas. They are needed to understand the details.
+This chapter introduces the design concepts that the rest of the document builds on: how the catalogue thinks about credentials and assets, how content arrives at the upload endpoint, how identifiers are assigned, and how schemas are categorised.
+Detailed building blocks (verification pipeline, graph store, admin API) follow in <<section-building-block-view>>; runtime flows are in chapter 6; the deployment surface is in chapter 7.
+
+TIP: Terms used here that are not introduced inline (Asset, Trust Framework Bundle, Base Class, Loire, Tagus, ICAM, EVC/EVP, on-demand validation) are defined in the <<section-glossary,Glossary>>.
 
 === Credentials
 
-NOTE: In 2026 what was previously called "Self-Description" has been renamed to **Credential**footnote:[https://docs.gaia-x.eu/technical-committee/identity-credential-access-management/24.07/credential_format/[Gaia-X Identity, Credential and Access Management / Credential format]] — a Verifiable Presentation (VP) containing one or more Verifiable Credentials (VCs), or a standalone VC, that describes a trust framework entity. At the catalogue's API and storage level, the generic term **Asset** is used to also describe non-RDF content that can be used in the lenient default configuration, not requiring verification. This section uses "credential" to describe the original domain concept that is still available in the strict configuration profile of the catalogue.
+NOTE: What earlier Gaia-X generations called a "Self-Description" has been renamed to **Credential**footnote:[https://docs.gaia-x.eu/technical-committee/identity-credential-access-management/24.07/credential_format/[Gaia-X Identity, Credential and Access Management 24.07 (Loire) / Credential format]] — a Verifiable Presentation (VP) containing one or more Verifiable Credentials (VCs), or a standalone VC, that describes a trust-framework entity.
+At the catalogue's API and storage level, the generic term **Asset** also covers non-RDF content (PDFs, plain JSON, XML, binaries) that can be uploaded without going through the full verification pipeline — see <<_non_rdf_assets>> below.
+The catalogue ships two deployment profiles: a **lenient default profile** that runs only semantic validation and stores anything else as-is, and a **strict profile** that enables the full Gaia-X verification pipeline; both are introduced in <<_verification_profiles,chapter 5>>.
+This section uses "credential" to describe the original domain concept that remains available in the strict profile.
+
+NOTE: **Target Gaia-X release.** The current implementation has been written and is maintained against the **Gaia-X Loire** trust framework (ICAM 24.07).
+The next Gaia-X release (Danube) is **not yet supported**; ADR 17 describes the planned migration path.
+Where Java identifiers in this document or in the source tree contain the word `danubetech` (e.g. `Vc2DanubeTechCredentialProcessor`, the `VC2_DANUBETECH` format enum value), they refer to the https://danubetech.com/[danubetech] open-source Java library used to parse generic W3C VC 2.0 credentials — they are unrelated to the Gaia-X "Danube" release.
 
 ==== Granularity of Credentials
 
@@ -48,27 +58,33 @@ When content is submitted, an `RdfDetector` component classifies it as either RD
 * **RDF content** (e.g., `application/ld+json`, or `application/json` with an `@context` key) follows the existing verification pipeline: syntax check, semantic validation, claim extraction, graph storage.
 * **Non-RDF content** (e.g., `application/pdf`, `text/plain`, `application/octet-stream`, plain JSON without `@context`) bypasses verification entirely and is stored directly in the File Store with metadata in the Metadata Store. No claims are extracted and no graph database interaction occurs.
 
-The set of MIME types treated as RDF is configurable via `federated-catalogue.rdf.content-types`. Operators can adjust this allowlist to match their deployment's verification capabilities.
+The set of MIME types treated as RDF is configurable; operators can adjust the allowlist to match their deployment's verification capabilities (see the operator guide).
 
 ==== Asset IRI Assignment
 
-Every asset in the catalogue MUST be identified by an IRI, in compliance with requirement CAT-FR-AM-02: Each Asset MUST be identified by an IRI. DIDs and UUIDs as URNs (RFC 4122) MUST be supported.footnote:[Enhancement of the XFSC Federated Catalogue. 2025. https://github.com/eclipse-xfsc/docs/blob/9a178c30f76610e5924fd72c39d259d6a8ae0461/federated-catalogue/src/docs/CAT%20Enhancement/CAT_Enhancement_Specifications%20v1.0.pdf]. The supported IRI formats are:
+Every asset in the catalogue is identified by an IRI.
+The supported IRI formats are:
 
 * **DIDs** — e.g., `did:web:example.com`, `did:key:z6Mk...` (extracted from RDF credential content)
 * **UUID URNs** — e.g., `urn:uuid:550e8400-e29b-41d4-a716-446655440000` (generated per RFC 4122footnote:[https://www.rfc-editor.org/rfc/rfc4122[RFC 4122 — A Universally Unique IDentifier (UUID) URN Namespace]])
 * **Generic URNs** — e.g., `urn:nid:nss`
 * **HTTP/HTTPS IRIs** — e.g., `https://example.org/resource/123`
 
-IRI assignment is handled by the `IriGenerator` component and validated by the `IriValidator` component (see <<section-building-block-viev>>). The assignment strategy depends on the asset type:
+IRI assignment is handled by the `IriGenerator` component and validated by the `IriValidator` component (see <<section-building-block-view>>).
+The assignment strategy depends on the asset type:
 
 * **RDF assets (credentials):** The IRI is extracted from the content — `credentialSubject.id` for Verifiable Credentials, or `@id` for generic JSON-LD. OWL ontologies, SHACL shapes, and SKOS concept schemes use their respective root identifiers. If no IRI can be extracted, a UUID URN is generated as fallback.
 * **Non-RDF assets:** A UUID URN (`urn:uuid:...`) is generated automatically. Each upload receives a unique identifier per RFC 4122.
 
-All IRIs are validated on assignment. Invalid formats (null, blank, or syntactically malformed) are rejected. Duplicate content detection still applies — uploading the same content twice results in a conflict (HTTP 409), with the existing IRI returned in the error response.
+All IRIs are validated on assignment.
+Invalid formats (null, blank, or syntactically malformed) are rejected.
+Duplicate content detection still applies — uploading the same content twice is rejected as a conflict, with the existing IRI returned in the error response (see the OpenAPI specification for the exact contract).
 
 ==== Storage Strategy
 
-Non-RDF assets are stored in a dedicated File Store instance (`assetFileStore`), separate from the schema and context caches. Asset metadata (content type, file size, original filename) is stored in the `assets` table (renamed from `sdfiles`) with three additional columns. The `content` column is nullable — for non-RDF assets, the raw bytes live only in the File Store, not in the database.
+Non-RDF assets are stored in a dedicated File Store instance, separate from the schema and context caches.
+Asset metadata (content type, file size, original filename) is persisted in the metadata store.
+For non-RDF assets, the raw bytes live only in the File Store, not in the relational database.
 
 === Asset Taxonomy and Claim Naming