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,45 @@ 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

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/FAIR-Test-Results-Vocabulary-FTR.rst

@@ -0,0 +1,57 @@
+FAIR Testing Resource Vocabulary (FTR)
+=======================================
+
+Definition
+----------
+
+The FAIR Testing Resource Vocabulary (FTR) is an ontology created to
+describe the results of FAIR Assessment in a consistent,
+machine-readable way. Its purpose is to help different FAIR assessment
+tools communicate the same language for transparency and reusability.
+
+FTR is the **application profile** of the assessment components,
+acting as a reference model that extends W3C standards such as
+`DCAT <https://www.w3.org/TR/vocab-dcat-3/>`_,
+`DQV <https://www.w3.org/TR/vocab-dqv/>`_,
+`PROV <https://www.w3.org/TR/prov-o/>`_,
+and others to describe the different assessment components, such as:
+
+- **Test**: Service, formed by an API and associated piece of code that implements a Metric, and is executed (by a FAIR assessment tool), retrieving a particular and standardised result.
+- **TestResult**: Output of running a test over a resource. A test result should also contain provenance metadata about the process followed to create it. ``TestResult`` is represented as an extension of ``prov:Entity``. A test result points to the corresponding test through the ``ftr:outputFromTest`` property.
+- **TestResultSet**: A set of FAIR test results, together with their respective metadata. Common metadata may describe the set. For example, if all results were run by a request to the same API.
+- **TestExecutionActivity**: The action carried out by an agent
+
+calling an API in which a test (or set of tests) was run. The result
+of this activity is either a ``TestResult`` or a ``TestResultSet``.
+
+- **Metric**: Narrative domain-agnostic description that a Test must wholly implement.
+- **Benchmark**: Community-specific groupings of a set of Metrics that provide a narrative describing how that community defines FAIR for assessment purposes.
+- **ScoringAlgorithm**: Piece of code that contextualises the sum of all test results for a given benchmark into a final quantitative assessment result.
+- **ScoringAlgorithmActivity**: The action carried out by an agent calling an API in which a ``ScoringAlgorithm`` was executed. The result of this activity is a ``BenchmarkScore``.
+- **BenchmarkScore**: Output of a Scoring Algorithm over a resource, generating the final score and guidance for the whole assessment.
+
+----
+
+.. image:: https://github.com/OSTrails/FAIR_testing_resource_vocabulary/blob/main/development/img/FAIRTestResult_diagram_v12.drawio.png?raw=true
+    :align: center
+
+
+Specification
+-------------
+
+The full FAIR Testing Resource Vocabulary (FTR) 1.2.0 is specified here:
+
+* https://w3id.org/ftr/1.2.0
+
+You can also explore the GitHub repository for additional content:
+
+* https://github.com/OSTrails/FAIR_assessment_output_specification/
+
+
+FAIR assessment validation
+--------------------------
+
+FTR also includes `ShEX and SHACL files <https://github.com/OSTrails/FAIR_testing_resource_vocabulary/tree/main/development>`_
+for the different assessment components, allowing you to validate your
+FTR records against this representation using any RDF validator tool,
+such as `rudof <https://rudof-project.github.io/>`_.

docs/commons/FAIR/FAIR-commons.rst

@@ -0,0 +1,15 @@
+FAIR Commons
+=============
+
+The following resources in this section are part of the FAIR Commons component.
+
+
+.. toctree::
+    :caption: Commons
+    :maxdepth: 1
+    :titlesonly:
+
+    Guidance Element Specification <Guidance-Element-Specification>
+    FAIR Test Results Vocabulary (FTR) <FAIR-Test-Results-Vocabulary-FTR>
+    Assessment Recommended API <Assessment-Recommended-API>
+    Code of Shared Tests <Shared-Tests>

docs/commons/FAIR/Guidance-Element-Specification.rst

@@ -0,0 +1,14 @@
+FAIR Guidance Vocabulary Specification (FGV)
+=============================================
+
+The **FAIR Guidance Vocabulary (FGV)** provides a machine-readable ontology that implements the FAIR Guidance Model described in the OSTrails Deliverable D1.3. It formalizes the structure of FAIR-enabling guidance by extending and aligning with standards such as `DCAT <https://www.w3.org/TR/vocab-dcat-3/>`__, `Schema.org <https://schema.org/version/latest>`__, and the `Semanticscience Integrated Ontology (SIO) <http://semanticscience.org/ontology/sio.owl>`__.
+
+**FGV** describes Guidance Entities—including their *typology* (e.g., FAQ, Best Practice), their links to *external resources* (such as webpages, annotations, or API responses), and their conceptual *focus areas* (e.g., How, Why, What). This enables consistent, interoperable, and machine-actionable representation of guidance across systems and services in a FAIR manner.
+
+The code release provides the ontology, including vocabularies, definitions, and specifications in machine-readable form.
+
+    - **Persistent identifier**: `https://w3id.org/fgv# <https://w3id.org/fgv#>`__
+    - **Code Repository**: https://github.com/OSTrails/FAIR-Guidance-Vocabulary/
+    - **Latest Release**: https://github.com/OSTrails/FAIR-Guidance-Vocabulary/releases/latest
+    - **Documentation**: https://ostrails.github.io/FAIR-Guidance-Vocabulary/
+    - **License**: Creative Commons Attribution 4.0 International `CC-BY 4.0 <https://creativecommons.org/licenses/by/4.0/>`__

