Add Commons info, fix figures and contributors

MarekSuchanek · MarekSuchanek · commit 37c6833989fb · 2025-02-19T12:11:33.000+01:00
diff --git a/CONTRIBUTORS.yml b/CONTRIBUTORS.yml
@@ -1,4 +1,4 @@
-Marek Suchanek:
+Marek Suchánek:
   first_name: Marek
   last_name: Suchánek
   github: MarekSuchanek
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -2,6 +2,16 @@
     display: none;
 }
 
+figure {
+  margin: 0.5em;
+}
+
+figcaption p {
+    margin-top: 0;
+    color: var(--color-toc-item-text);
+    font-size: 80%;
+}
+
 /* Authors */
 .authors {
     border-top: 1px solid var(--color-brand-content);
diff --git a/docs/architecture/dmp_if.rst b/docs/architecture/dmp_if.rst
@@ -1,9 +1,9 @@
-.. page-authors::
-    Tomasz Miksa
-
 Architecture: DMP IF
 ====================
 
+.. page-authors::
+    Tomasz Miksa
+
 An **interoperability framework** refers to a set of guidelines, standards, and protocols that ensure the ability of different systems, applications, or organizations to work together effectively, exchanging data and functions seamlessly despite differences in their underlying technologies. The framework typically addresses the technical, semantic, and organizational aspects needed to facilitate collaboration and integration between disparate systems.
 
 The **DMP-IF** consists of:
diff --git a/docs/architecture/fair_if.rst b/docs/architecture/fair_if.rst
@@ -1,14 +1,20 @@
 Architecture: FAIR-IF
 =====================
 
+.. page-authors::
+    Daniel Garijo
+
 The FAIR Testing Interoperability Framework (FAIR-IF) uses, almost exclusively, existing standards or extensions of standards, such as W3C Data Quality Vocabulary (https://www.w3.org/TR/vocab-dqv/), the W3C Data Catalog vocabulary (https://www.w3.org/TR/vocab-dcat-3/) and the W3C Provenance Ontology (https://www.w3.org/TR/prov-o/). These are employed to build the descriptors for the components that make up the FAIR Testing Reference Model and are described here. While most of these components contribute only indirectly to the Interoperability behaviour of the FAIR-IF, a brief discussion of all of them will simplify understanding how Interoperability is achieved.
 
 FAIR Reference Model Conceptual Components
 ******************************************
 
 Guided by the Compliance Assessment Toolkit [1], we have identified the set of distinct components that make up a FAIR testing environment.  These, and the relationships between them, are diagrammed in Figure 1. These are categorised as Conceptual (shown in green), Software (blue), and Data (orange) levels. In addition, there is a higher level of Conceptual object we call a Dimension (red), which represents an established principle (e.g. FAIR Principle F1) that motivates the need for the creation of a FAIR test (or set of tests).
 
-.. image:: fair-if.png
+.. figure:: fair-if.png
+
+    FAIR Reference Model
+
 
 Detailed definitions of these components are work in progress as we examine use-cases emerging from the participating Pilots, to ensure that the identified FAIRness Reference Model components are a) complete, and b) match the requirements of the FAIR-IF, and the overall expectations of the OSTrails IF. Briefly, here are the current definitions of the components.
 
diff --git a/docs/architecture/intro.rst b/docs/architecture/intro.rst
@@ -1,15 +1,20 @@
-.. page-authors:: Tomasz Miksa
-
 Architecture
 ============
 
+.. page-authors::
+    Tomasz Miksa
+
+
 The OSTrails reference architecture provides guidance on realising interactions between key components identified in the OSTrails pathways: Data Management Plans (DMPs), Scientific Knowledge Graphs (SKGs), and FAIR Assessment. It clarifies which interactions are standardised within the Interoperability Frameworks and which are relevant to the project without prescribing specific implementation methods. For example, while the reference architecture specifies when the DMP API (part of the DMP Interoperability Framework) must be used, it leaves the method of accessing information from data repositories flexible.
 
 A key objective of this architecture is to prevent vendor lock-in, ensuring tools and services can be used interchangeably in typical scenarios outlined by the pathways. For instance, any SKG conforming to the SKG-IF can seamlessly integrate with DMP tools to provide additional insights into reused datasets. This architecture emphasises harmonising the modelling and exchange of information across research data management services while allowing diverse implementation choices tailored to specific use cases.
 
 The architecture also supports both current well-known and potential future patterns of interactions between components, fostering innovative use cases that enhance automation and machine-actionability of digital object information exchange. For example, while it is yet uncommon for data repositories to update DMPs, the architecture anticipates and accommodates such potential pathways.
 
