Prepare for Commons deliverable D2.6

.editorconfig

@@ -8,9 +8,6 @@ trim_trailing_whitespace = true
 insert_final_newline = true
 max_line_length = off
 
-[*.rst]
-indent_size = 4
-
 [*.bat]
 indent_style = tab
 end_of_line = crlf

CONTRIBUTING.md

@@ -43,10 +43,11 @@ First, install the required dependencies (preferably in a virtual environment):
 ```bash
 python -m venv venv
 source venv/bin/activate
-
 pip install -r requirements.txt
 ```
 
+**Note**: To activate the env on Windows, run in cmd: `venv\Scripts\activate.bat`.
+
 Then, you can build the documentation using the following command:
 
 ```bash

CONTRIBUTORS.yml

@@ -5,6 +5,20 @@ Marek Suchánek:
   orcid: 0000-0001-7525-9218
   affiliation: CTU in Prague
 
+Jana Martínková:
+  first_name: Jana
+  last_name: Martínková
+  github: jmartinkova
+  orcid: 0000-0001-8575-6533
+  affiliation: CTU in Prague
+
+Vojtěch Knaisl:
+  first_name: Vojtěch
+  last_name: Knaisl
+  github: vknaisl
+  orcid: 0000-0003-0103-8468
+  affiliation: Codevence Solutions
+
 Daniel Garijo:
   first_name: Daniel
   last_name: Garijo
@@ -39,3 +53,69 @@ Allyson Lister:
   github: allysonlister
   orcid: 0000-0002-7702-4495
   affiliation: University of Oxford
+
+Raul Palma:
+  first_name: Raul
+  last_name: Palma
+  github: rapw3k
+  orcid: 0000-0003-4289-4922
+  affiliation: Poznan Supercomputing and Networking Center
+
+Katja Moilanen:
+  first_name: Katja
+  last_name: Moilanen
+  github: katja-moilanen
+  orcid: 0000-0002-7668-5427
+  affiliation: TAU-FSD/CESSDA
+
+Andrea Mannocci:
+  first_name: Andrea
+  last_name: Mannocci
+  github: andremann
+  orcid: 0000-0002-5193-7851
+  affiliation: CNR-ISTI
+
+Paolo Manghi:
+  first_name: Paolo
+  last_name: Manghi
+  github: paolomanghi
+  orcid: 0000-0001-7291-3210
+  affiliation: CNR-ISTI
+
+Miriam Baglioni:
+  first_name: Miriam
+  last_name: baglioni
+  github: mirima2
+  orcid: 0000-0002-2273-9004
+  affiliation: CNR-ISTI
+
+Pablo Alarcón-Moreno:
+  first_name: Pablo
+  last_name: Alarcón-Moreno
+  github: pabloalarconm
+  orcid: 0000-0001-5974-589X
+  affiliation: Universidad Politécnica de Madrid
+
+Renaud Duyme:
+  first_name: Renaud
+  last_name: Duyme
+  github: rduyme
+  affiliation: ESFR
+
+Andres Tabima:
+  first_name: Andres
+  last_name: Tabima
+  github: andresTabiTuwien
+  orcid: 0009-0002-4848-5089
+  affiliation: TU Wien
+
+Menzo Windhower:
+  first_name: Menzo
+  last_name: Windhowe
+  orcid: 0000-0002-2204-4018
+  affiliation: KNAW
+
+Daan Broader:
+  first_name: Daan
+  last_name: Broader
+  affiliation: KNAW

README.md

@@ -6,7 +6,7 @@
 
 ## Usage
 
-This repository contains the source files for the OSTrails documentation. The documentation is hosted on Read-the-Docs and can be accessed [here](https://docs.ostrails.eu/en/latest/).
+This repository contains the source files for the OSTrails documentation. The documentation is hosted on Read-the-Docs and can be accessed (only for this branch) [here](https://ostrails-docs--22.org.readthedocs.build/en/22/commons/resources.html).
 
 ## Contributing
 

docs/architecture/skg_if.rst

@@ -2,7 +2,8 @@ Architecture: SKG IF
 ====================
 
 .. page-authors::
-    Tomasz Miksa
+    Andrea Mannocci
+    Paolo Manghi
 
 
 This page introduces the Scientific/Scholarly Knowledge Graph Interoperability Framework (SKG-IF). It outlines its motivation, relation to key elements, and applications in OSTrails.

docs/commons/FAIR/Assessment-Recommended-API.rst

@@ -0,0 +1,99 @@
+Assessment Recommended API
+==========================
+
+The FAIR-IF follows, as closely as possible, the REST standard;
+however, unlike many REST architectures, not all identifiers in
+the IF are “local”, and thus it is often necessary to pass the
+full GUID of an identifier from one component to another, or from
+client to server.  For example, the GUID of a Benchmark is the
+DOI of that Benchmark as recorded in the FAIRsharing registry,
+and as such, it cannot become part of the URL of the REST interface.
+
+Nevertheless, there are two “types” of calls in the FAIR-IF.
+Calls that are intended to retrieve information and calls that are
+intended to trigger an activity (such as a test or assessment).
+The latter kinds of calls are prefixed with /assess/.
+
+Please refer to the paragraphs below for API calls or implementation.
+An OpenAPI yaml specification for FTR is available in the following [link](https://github.com/OSTrails/FAIR_testing_resource_vocabulary/blob/main/development/api/open_api_description.yaml) including examples and
+method calls.
+
+
+GET calls
+---------
+
+Each of following methods will return metadata of the artifact in JSON-LD,
+following the FAIR-IF Application Profile. The method MUST accept a GET
+string with key/value as in the table below.  The same method MAY accept a JSON
+Body as in Table 1, via HTTP POST.
+
+.. list-table:: GET endpoints
+    :header-rows: 1
+    :widths: 20 20 60
+
+    * - Method
+      - Parameter
+      - Returns
+    * - ``/tests/``
+      - ``testid``
+      - A list with all the test identifiers supported by the tool.
+        When an id is sent, a DCAT record in JSON-LD is returned.
+    * - ``/benchmarks/``
+      - ``bmid``
+      - A list with all the benchmark identifiers supported by the tool.
+        When an id is sent, a DCAT record in JSON-LD is returned.
+    * - ``/metrics/``
+      - ``mid``
+      - A list with all the metrics identifiers supported by the tool.
+        When an id is sent, a DCAT record in JSON-LD is returned.
+    * - ``/algorithms/``
+      - ``aid``
+      - A list with all the algorithms identifiers supported by the tool.
+        When an id is sent, a DCAT record in JSON-LD is returned.
+
+POST calls
+----------
+
+All post requests must submit a body with the resource to assess as follows:
+
+.. code-block:: json
+
+    {
+        "resource_identifier": "https://w3id.org/example#"
+    }
+
+.. list-table:: POST endpoints
+    :header-rows: 1
+    :widths: 20 20 60
+
+    * - Method
+      - Parameter
+      - Returns
+    * - ``/assess/test/``
+      - ``testid`` and ``resource_identifier``
+      - Test result in JSON-LD
+    * - ``/assess/benchmark/``
+      - ``bmid`` and ``resource_identifier``
+      - Test result in JSON-LD
+    * - ``/assess/algorithm/``
+      - ``algoid`` and ``resource_identifier``
+      - Test result in JSON-LD
+
+In some cases, FAIR assessments may require inspecting multiple large resources. This is, for example, the case when assessing Research Objects. In such situations, the API may not immediately return the test results in JSON-LD format. Instead, it returns a JSON response with the following information:
+
+.. code-block:: json
+
+    {
+      "ticket_id": "<ID of the response>"
+    }
+
+In this case, the API returns an HTTP status code **202 (Accepted)**, indicating that the assessment request has been successfully created. Additionally, the response header **Location** contains a link where the results will be available once generated.
+
+The link follows this format::
+
+    /assess/algorithm/{ticket_id}
+
+When accessing this link, you may receive one of the following HTTP status codes:
+
+- **404 (Not Found)** if the results have not yet been generated
+- **200 (OK)** if the results are available, returned in the same JSON-LD format as a standard test result

docs/commons/FAIR/Catalogue-of-Benchmark-Scoring-Algorithms.rst

@@ -0,0 +1,60 @@
+Catalogue-of-Benchmark-Scoring-Algorithms
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+FAIR Data Point
+----------------
+
+OSTrails has generated a federated metadata registry for publishing and
+indexing FAIR Scoring Algorithm descriptions. Every Algorithm intended to be discoverable
+and to support FAIR assessment activities should be registered in this
+repository.
+
+This repository is built on top of the **FAIR Data Point (FDP)**, a
+software framework maintained by the
+`FAIRDataTeam <https://github.com/FAIRDataTeam>`_.
+
+The FDP index includes descriptions of test records from multiple
+assessment tools, such as
+`FAIR Champion </docs/docs/tools/FAIR_tools/FAIR-Champion.rst>`_
+and
+`FOOPS </docs/docs/tools/FAIR_tools/FOOPS.rst>`_.
+
+Registering a Scoring Algorithm in the Catalogue
+--------------------------------------------------
+
+To register a Scoring Algorithm, you may use one of the following standardised
+procedures:
+
+Submitting an Existing Metadata Record via FAIR Champion
+------------------------------------------------------------
+
+Visit the FAIR Champion registration page: https://tests.ostrails.eu/tests/new
+
+Provide the persistent unique identifier of your existing metadata
+record and submit it for indexing.
+
+You may verify the publication and validation status of your metadata at: https://tools.ostrails.eu/fdp-index/
+
+If your DCAT record contains structural or semantic errors, the metadata
+may be displayed as **invalid**.
+
+
+    NOTE: This method requires the metadata record to already exist in your
+    tool or repository. The record **must** comply with the FTR model.
+
+Registering Metadata via the FAIR Assessment Authoring Tool
+--------------------------------------------------------------
+
+The FAIR Assessment Authoring Tool, developed by the OSTrails team,
+supports the creation of FAIR assessment components such as Tests,
+Metrics, Benchmarks, and others.
+
+Through a machine-actionable questionnaire, the tool automatically
+generates the metadata record, stores it, and submits it to an OSTrails
+GitHub repository that acts as an openly accessible, self-hosted
+index for transparency and long-term availability. This submission also
+registers the record in the FDP-based OSTrails index: https://tools.ostrails.eu/fdp-index/
+
+The FAIR Assessment Authoring Tool is available at: https://ostrails-fair.fair-wizard.com/wizard/dashboard
+
+All its documentation is available `here </docs/docs/tools/FAIR_tools/FAIR-Assessment-Authoring-Tool.rst>`_