docs/commons/FAIR/Shared-Tests.rst

@@ -0,0 +1,15 @@
+Shared Tests
+==============
+
+The FAIR-IF defines the API for assessments.
+
+In OSTrails, code for assessment tools ("Tests") that adhere to that API is stored in public GitHub repositories.
+The repository reflects, primarily, the origin assessment platform that authored the test (e.g. Champion vs. FOOPS!)
+
+This code can be deployed by anyone, or can be used as a template to guide independent implementations of Tests.
+
+Repositories
+---------
+
+    - **FAIR Champion Core FAIR Tests**: https://github.com/wilkinsonlab/FAIR-Core-Tests
+    - **FAIR Champion OSTrails Pilots Community Tests**: https://github.com/wilkinsonlab/Community-FAIR-Tests

docs/commons/dmp/application-profile.rst

@@ -0,0 +1,72 @@
+OSTrails Application Profile for maDMPs
+=======================================
+
+.. page-authors::
+    Tomasz Miksa
+    Marek Suchánek
+    Jana Martínková
+
+
+The **OSTrails Application Profile (AP) for machine-actionable Data Management Plans (maDMPs)** is a tailored extension of the :doc:`RDA DMP Common Standard (DCS) for maDMPs <dmp-common-standard>`.
+
+It is designed to enhance interoperability while addressing requirements from national and thematic pilots, often reflecting specific funder and community templates. The profile provides a list of additional terms that can be used to express information contained in DMPs in a machine-actionable way.
+
+Upon successful review, some of the fields from the AP will be incorporated into the RDA DCS. This process is still ongoing and requires broader community consensus and RDA involvement.
+
+The work presented on this page reflects the **working draft as of January 2026**.
+
+Purpose and scope
+-----------------
+
+The OSTrails AP enhances interoperability by introducing **additional entities, fields, constraints, and usage patterns** that are not covered by the minimal core defined in the DMP Common Standard.
+
+It is designed to:
+
+- Support **information requirements imposed by funding agencies**
+- Reflect **national, institutional, and thematic practices** around DMPs
+- Enable reliable machine-to-machine interactions in the European research data management ecosystem
+
+Technically, the application profile is specified in accordance with the extension mechanisms foreseen by the DMP Common Standard and forms a core artefact of the DMP Commons as a formal description of the maDMP data structure.
+
+Iterative and community-driven development
+------------------------------------------
+
+The OSTrails Application Profile is developed **iteratively**.
+
+Rather than defining a fixed, one-time specification, the profile continuously evolves by consolidating requirements gathered from multiple perspectives and real-world implementations. This approach allows the AP to respond to emerging needs while maintaining internal consistency and interoperability.
+
+The application profile is intentionally designed as an artefact that is **by-design ready for future evolution**, both within the OSTrails project and beyond it.
+
+At present, the OSTrails AP is in an **early stage of development**, and its structure and content are expected to mature through successive iterations.
+
+Sources of requirements and inputs
+----------------------------------
+
+The OSTrails Application Profile is informed by a wide range of inputs, including:
+
+- **Funding agency DMP templates** and policy requirements
+- **European and EOSC-level guidelines** and interoperability recommendations
+- **National and regional DMP practices** identified through pilots
+- **Institutional requirements**, including those of research-performing   and research-supporting organisations
+- **Thematic and domain-specific guidelines** from research communities
+- **Feedback from national and thematic pilots within OSTrails**
+- **Practical implementation experience** from DMP platforms and services
+- **Gaps and ambiguities identified in the DMP Common Standard** when applied in operational settings
+
+These inputs are analysed, consolidated, and progressively incorporated into the application profile. Some of the exemplary efforts are documented in the :doc:`maDMP mappings <mappings/index>`.
+
+Relationship to the DMP Common Standard
+---------------------------------------
+
+The OSTrails Application Profile is a **formal extension** of the :doc:`RDA DMP Common Standard (DCS) for maDMPs <dmp-common-standard>`.
+
+This means that the profile may introduce:
+
+- new entities,
+- additional fields or attributes,
+- more specific constraints on existing elements,
+- clarified usage patterns for machine-actionable exchange.
+
+At the same time, **compatibility is a core design principle**. Every maDMP that conforms to the OSTrails Application Profile is also compliant with the broader and in a sense simpler DMP Common Standard.
+
+This ensures that DMPs expressed using the OSTrails AP remain interoperable with services that only support the core RDA model, while enabling richer interactions where the application profile is implemented.