-.. image:: OSTrails-architecture.png
+.. figure:: OSTrails-architecture.png
+
+    OSTrails Architecture
+
 
 We use colour coding in the diagram:
     * Orange represents the components and communications that are subject to standardisation within the DMP-IF.
@@ -42,3 +47,4 @@ Check our deliverables for more information:
     * Reichmann, S., Rey Mazón, M., Hasani-Mavriqi, I., Thaci, L., & Eckhard, D. (2024). **D1.1: Plan-Track-Assess Pathways**. Zenodo. https://doi.org/10.5281/zenodo.13145788
     * Miksa, T., Wilkinson, M., Manghi, P., & Suchánek, M. (2025). **D1.4 OSTrails Interoperability Reference Architecture V1**. Zenodo. https://doi.org/10.5281/zenodo.14795000
     * Suchánek, M., Martínková, J., Shepherdson, J., Miksa, T., Jirka, J., Knaisl, V., Moilanen, K., Sansone, S.-A., & Stavropoulos, T. (2025). **D2.5 OSTrails Commons Specifications**. Zenodo. https://doi.org/10.5281/zenodo.14795060
+
diff --git a/docs/architecture/skg_if.rst b/docs/architecture/skg_if.rst
@@ -1,8 +1,9 @@
+Architecture: SKG IF
+====================
+
 .. page-authors::
     Tomasz Miksa
 
-Architecture: SKG IF
-====================
 
 This page introduces the Scientific/Scholarly Knowledge Graph Interoperability Framework (SKG-IF). It outlines its motivation, relation to key elements, and applications in OSTrails.
 
diff --git a/docs/commons/commons-components.png b/docs/commons/commons-components.png
diff --git a/docs/commons/commons-layers.png b/docs/commons/commons-layers.png
diff --git a/docs/commons/governance.rst b/docs/commons/governance.rst
@@ -1,4 +1,58 @@
-Commons: Governance
-===================
+OSTrails Commons: Governance
+============================
 
-*To be specified*
+.. page-authors::
+    Marek Suchánek
+
+
+The OSTrails Commons is a structured collection of open, reusable specifications designed to facilitate interoperability within the OSTrails ecosystem. Its governance ensures sustainable management, adoption, and evolution. The governance framework incorporates structured leadership, participation policies, and sustainability strategies aligned with global best practices, including the Global Open Research Commons (GORC). Please note, that this is **early-stage** governance structure for OSTrails Commons and it may change as the Commons are being materialised over the course of the project.
+
+.. _commons-structure:
+
+Commons Components and Layers
+-----------------------------
+
+The Commons is organised into five components, ensuring comprehensive coverage of all included resources. Every resource, whether directly supporting interoperability or serving as foundational infrastructure, is categorised within this structure. This framework encompasses the core Plan-Track-Access framework-related elements, supporting tools, and essential management resources to maintain and evolve the Commons effectively.
+
+.. figure:: commons-components.png
+    :scale: 60%
+
+    Components of OSTrails Commons
+
+Furthermore, the Commons is organised into a layered structure that complements the core components (DMP, SKG, FAIR) and supporting tools. This approach ensures a systematic, modular framework where resources are categorised not only by their functional area but also by the type of technical or conceptual contribution they make. The layering enables consistency across components, promotes reusability, and supports the alignment of tools with the Interoperability Framework.
+
+Each layer reflects a distinct aspect of resource organisation, whether it involves APIs for tool integration, data models for structured information exchange, or compliance mechanisms for evaluating adherence to the framework. This structure is designed to D2.5 OSTrails Commons Specification remain extensible, allowing new layers to be introduced as needs evolve, especially in response to extensions or updates in the Interoperability Framework. Unlike the introduction of new components, which are tied to the PTA framework and thus less likely, additional layers may be necessary to address emerging interoperability requirements or technological advancements.
+
+.. figure:: commons-layers.png
+    :scale: 60%
+
+    Layers and Components of OSTrails Commons
+
+
+Governance Structure
+--------------------
+
+OSTrails Commons is managed through a federated governance model, ensuring adaptability and inclusivity. The governance structure consists of:
+
+- **Group of Maintainers**: Responsible for specific parts of the Commons, ensuring technical consistency, version control, and interoperability standards across components (DMP, SKG, FAIR).
+- **Resource Representatives**: Responsible for specific resource(s) that are part of the Commons, maintaining its record up-to-date and the resource aligned with the Commons and OSTrails Interoperability Framework.
+- **Community Contributors**: Researchers, developers, and stakeholders who provide feedback, propose enhancements, and contribute to resource maintenance.
+
+Maintenance and Evolution
+-------------------------
+
+The Commons evolves through structured updates and community contributions. Maintenance follows these principles:
+
+- **Versioning Policy**: Updates follow semantic versioning, ensuring compatibility and traceability.
+- **Compliance Monitoring**: Resources are periodically assessed against interoperability standards (EOSC, GORC).
+- **Feedback Mechanism**: Contributions and issues are managed via GitHub discussions and issue tracking.
+- **Deprecation & Archival**: Outdated resources are phased out following transparent guidelines to maintain usability and relevance.
+
+GORC Alignment
+--------------
+
+As part of the OSTrails Commons Specification, the Global Open Research Commons (GORC) International Model has been utilized, ensuring:
+
+- **Sustainability**: Long-term stewardship of resources and metadata.
+- **Interoperability**: Adherence to global data exchange and research infrastructure standards.
+- **Transparency & Engagement**: Open decision-making processes, public documentation, and structured community involvement.
diff --git a/docs/commons/intro.rst b/docs/commons/intro.rst
@@ -1,13 +1,13 @@
-Commons: Introduction
-=====================
+OSTrails Commons
+================
 
