Skip to content

Commit 73bb624

Browse files
annamakorannamakor
committed
add FAIR data chapter under Distribution, CMEM-8258
The documentation did not mention FAIR anywhere, although Corporate Memory implements most of the principles and the Marketplace already carries SPDX licenses, versions and package metadata. - add a landing page explaining the four dimensions, including the note that Accessible does not mean open - add a reference page mapping all fifteen principles in the wording of the GO FAIR Foundation to the mechanism that implements them - add a FAIRification page describing the six steps for a Knowledge Graph - widen the Distribution intro from content to content and data, and add the section card Open points for a run against an instance: the fields of the graph metadata form (F2), a license statement on a graph (R1.1) and the behaviour once a described graph is removed (A2).
1 parent e16db0d commit 73bb624

7 files changed

Lines changed: 258 additions & 1 deletion

File tree

‎docs/distribution/.pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@
22
nav:
33
- Distribution: index.md
44
- Marketplace: marketplace
5+
- FAIR Data: fair-data

‎docs/distribution/fair-data/.pages‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
nav:
3+
- FAIR Data: index.md
4+
- FAIR Principles: principles
5+
- FAIRification: fairification

‎docs/distribution/fair-data/fairification/index.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
status: new
3+
title: "FAIRify a Knowledge Graph"
4+
icon: material/transit-connection-variant
5+
tags:
6+
- KnowledgeGraph
7+
- BestPractice
8+
---
9+
10+
# FAIRify a Knowledge Graph
11+
12+
Data does not become Findable, Accessible, Interoperable and Reusable (FAIR) by declaration.
13+
It becomes FAIR through a sequence of steps that attach the missing context to it - identifier, description, semantics, origin and rules of use.
14+
This sequence is called FAIRification.
15+
16+
The six steps below describe that sequence for a Knowledge Graph in eccenca Corporate Memory.
17+
Each step links to the page that documents the mechanism in detail.
18+
19+
!!! tip "Start early"
20+
21+
Origin, semantics and responsibility are expensive to reconstruct once a graph exists, and sometimes impossible.
22+
Carry out steps 1 to 4 while the graph is being built rather than after it has been published.
23+
24+
## 1. Identify the data
25+
26+
Create the graph and decide on its identifier before loading data into it.
27+
In **:eccenca-application-explore: Knowledge Graphs**, click **:eccenca-item-add-artefact: Add new graph** and select the graph type.
28+
The **Graph URI** is generated from the label by a selectable template - **Hostname + provided label**, **Selected graph + provided label**, **UUID** or **Custom**.
29+
30+
The identifiers of the resources inside the graph are determined by the mapping rules that produce them.
31+
[Cool IRIs](../../../build/cool-iris/index.md) describes how to design them so that they stay stable, and [Define Prefixes / Namespaces](../../../build/define-prefixes-namespaces/index.md) how to register the namespace.
32+
33+
## 2. Describe the data
34+
35+
Fill in the metadata form that follows the graph type.
36+
The metadata is stored as RDF about the graph IRI itself and is available to search, to queries and to any client reading the graph.
37+
38+
Agree on a minimum set of fields that every graph in the organization carries, and enforce it with a shape catalog as described in step 6.
39+
Without such an agreement the metadata differs from graph to graph, and principle F2 is satisfied for some graphs only.
40+
41+
## 3. Place the data semantically
42+
43+
Install the vocabularies and ontologies the domain already has instead of inventing terms.
44+
45+
=== "Corporate Memory"
46+
47+
Open the [Marketplace](../../marketplace/index.md), filter the package list by the **Vocabulary** package type, and click **Install** on the package.
48+
49+
=== "cmemc"
50+
51+
``` bash
52+
cmemc package search VOCABULARY
53+
cmemc package install PACKAGE_ID
54+
```
55+
56+
Record the dependency with `owl:imports`, so that the graph states which vocabularies it relies on, see [graph imports](../../../automate/cmemc-command-line-interface/command-reference/graph/imports/index.md).
57+
Where no suitable vocabulary exists, author one in the [Business knowledge editor](../../../explore-and-author/bke-module/index.md) and publish it as a package of its own.
58+
59+
## 4. Add provenance
60+
61+
Make the origin of the data readable without asking the person who built it.
62+
63+
- Enable [Versioning of Graph Changes](../../../explore-and-author/graph-exploration/versioning-of-graph-changes/index.md) on the graph to record editing activities in a Versioning Graph.
64+
- Set up [Statement Annotations](../../../explore-and-author/graph-exploration/statement-annotations/index.md) where the origin or the temporal validity of individual statements matters.
65+
- Keep the [Workflow](../../../build/workflows/index.md) that produces the graph as the record of how it was derived from its sources.
66+
67+
## 5. Attach the rules of use
68+
69+
Decide who reaches the graph and under which conditions, and record the decision where it is enforced rather than in a separate document.
70+
[Access Conditions](../../../deploy-and-configure/configuration/access-conditions/index.md) grant access per graph, per action and through dynamic conditions.
71+
72+
State the license under which the content may be reused.
73+
For content distributed as a Marketplace Package, the license is an [SPDX identifier](https://spdx.org/licenses/) in the manifest, and publication without it is rejected, see [Metadata](../../../develop/packages/development/index.md#metadata).
74+
75+
## 6. Publish and check
76+
77+
Expose the graph over the standard endpoints and verify that it holds what the shape catalog requires.
78+
79+
=== "Corporate Memory"
80+
81+
Open **:eccenca-application-explore: Knowledge Graphs** and check the resources against the node shapes of the shape catalog graph.
82+
83+
=== "cmemc"
84+
85+
``` bash
86+
cmemc graph validation execute https://ns.eccenca.com/example/data
87+
cmemc graph validation inspect <ID>
88+
```
89+
90+
Bundle the result for reuse elsewhere.
91+
[Marketplace Packages: Development and Publication](../../../develop/packages/development/index.md) describes how graphs, projects and queries are packaged into a single versioned artifact, and [Marketplace](../../marketplace/index.md) how such a package is installed into another instance.
92+
93+
!!! info "Related sections"
94+
95+
- [The FAIR principles in Corporate Memory](../principles/index.md) lists which principle each of these steps serves.

‎docs/distribution/fair-data/index.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
status: new
3+
title: "FAIR Data with Corporate Memory"
4+
icon: material/star-four-points-outline
5+
tags:
6+
- KnowledgeGraph
7+
- BestPractice
8+
---
9+
10+
# FAIR data with Corporate Memory
11+
12+
!!! abstract
13+
14+
The Findable, Accessible, Interoperable and Reusable (FAIR) principles describe the conditions under which data can be located, retrieved, understood and reused - by people as well as by machines.
15+
This section maps each principle to the mechanism in eccenca Corporate Memory that implements it, and names the points where a principle asks for an organizational decision rather than for a feature.
16+
17+
## What FAIR means
18+
19+
FAIR stands for Findable, Accessible, Interoperable and Reusable.
20+
The four dimensions are published as fifteen principles by the [GO FAIR Foundation](https://www.gofair.foundation/fair-principles).
21+
Each dimension answers one question about a dataset:
22+
23+
| Dimension | Question it answers |
24+
| --- | --- |
25+
| Findable | Is it known that the data exists, and can it be located? |
26+
| Accessible | Can the data be retrieved, under defined conditions? |
27+
| Interoperable | Do sender and receiver interpret the data the same way? |
28+
| Reusable | Can the fitness of the data for a new purpose be judged? |
29+
30+
The principles address metadata as much as data.
31+
A dataset becomes FAIR through the context that travels with it: its identifier, its description, the vocabularies it uses, its origin and the rules for its use.
32+
33+
!!! note "Accessible does not mean open"
34+
35+
Principle A1.2 requires the access protocol to support authentication and authorization where necessary.
36+
Restricted data can be FAIR data.
37+
In Corporate Memory, [Access Conditions](../../deploy-and-configure/configuration/access-conditions/index.md) determine which user group reaches which graph and which action, without affecting the findability or the description of the data.
38+
39+
## How Corporate Memory covers the four dimensions
40+
41+
| Dimension | Building blocks in Corporate Memory |
42+
| --- | --- |
43+
| Findable | IRIs for every resource and every graph, graph metadata, graph and full-text search, the Query catalog, the Marketplace |
44+
| Accessible | SPARQL endpoint, Graph Store API, RDF resource and JSON-LD Frame APIs, Keycloak, Access Conditions |
45+
| Interoperable | RDF throughout, RDFS and OWL ontologies, SKOS thesauri, SHACL shapes, vocabularies installed as Marketplace Packages |
46+
| Reusable | Shape catalogs and validation, SPDX licenses on packages, Versioning Graphs, Statement Annotations, Build workflows |
47+
48+
[The FAIR principles in Corporate Memory](principles/index.md) resolves this overview into one entry per principle.
49+
50+
<div class="grid cards" markdown>
51+
52+
- :material-format-list-checks: [The FAIR principles in Corporate Memory](principles/index.md)
53+
54+
---
55+
56+
All fifteen principles in the wording of the GO FAIR Foundation, each with the Corporate Memory mechanism that implements it and the page that documents it.
57+
58+
- :material-transit-connection-variant: [FAIRify a Knowledge Graph](fairification/index.md)
59+
60+
---
61+
62+
The six steps that turn an existing Knowledge Graph into a FAIR one, from the identifier to the published package.
63+
64+
</div>
65+
66+
## What FAIR does not cover
67+
68+
The FAIR principles describe whether data can be used.
69+
They do not describe whether data should be used for a particular purpose.
70+
A dataset can satisfy all fifteen principles and still be unsuitable for training a model, because its coverage is skewed, its annotations are unreliable, or the exact state used in an earlier run cannot be reconstructed.
71+
Fitness for purpose, bias and coverage, and the reproducibility of a given state are separate questions.
72+
They build on FAIR data rather than following from it.
73+
74+
!!! info "Related sections"
75+
76+
- [Marketplace](../marketplace/index.md) describes how ready-made vocabularies, ontologies and projects are installed as versioned packages.
77+
- [Marketplace Packages: Development and Publication](../../develop/packages/development/index.md) describes the manifest in which name, description, license and dependencies of a package are declared.
78+
- [Access Conditions](../../deploy-and-configure/configuration/access-conditions/index.md) describes how access to graphs and actions is granted.

‎docs/distribution/fair-data/principles/index.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
status: new
3+
title: "FAIR Principles in Corporate Memory"
4+
icon: material/format-list-checks
5+
tags:
6+
- KnowledgeGraph
7+
- BestPractice
8+
---
9+
10+
# The FAIR principles in Corporate Memory
11+
12+
The fifteen Findable, Accessible, Interoperable and Reusable (FAIR) principles are quoted below in the wording of the [GO FAIR Foundation](https://www.gofair.foundation/fair-principles), retrieved on 2026-10-02.
13+
For each principle, the table names the mechanism in eccenca Corporate Memory that implements it and links to the page documenting that mechanism.
14+
15+
A principle that depends on an organizational decision rather than on a product feature is called out below its table.
16+
17+
## Findable
18+
19+
| Code | Principle | In Corporate Memory |
20+
| --- | --- | --- |
21+
| F1 | "(meta)data are assigned a globally unique and persistent identifier" | Every resource and every graph is identified by an IRI. Graph IRIs are derived from a selectable generation template - hostname and label, selected graph and label, UUID or a custom value. See [Cool IRIs](../../../build/cool-iris/index.md), [Define Prefixes / Namespaces](../../../build/define-prefixes-namespaces/index.md) and [Adding a new graph](../../../explore-and-author/graph-exploration/index.md#adding-a-new-graph). |
22+
| F2 | "data are described with rich metadata (defined by R1 below)" | Each graph type carries its own metadata form, shown on the Metadata view of the graph. The metadata is stored as RDF inside the graph and can be queried like any other data. See [Knowledge Graphs](../../../explore-and-author/graph-exploration/index.md#graphs). |
23+
| F3 | "metadata clearly and explicitly include the identifier of the data they describe" | Graph metadata is recorded as statements about the graph IRI itself, so the description and the described graph share one identifier. See [Knowledge Graphs](../../../explore-and-author/graph-exploration/index.md#graphs). |
24+
| F4 | "(meta)data are registered or indexed in a searchable resource" | The graph list, the navigation tree and the full-text search index the content of an instance. Queries are registered in the [Query module](../../../explore-and-author/query-module/index.md), distributable content in the [Marketplace](../../marketplace/index.md). See [Label Resolution and Full Text Search](../../../deploy-and-configure/configuration/label-resolution-and-full-text-search/index.md). |
25+
26+
!!! info "F4 beyond a single instance"
27+
28+
A Marketplace Server indexes packages, not datasets.
29+
Discovery of datasets across organizations requires a catalog that is set up as part of the solution, for example as a graph following a catalog vocabulary.
30+
31+
## Accessible
32+
33+
| Code | Principle | In Corporate Memory |
34+
| --- | --- | --- |
35+
| A1 | "(meta)data are retrievable by their identifier using a standardised communications protocol" | The SPARQL endpoint, the Graph Store API, the RDF resource API, the JSON-LD Frame API and the SQL endpoint retrieve data by its identifier. See [Explore backend APIs](../../../develop/dataplatform-apis/index.md) and [Consume](../../../consume/index.md). |
36+
| A1.1 | "the protocol is open, free, and universally implementable" | Access runs over SPARQL 1.1, the SPARQL Graph Store HTTP Protocol and HTTP content negotiation. These are W3C standards, so no proprietary client is required. See [Media Types](../../../develop/dataplatform-apis/index.md#media-types). |
37+
| A1.2 | "the protocol allows for an authentication and authorisation procedure, where necessary" | Authentication runs over OAuth 2.0 and OpenID Connect through [Keycloak](../../../deploy-and-configure/configuration/keycloak/index.md). [Access Conditions](../../../deploy-and-configure/configuration/access-conditions/index.md) grant access per graph, per action and through dynamic conditions. [Project Access Control](../../../build/project-access-control/index.md) restricts a Build project to selected user groups. |
38+
| A2 | "metadata are accessible, even when the data are no longer available" | Metadata is held in graphs and can be kept in a different graph from the data it describes, so removing the data graph leaves the description in place. This is a modelling decision taken when the solution is designed, not a setting. |
39+
40+
!!! info "A2 is a design decision"
41+
42+
Corporate Memory does not retain the description of a graph automatically once the graph is removed.
43+
Keeping metadata separate from the data it describes - for example in a dedicated catalog graph - is what makes A2 hold.
44+
45+
## Interoperable
46+
47+
| Code | Principle | In Corporate Memory |
48+
| --- | --- | --- |
49+
| I1 | "(meta)data use a formal, accessible, shared, and broadly applicable language for knowledge representation" | Data and metadata are RDF throughout. Ontologies are authored in RDFS and OWL in the [Business knowledge editor](../../../explore-and-author/bke-module/index.md), see [Visually authoring ontologies](../../../explore-and-author/bke-module/visually-authoring-ontologies/index.md). Taxonomies follow SKOS, see [Thesauri](../../../explore-and-author/thesauri-management/index.md). |
50+
| I2 | "(meta)data use vocabularies that follow FAIR principles" | Vocabularies and ontologies are installed as versioned [Marketplace Packages](../../marketplace/index.md) carrying a name, a description, an SPDX license, a version and their dependencies. `owl:imports` records which vocabularies a graph relies on, see [graph imports](../../../automate/cmemc-command-line-interface/command-reference/graph/imports/index.md). |
51+
| I3 | "(meta)data include qualified references to other (meta)data" | [Link rules](../../../explore-and-author/link-rules/index.md) and [Active learning](../../../build/active-learning/index.md) produce typed links between datasets instead of untyped matches. [Statement Annotations](../../../explore-and-author/graph-exploration/statement-annotations/index.md) qualify an individual statement, for example with its temporal validity or its origin. |
52+
53+
## Reusable
54+
55+
| Code | Principle | In Corporate Memory |
56+
| --- | --- | --- |
57+
| R1 | "(meta)data are richly described with a plurality of accurate and relevant attributes" | SHACL shape catalogs define which attributes a resource carries, and drive both the editing forms and the validation. See [Building a customized user interface](../../../explore-and-author/graph-exploration/building-a-customized-user-interface/index.md) and [graph validation](../../../automate/cmemc-command-line-interface/command-reference/graph/validation/index.md). Shapes can be derived from an existing graph with [Generate SHACL shapes](../../../build/reference/customtask/cmem_plugin_shapes-plugin_shapes-ShapesPlugin.md). |
58+
| R1.1 | "(meta)data are released with a clear and accessible data usage license" | A Marketplace Package declares an [SPDX license identifier](https://spdx.org/licenses/) in its manifest and cannot be published without one. The license is shown on the package card and on the details page, and packages can be filtered by it. See [Metadata](../../../develop/packages/development/index.md#metadata) and [License](../../marketplace/index.md#license). |
59+
| R1.2 | "(meta)data are associated with detailed provenance" | [Versioning of Graph Changes](../../../explore-and-author/graph-exploration/versioning-of-graph-changes/index.md) records editing activities in a separate Versioning Graph. [Statement Annotations](../../../explore-and-author/graph-exploration/statement-annotations/index.md) hold the origin of an individual statement. [Workflows](../../../build/workflows/index.md) document how a graph was produced, and a package changelog records what changed between versions. |
60+
| R1.3 | "(meta)data meet domain-relevant community standards" | Standard vocabularies are installed from the [Marketplace](../../marketplace/index.md). Conformance to the shapes of a standard is checked with [graph validation](../../../automate/cmemc-command-line-interface/command-reference/graph/validation/index.md) and with [Validate RDF triples](../../../build/reference/customtask/cmem_plugin_reason-plugin_validate-ValidatePlugin.md). |
61+
62+
!!! info "R1.1 applies to packages"
63+
64+
The license mechanism described here belongs to Marketplace Packages.
65+
A license statement on a graph that is not distributed as a package is part of the metadata model of that graph and is defined with the solution.

‎docs/distribution/index.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ icon: material/star
44
tags:
55
- Marketplace
66
- Package
7+
- KnowledgeGraph
78
hide:
89
- toc
910
---
@@ -13,7 +14,7 @@ hide:
1314

1415
# :material-star: Distribution
1516

16-
This section describes how ready-made eccenca Corporate Memory content is distributed, shared and reused - across projects, teams and Corporate Memory instances.
17+
This section describes how eccenca Corporate Memory content and data are distributed, shared and reused - across projects, teams, Corporate Memory instances and organizations.
1718

1819
Vocabularies / ontologies, taxonomies, data graphs, Build projects and query catalogs do not need to be moved around one by one.
1920
They are bundled into **Marketplace Packages**: single, versioned artifacts which are offered on a Marketplace Server and can be installed into your Corporate Memory instance with a few clicks.
@@ -28,6 +29,12 @@ They are bundled into **Marketplace Packages**: single, versioned artifacts whic
2829

2930
Discover ready-made ontologies, vocabularies, demo projects and complete solutions in the Marketplace module, and install, update or uninstall them in your Corporate Memory instance.
3031

32+
- :material-star-four-points-outline: [FAIR Data](fair-data/index.md)
33+
34+
---
35+
36+
Make data Findable, Accessible, Interoperable and Reusable: the fifteen FAIR principles mapped to the Corporate Memory mechanisms that implement them, and the six steps of FAIRification.
37+
3138
</div>
3239

3340
!!! info "Related sections"

‎nav.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -555,6 +555,12 @@ nav:
555555
- Distribution: distribution/index.md
556556
- Marketplace:
557557
- distribution/marketplace/index.md
558+
- FAIR Data:
559+
- FAIR Data: distribution/fair-data/index.md
560+
- FAIR Principles:
561+
- distribution/fair-data/principles/index.md
562+
- FAIRification:
563+
- distribution/fair-data/fairification/index.md
558564
- Deploy and Configure:
559565
- Deploy and Configure: deploy-and-configure/index.md
560566
- System Architecture:

0 commit comments

Comments
 (0)