docs/commons/FAIR/Catalogue-of-Benchmarks.rst

@@ -0,0 +1,19 @@
+Metric and Benchmark Commons
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In the context of FAIR assessment and assistance, metrics are clearly defined, narrative descriptions of community-specific implementations of individual FAIR Principles. Benchmarks are structured groupings of these metrics that articulate how a specific research community interprets FAIR in ways that are meaningful for particular domains, object types, or use cases.
+
+Benchmarks provide a narrative that captures a community’s priorities and expectations for FAIRness, enabling consistency and comparability in assessment while preserving contextual relevance.⁤ Community-defined metrics and benchmarks are critical because they ensure that FAIR assessment is open, transparent, and adaptable: they allow researchers and domain experts to collaboratively define what FAIR means for their specific objects and workflows,
+support reuse of definitions across projects and tools, and enable FAIR assessments that are both machine-actionable and aligned with shared interpretations of FAIR. By anchoring assessments in community consensus and making these definitions discoverable and interoperable, research groups can drive more meaningful evaluation, reduce ambiguity in FAIR interpretation, and foster trust and reuse within and across disciplines.
+
+The FAIRassist registry (https://fairassist.org/registry), powered by FAIRsharing (https://fairsharing.org/) provides a trusted, community-facing commons for FAIR metrics and benchmarks used within OSTrails and by the wider research community adopting the Assess-IF. By offering a single, curated point of access, the registry helps researchers, infrastructure providers, funders, and publishers identify, compare, and reuse assessment components in a transparent and interoperable way.
+
+FAIRassist (for conceptual components such as metrics and benchmarks) and the FDP Index (for software-based assessment services) act as complementary exemplar services that demonstrate how Assess-IF components can be:
+
+- **Registered and shared** using community-agreed descriptions,
+- **Discovered efficiently**, based on digital object type, disciplinary relevance, or generic applicability, and
+- **Understood and reused**, through clear documentation that supports consistent and responsible FAIR assessments.
+
+Registering metrics and benchmarks in FAIRassist and FDP is strongly recommended to promote transparency, reuse, and FAIR-aligned assessment practices. Once a metric or benchmark is considered mature by its maintainer, it can be assigned a DOI, enabling citation, credit, and long-term reference within assessment workflows and policy contexts.
+Through FAIRsharing’s APIs and content negotiation, the registry exposes rich, human-curated descriptions in machine-actionable formats (including DCAT and JSON). This allows FAIR assessments to move beyond bespoke or opaque implementations, supporting automation, comparability, and interoperability across tools, communities, and infrastructures.
+For further details, see the sections on FAIRsharing and FAIRassist in the documentation (FAIRsharing Registry, FAIRassist Registry).

docs/commons/FAIR/Catalogue-of-Tests.rst

@@ -0,0 +1,67 @@
+Catalogue of Tests
+==================
+
+FAIR Data Point
+---------------
+
+OSTrails has generated a federated metadata registry for publishing and
+indexing FAIR Test descriptions. Every test intended to be discoverable
+and to support FAIR assessment activities should be registered in this
+repository.
+
+This repository is built on top of the **FAIR Data Point (FDP)**, a
+software framework maintained by the
+`FAIRDataTeam <https://github.com/FAIRDataTeam>`_.
+
+.. figure:: Test-Algorithm-Registry.png
+    :alt: Test Algorithm Registry
+    :align: center
+
+    Test Algorithm Registry
+
+
+The FDP index includes descriptions of test records from multiple
+assessment tools, such as
+`FAIR Champion </docs/docs/tools/FAIR_tools/FAIR-Champion.rst>`_
+and
+`FOOPS </docs/docs/tools/FAIR_tools/FOOPS.rst>`_.
+
+Registering a Test in the Catalogue
+-----------------------------------
+
+To register a test, you may use one of the following standardised
+procedures:
+
+Submitting an Existing Metadata Record via FAIR Champion
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Visit the FAIR Champion registration page: https://tests.ostrails.eu/tests/new
+
+Provide the persistent unique identifier of your existing metadata
+record and submit it for indexing.
+
+You may verify the publication and validation status of your metadata at: https://tools.ostrails.eu/fdp-index/
+
+If your DCAT record contains structural or semantic errors, the metadata
+may be displayed as **invalid**.
+
+
+    NOTE: This method requires the metadata record to already exist in your
+    tool or repository. The record **must** comply with the FTR model.
+
+Registering Metadata via the FAIR Assessment Authoring Tool
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The FAIR Assessment Authoring Tool, developed by the OSTrails team,
+supports the creation of FAIR assessment components such as Tests,
+Metrics, Benchmarks, and others.
+
+Through a machine-actionable questionnaire, the tool automatically
+generates the metadata record, stores it, and submits it to an OSTrails
+GitHub repository that acts as an openly accessible, self-hosted
+index for transparency and long-term availability. This submission also
+registers the record in the FDP-based OSTrails index: https://tools.ostrails.eu/fdp-index/
+
+The FAIR Assessment Authoring Tool is available at: https://ostrails-fair.fair-wizard.com/wizard/dashboard
+
+All its documentation is available `here </docs/docs/tools/FAIR_tools/FAIR-Assessment-Authoring-Tool.rst>`_