-.. page-authors:: Mark Wilkinson
+.. page-authors::
+    Mark Wilkinson
+    Marek Suchánek
 
-The OSTrails Commons
---------------------
 
-The OSTrails Commons (referred to also as ‘the Commons’ hereafter) is a set of open, reusable digital objects that guide and simplify the inclusion of tools into the federation of interoperable services within OSTrails This repository is a living record of the standards, schemas, API definitions, and code modules that make up the OSTrails commons.
+The **OSTrails Commons** (referred to also as ‘the Commons’ hereafter) is formally defined as a **collection of open, reusable, and adaptable resources that collectively enable and enhance interoperability** within the OSTrails ecosystem and beyond. These resources are designed to lower adoption barriers to integration by standardising interactions between tools, ensuring alignment with the OSTrails Interoperability Framework (IF) and Reference Architecture (RA). The Commons is not standalone tools or services; rather, they provide the foundational elements that support and guide the development, operation, and evolution of interoperable research-supporting platforms. By bridging technical, semantic, and procedural gaps, the Commons facilitate collaboration and scalability while remaining flexible for adaptation to emerging technologies and diverse research contexts.
 
-The Commons is built through iterative cycles, where specifications will evolve (either individually or in synchrony with other components of The Commons) to incorporate feedback from tool developers and other stakeholders. This iterative approach ensures that the Commons remains practical and adaptable. For this reason, entities in the commons are carefully versioned, and versioned releases are generated as required to ensure that the tools work together.
+The Commons is **built through iterative cycles**, where specifications will evolve (either individually or in synchrony with other components of The Commons) to **incorporate feedback from tool developers and other stakeholders**. This iterative approach ensures that the Commons remains practical and adaptable. For this reason, entities in the commons are carefully versioned, and versioned releases are generated as required to ensure that the tools work together.
 
-The Commons is guided by the Plan-Track-Assess Pathways defined by OSTrails, which provides a map of how tools interact to facilitate research workflows. The pathways flow through three primary Interoperability Frameworks (IF): the SKG-IF, the DMP-IF, and the FAIR-IF.  As such, this living repository is similarly split into three chapters with the same names, containing the detailed record of the members of that sub-set of Commons artefacts.
+The Commons is **guided by the Plan-Track-Assess Pathways defined by OSTrails**, which provides a map of how tools interact to facilitate research workflows. The pathways flow through three primary Interoperability Frameworks (IF): the SKG-IF, the DMP-IF, and the FAIR-IF.  As such, this living repository is similarly split into three chapters with the same names, containing the detailed record of the members of that sub-set of Commons artefacts.
diff --git a/docs/commons/resources.rst b/docs/commons/resources.rst
diff --git a/docs/other/contributing.rst b/docs/other/contributing.rst

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-Marek Suchanek:`
	`1`	`+Marek Suchánek:`
`2`	`2`	`first_name: Marek`
`3`	`3`	`last_name: Suchánek`
`4`	`4`	`github: MarekSuchanek`