From 0567b141622af588693d66a539c6f0ce89c8cab9 Mon Sep 17 00:00:00 2001
From: khatamirad <104424728+khatamirad@users.noreply.github.com>
Date: Fri, 10 Jul 2026 15:45:22 +0200
Subject: [PATCH 03/10] text updated
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
## Changes made
### 1. New opening paragraph added
**Original:** Page opened directly with the four-pillar technical summary table (twelve preparation methods, twenty-eight techniques, etc.)
**Revised:** A short plain-language opening paragraph added before everything else:
> "CoreMeta4Cat defines the minimum information that should be reported alongside catalysis research data, across four domains: Synthesis, Characterization, Reaction, and Simulation. This page gives you a structured overview of what the standard covers, how it is organized, and how the different parts connect."
**Reason:** A researcher clicking "Overview" expects to understand what the standard is before seeing how many preparation methods it covers. The original page led with counts and schema terms, which is the right content for developers but the wrong opening for a general audience.
### 2. Technical summary table moved
**Original:** The four-bullet technical summary (twelve preparation methods, twenty-eight techniques, eight reactor design types, four computational methods) appeared at the very top of the page.
**Revised:** This content is now absorbed into the four data class descriptions lower on the page, where each section naturally introduces its own counts and scope. The standalone table at the top is removed.
**Reason:** Leading with counts before context reads as inside knowledge. The same information is more useful and more readable when it appears inside the section it describes.
### 3. One sentence added to "What is CoreMeta4Cat?"
**Original:** The section described the technical implementation (LinkML, DCAT-AP-PLUS, generated artefacts) without saying what this means practically for a researcher.
**Revised:** One sentence added at the end of the section:
> "In practical terms: a dataset described with CoreMeta4Cat is not just a well-labelled spreadsheet. It is a structured, machine-readable record that can be validated, searched, and connected to other datasets across repositories — because every field links back to a shared scientific vocabulary."
**Reason:** Consistent with the sentence added to the Home page intro — surfaces the semantic/knowledge graph benefit in plain language before the reader encounters the technical explanation.
### 4. "Pillars" → "data classes" throughout
**Original:** The four domains were consistently called "pillars" on this page.
**Revised:** Changed to "data classes" throughout — section heading changed from "The four CoreMeta4Cat pillars" to "The four data classes."
**Reason:** "Data class" is the term used in the schema, the Excel workbook, the README, and the Home page. "Pillar" is an informal internal term that doesn't appear elsewhere in the documentation. Using consistent terminology reduces confusion for anyone reading across multiple pages.
### 5. Source code link corrected
**Original:** `[HendrikBorgelt/CoreMeta4Cat](https://github.com/nfdi4cat/CoreMeta4Cat)` — the link text named a personal fork while the URL correctly pointed to the official repo.
**Revised:** `[nfdi4cat/CoreMeta4Cat](https://github.com/nfdi4cat/CoreMeta4Cat)` — link text corrected to match the URL.
**Reason:** A visitor reading "HendrikBorgelt/CoreMeta4Cat" would reasonably assume the project is maintained by an individual rather than the NFDI4Cat organization — which is both factually incorrect and potentially off-putting for institutions evaluating adoption.
### 6. "Source code" section renamed to "Further reading"
**Original:** Final section was titled "Source code" and mixed the GitHub link with the documentation table.
**Revised:** Renamed to "Further reading" — table retained, GitHub link moved to a separate line below the table.
**Reason:** "Source code" as a section heading implies the page is for developers. "Further reading" is more neutral and welcoming to all audiences.
---
docs/overview.md | 183 +++++++++++++++++++----------------------------
1 file changed, 73 insertions(+), 110 deletions(-)
diff --git a/docs/overview.md b/docs/overview.md
index 26e642ddb..afc1b0f38 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -1,72 +1,16 @@
----
-title: CoreMeta4Cat
-description: Comprehensive Metadata Guidelines for Catalysis Research Data
----
-
-# CoreMeta4Cat — Comprehensive Metadata Guidelines for Catalysis Research Data
-
-
-
-- :material-flask-outline: **Synthesis**
-
- Twelve preparation methods with method-specific parameter sets, shared mixin classes for drying and calcination steps.
-
-- :material-microscope: **Characterization**
+# CoreMeta4Cat — Overview
- Twenty-eight analytical techniques, from Powder XRD to Cyclic Voltammetry, each with dedicated measurement slots.
-
-- :material-thermometer: **Reaction**
-
- Eight reactor design types, flattened operation parameter slots, and product identification links.
-
-- :octicons-cpu-16: **Simulation**
-
- Four computational methods (DFT, MD, Microkinetics, Monte Carlo) with 12 calculated property classes.
-
-
+CoreMeta4Cat defines the minimum information that should be reported alongside catalysis research data, across four domains: Synthesis, Characterization, Reaction, and Simulation. This page gives you a structured overview of what the standard covers, how it is organized, and how the different parts connect.
---
## What is CoreMeta4Cat?
-CoreMeta4Cat is a [LinkML](https://linkml.io/)-based metadata reference model for catalysis research data, developed within the [NFDI4Cat](https://nfdi4cat.org) initiative. It defines the **minimum information** that should be reported alongside research data in the field of catalysis, following the FAIR principles (Findable, Accessible, Interoperable, Reusable).
-
-CoreMeta4Cat is built as a domain-specific application profile on top of [DCAT-AP-PLUS](https://nfdi-de.github.io/dcat-ap-plus/dev/), a provenance-aware extension of the DCAT Application Profile 3.0. This means every CoreMeta4Cat dataset is a valid `dcat:Dataset`, every activity is a valid `prov:Activity`, and all schema artefacts — SHACL shapes, JSON Schema, Python/Pydantic classes, HTML reference documentation — are generated automatically from the single LinkML source.
-
----
-
-## Quick Start: What does CoreMeta4Cat add?
-
-In plain DCAT-AP, a `Dataset` can describe what data exists but says little about *how* it was produced or *what material* it concerns. DCAT-AP-PLUS adds a structured provenance graph via `prov:wasGeneratedBy`. CoreMeta4Cat specialises that graph for catalysis:
-
-```yaml
-# A dataset about the CO oxidation performance of a supported Pt catalyst
-id: ex:dataset-001
-title: "CO oxidation activity of 1wt% Pt/Al2O3 at 200–400°C"
-rdf_type:
- id: voc4cat:0007001
- title: "heterogeneous catalysis"
-
-was_generated_by:
- - id: ex:reaction-001
- type: Reaction
- catalyst_quantity: 100.0 # mg
- reactant:
- - "1 vol% CO in N2"
- - "2 vol% O2 in N2"
- reactor_temperature_range: "200–400 °C"
- experiment_pressure: 1.0 # bar
- carried_out_by:
- id: ex:reactor-001
- type: FixedBedReactor
+CoreMeta4Cat is a metadata standard for catalysis research data, developed within the [NFDI4Cat](https://nfdi4cat.org) initiative. It is implemented as a [LinkML](https://linkml.io/) schema — a format that allows the standard to automatically generate multiple useful outputs from a single source: an Excel reference workbook, a JSON Schema for validation, Python data classes, and a full RDF/OWL representation for semantic querying.
-is_about_entity:
- - id: ex:catalyst-001
- type: CatalystSample
- nominal_composition: "1wt% Pt/Al2O3"
-```
+CoreMeta4Cat is built as a domain-specific application profile on top of [DCAT-AP-PLUS](https://nfdi-de.github.io/dcat-ap-plus/dev/), a provenance-aware extension of the DCAT Application Profile 3.0. This means every CoreMeta4Cat dataset is a valid `dcat:Dataset`, every activity is a valid `prov:Activity`, and all schema artefacts are generated automatically from the single LinkML source.
-This is valid CoreMeta4Cat instance data. Every class and property is mapped to a controlled ontology term (voc4cat, CHMO, OBI, …) and can be validated and converted to RDF using standard LinkML tooling.
+In practical terms: a dataset described with CoreMeta4Cat is not just a well-labelled spreadsheet. It is a structured, machine-readable record that can be validated, searched, and connected to other datasets across repositories — because every field links back to a shared scientific vocabulary.
---
@@ -74,88 +18,107 @@ This is valid CoreMeta4Cat instance data. Every class and property is mapped to
CoreMeta4Cat organises metadata in two layers.
-**Layer 1 — Global classification** is data-class-independent. It applies to every `CatalysisDataset` and captures the two fields needed for the coarsest-possible filtering of a repository:
+**Layer 1 — Global classification** applies to every catalysis dataset, regardless of data class. It captures the two fields needed for the coarsest-possible filtering across a repository:
| Field | Example values | Obligation |
|---|---|---|
-| Catalysis research field (`rdf_type`) | heterogeneous catalysis, electrocatalysis, biocatalysis | Recommended |
-| Reaction type (`rdf_type` on `Reaction`) | CO oxidation, ammonia synthesis, hydrogenation | Recommended |
+| Catalysis research field | heterogeneous catalysis, electrocatalysis, biocatalysis | Recommended |
+| Reaction type | CO oxidation, ammonia synthesis, hydrogenation | Recommended |
-**Layer 2 — Data-class-specific metadata** is structured around the four *pillars*: Synthesis, Characterization, Reaction, and Simulation. Each pillar maps to a DCAT-AP-PLUS Activity subclass and carries its own set of Mandatory, Recommended, and Optional fields.
+**Layer 2 — Data-class-specific metadata** is structured around the four data classes: Synthesis, Characterization, Reaction, and Simulation. Each data class carries its own set of Mandatory, Recommended, and Optional fields.
```
-CatalysisDataset (dcat:Dataset)
- ├── rdf_type → CatalysisResearchFieldEnum [Layer 1]
- ├── was_generated_by → Synthesis [Layer 2]
- ├── was_generated_by → Characterization [Layer 2]
- ├── was_generated_by → Simulation [Layer 2]
- └── is_about_activity → Reaction [Layer 2]
+CatalysisDataset
+ ├── catalysis research field [Layer 1 — applies to all]
+ ├── reaction type [Layer 1 — applies to all]
+ ├── was_generated_by → Synthesis [Layer 2 — data-class specific]
+ ├── was_generated_by → Characterization
+ ├── was_generated_by → Simulation
+ └── is_about_activity → Reaction
```
---
-## The four CoreMeta4Cat pillars
+## The four data classes
### Synthesis
-Reproducibility of catalyst synthesis is one of the most persistent challenges in catalysis research. The **Synthesis** pillar defines the minimum metadata for twelve preparation methods, from common routes such as Impregnation and Co-Precipitation to more specialised techniques like Atomic Layer Deposition, Flame Spray Pyrolysis, and Exsolution Synthesis.
+Reproducibility of catalyst synthesis is one of the most persistent challenges in catalysis research. The Synthesis data class defines the minimum metadata for twelve preparation methods — from common routes such as Impregnation and Co-Precipitation to more specialised techniques like Atomic Layer Deposition, Flame Spray Pyrolysis, and Exsolution Synthesis.
-Method-specific parameter sets are organised into concrete `PreparationMethod` subclasses. Cross-cutting slot groups (drying step, calcination step, precipitation step, thermal process) are factored out as **mixin classes**, so parameters shared by multiple methods are defined exactly once.
+Method-specific parameter sets are organized into concrete preparation method types. Cross-cutting steps shared across methods (drying, calcination, precipitation) are defined once and reused, so the same parameter is never described differently depending on which method it appears in.
-| Class | Key mixins applied |
+| Preparation method | Key shared steps |
|---|---|
-| `Impregnation` | `DryingMixin`, `CalcinationMixin` |
-| `CoPrecipitation` | `PrecipitationMixin`, `DryingMixin`, `CalcinationMixin` |
-| `DepositionPrecipitation` | `PrecipitationMixin`, `DryingMixin`, `CalcinationMixin` |
-| `Solvothermal`, `PlasmaAssisted`, `CombustionSynthesis`, `MicrowaveAssisted`, `MechanochemicalSynthesis`, `Sublimation` | `ThermalSynthesisMixin` |
-| `SonochemicalSynthesis`, `MolecularSynthesis` | `DryingMixin` / `CalcinationMixin` |
-| `AtomicLayerDeposition`, `SolGel`, `FlameSprayPyrolysis`, `ExsolutionSynthesis` | method-specific slots only |
+| Impregnation | Drying, Calcination |
+| Co-Precipitation | Precipitation, Drying, Calcination |
+| Deposition-Precipitation | Precipitation, Drying, Calcination |
+| Solvothermal, Plasma-Assisted, Combustion, Microwave-Assisted, Mechanochemical, Sublimation | Thermal process |
+| Sol-Gel, Flame Spray Pyrolysis, Atomic Layer Deposition, Exsolution | Method-specific only |
### Characterization
-The **Characterization** pillar covers twenty-eight analytical techniques currently used in catalysis. Each technique is modelled as a concrete `CharacterizationTechnique` subclass (a DCAT-AP-PLUS `Plan`), with slots for instrument parameters, sample state, and measurement conditions. Cross-cutting parameter groups are again factored out as mixins:
+The Characterization data class covers twenty-eight analytical techniques currently used in catalysis. Each technique is modelled with slots for instrument parameters, sample state, and measurement conditions. Cross-cutting parameter groups are shared across related techniques:
-- `XRaySourceMixin` — shared by PowderXRD, SingleCrystalXRD, XPS, EDX
-- `ElectronMicroscopyMixin` — shared by TEM, SEM
-- `TemperatureProgramMixin` — shared by TPR, TPO, Thermogravimetry
-- `ChromatographyMixin`, `MassRangeMixin` — shared by GC, GC-MS, HPLC, HPLC-MS
+- X-ray source parameters — shared by Powder XRD, Single Crystal XRD, XPS, EDX
+- Electron microscopy parameters — shared by TEM, SEM
+- Temperature program parameters — shared by TPR, TPO, Thermogravimetry
+- Chromatography and mass range parameters — shared by GC, GC-MS, HPLC, HPLC-MS
### Reaction
-The **Reaction** pillar represents the catalytic process being studied. It is modelled as a DCAT-AP-PLUS `EvaluatedActivity` — the process the dataset is *about*, not the process that *generates* the data. This distinction matters: for operando experiments (e.g. in-situ XRD during a reaction), the dataset carries both `was_generated_by: Characterization` and `is_about_activity: Reaction`.
+The Reaction data class represents the catalytic process being studied. An important design detail: for operando experiments — for example, in-situ XRD carried out while a reaction is running — the dataset carries both a Characterization record (the process that generated the data) and a Reaction record (the process the data is about). CoreMeta4Cat models both links explicitly.
-The reactor is linked via `carried_out_by` as one of eight `ReactorDesignType` subclasses:
+Eight reactor design types are currently defined:
-
+- Electrochemical Reactor
+- CSTR (Continuous Stirred Tank Reactor)
+- Plug Flow Reactor
+- Autoclave
+- Slurry Reactor
+- Microreactor
+- Fixed Bed Reactor
+- Fluidized Bed Reactor
-- `ElectrochemicalReactor`
-- `CSTR`
-- `PlugFlowReactor`
-- `Autoclave`
-- `SlurryReactor`
-- `Microreactor`
-- `FixedBedReactor`
-- `FluidizedBedReactor`
+### Simulation
-
+The Simulation data class covers four major computational method classes: DFT, Molecular Dynamics, Microkinetics, and Monte Carlo. The simulation software used is recorded alongside the method. Twelve calculated property types — such as electronic structure, band gap, phonon dispersion, and thermodynamic stability — capture the computed output.
-### Simulation
+---
+
+## What does a CoreMeta4Cat record look like?
-The **Simulation** pillar covers four major computational method classes, each a `SimulationMethod` subclass (DCAT-AP-PLUS `Plan`): **DFT**, **MolecularDynamics**, **Microkinetics**, and **MonteCarlo**. The simulation software is linked via `carried_out_by` as a `Software` agent. Twelve `CalculatedProperty` classes (e.g. `ElectronicStructure`, `BandGap`, `PhononDispersion`, `ThermodynamicStability`) capture the computed output type.
+Here is a minimal example showing how a reaction dataset is described. Every class and property links to a controlled vocabulary term and can be validated and converted to RDF using standard tooling:
+
+```yaml
+id: ex:dataset-001
+title: "CO oxidation activity of 1wt% Pt/Al2O3 at 200–400°C"
+catalysis_research_field: heterogeneous catalysis
+
+was_generated_by:
+ - type: Reaction
+ catalyst_quantity: 100.0 # mg
+ reactant:
+ - "1 vol% CO in N2"
+ - "2 vol% O2 in N2"
+ reactor_temperature_range: "200–400 °C"
+ experiment_pressure: 1.0 # bar
+ carried_out_by:
+ type: FixedBedReactor
+
+is_about_entity:
+ - type: CatalystSample
+ nominal_composition: "1wt% Pt/Al2O3"
+```
---
-## Documentation
+## Further reading
| Page | What it covers |
|---|---|
-| [Design Patterns](design-patterns.md) | How the four pillars map to DCAT-AP-PLUS, the mixin pattern, ontology alignment |
-| [How to Extend](how-to-extend.md) | Rules for adding new preparation methods, techniques, reactor types, and properties |
-| [Schema Reference](elements/overview.md) | Auto-generated reference for all classes and slots |
-| [CoreMeta4Cat Users](coremeta4cat-users.md) | Projects and repositories that adopt CoreMeta4Cat |
-
-## Source code
-
-The LinkML schema, build scripts, and documentation source are on GitHub: [HendrikBorgelt/CoreMeta4Cat](https://github.com/nfdi4cat/CoreMeta4Cat)
+| [Design Patterns](https://nfdi4cat.github.io/CoreMeta4Cat/latest/design-patterns/) | How the four data classes map to DCAT-AP-PLUS, the mixin pattern, ontology alignment |
+| [How to Extend](https://nfdi4cat.github.io/CoreMeta4Cat/latest/how-to-extend/) | Rules for adding new preparation methods, techniques, reactor types, and properties |
+| [Schema Reference](https://nfdi4cat.github.io/CoreMeta4Cat/latest/elements/overview/) | Auto-generated reference for all classes and slots |
+| [Intended Users](https://nfdi4cat.github.io/CoreMeta4Cat/latest/coremeta4cat-users/) | Projects and repositories that adopt CoreMeta4Cat |
-The schema is built as a domain-specific application profile on top of DCAT-AP-PLUS. The base layer is maintained by [NFDI4Cat](https://nfdi4cat.org).
+The LinkML schema, build scripts, and documentation source are on GitHub: [nfdi4cat/CoreMeta4Cat](https://github.com/nfdi4cat/CoreMeta4Cat)
From 89c1adc0d094d04dea16f962938e80458b4cb585 Mon Sep 17 00:00:00 2001
From: khatamirad <104424728+khatamirad@users.noreply.github.com>
Date: Fri, 10 Jul 2026 16:14:56 +0200
Subject: [PATCH 04/10] design pattern text updated
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
## Changes made
### 1. "Pillars" → "data classes" throughout
**Original:** The page consistently used "the four pillars" — section heading "The four pillars", references throughout to "the four pillars", Pattern 4 referring to "pillars".
**Revised:** Changed to "the four data classes" throughout. Section heading changed from "The four pillars" to "The four data classes".
**Reason:** Consistent with the terminology change applied to the Overview page and used throughout the README and Home page. "Data class" is the term used in the schema itself; "pillar" is informal and doesn't appear in the schema source.
### 2. GitHub link corrected
**Original:** Header GitHub link pointed to `https://github.com/HendrikBorgelt/CoreMeta4Cat` (personal fork).
**Revised:** Corrected to `https://github.com/nfdi4cat/CoreMeta4Cat` (official repository).
**Reason:** Same issue as Getting Started and Overview pages — same root cause, same fix. Worth noting this link appears in the MkDocs configuration (`mkdocs.yml`) rather than in the page source, so it may need to be fixed at the config level rather than per-page. Flag to co-developers.
### 3. Code block language tags added
**Original:** All YAML code blocks were plain fenced blocks with no language specifier.
**Revised:** All YAML blocks tagged as ` ```yaml `, the import hierarchy block tagged as plain ` ``` ` (since it's a diagram, not valid YAML).
**Reason:** MkDocs Material renders syntax highlighting when a language tag is present. No content changed.
### 4. Pattern summary blocks — tag changed for clarity
**Original:** Pattern summaries used a plain `??? abstract` collapsible block with the label "Pattern summary".
**Revised:** Retained as-is for Patterns 1, 2, 3, and 4. The Deep dive warning block retained as `??? warning`.
**Reason:** No change needed — the collapsible pattern summary blocks are well-designed and should stay exactly as they are.
### 5. Operando experiments callout — formatting made consistent
**Original:** The operando experiments note under Reaction appeared as a plain indented block.
**Revised:** Converted to a `??? info "Operando experiments"` collapsible block, consistent with the pattern summary blocks used elsewhere on the same page.
**Reason:** Visual consistency within the page — the operando note is supplementary detail, the same role the pattern summaries play.
---
docs/design_patterns.md | 358 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 358 insertions(+)
create mode 100644 docs/design_patterns.md
diff --git a/docs/design_patterns.md b/docs/design_patterns.md
new file mode 100644
index 000000000..5279da497
--- /dev/null
+++ b/docs/design_patterns.md
@@ -0,0 +1,358 @@
+# Design Patterns
+
+This page explains the key structural decisions behind CoreMeta4Cat — how the four data classes are modelled, how they connect to a dataset, and what design patterns make the schema extensible and machine-actionable.
+
+
+
+---
+
+## Reading guide
+
+This page is written in three tiers. Most users only need the first two.
+
+| Tier | Who it's for | Sections |
+|---|---|---|
+| **Overview** | Everyone — data providers, repository managers | [The entry point](#the-entry-point-catalysisdataset), [The four data classes](#the-four-data-classes) |
+| **Pattern explanations** | Users who want to understand how to navigate or extend the schema | [Classification pattern](#pattern-1-classification-via-rdf_type), [Activity pattern](#pattern-2-activities-and-plans), [Mixin pattern](#pattern-3-mixin-classes) |
+| **Technical depth** | Schema developers and DCAT-AP-PLUS integrators | [Sections marked with 🔬](#deep-dive-the-evaluatedactivity-distinction) |
+
+---
+
+## The entry point: CatalysisDataset
+
+Every CoreMeta4Cat record starts with a **`CatalysisDataset`**. This is a `dcat:Dataset` — fully compatible with plain DCAT and DCAT-AP — extended with four additional link slots that connect to the four CoreMeta4Cat data classes.
+
+```yaml
+id: ex:dataset-001
+type: CatalysisDataset # → dcat:Dataset
+
+# Layer 1: global classification
+rdf_type:
+ id: voc4cat:0007001
+ title: "heterogeneous catalysis"
+
+# Layer 2: links to the four data classes
+was_generated_by:
+ - id: ex:synthesis-001
+ type: Synthesis
+ - id: ex:characterization-001
+ type: Characterization
+
+is_about_activity:
+ - id: ex:reaction-001
+ type: Reaction
+
+is_about_entity:
+ - id: ex:catalyst-001
+ type: CatalystSample
+```
+
+The key points here are:
+
+- `rdf_type` carries a **controlled vocabulary term** from [Voc4Cat](https://nfdi4cat.github.io/voc4cat/) to classify which field of catalysis the dataset belongs to.
+- `was_generated_by` links to **activities that produced the data** (Synthesis, Characterization, Simulation).
+- `is_about_activity` links to the **Reaction being studied** — which is the catalytic process itself, not a data-generating step.
+- `is_about_entity` links to the **catalyst sample or material** the dataset concerns.
+
+---
+
+## The four data classes
+
+The four CoreMeta4Cat data classes — **Synthesis**, **Characterization**, **Reaction**, and **Simulation** — are the core of the metadata model. Each is a separate class, defined in its own subprofile module, and linked from the `CatalysisDataset` via the slots above.
+
+```
+catcore.yaml (aggregator + CatalysisDataset)
+ ├── catcore_common.yaml (shared slots and enumerations)
+ ├── catcore_synthesis_ap.yaml (Synthesis + 12 preparation methods)
+ ├── catcore_characterization_ap.yaml (Characterization + 28 techniques)
+ ├── catcore_reaction_ap.yaml (Reaction + 8 reactor types)
+ └── catcore_simulation_ap.yaml (Simulation + 4 methods + 12 properties)
+```
+
+### Synthesis
+
+**What it is:** The process of preparing a catalyst. Synthesis is a `DataGeneratingActivity` — it produces data *about* the preparation, and it produces a `CatalystSample` as its physical output.
+
+**Key links:**
+
+- `realized_plan` → a `PreparationMethod` subclass (the protocol used)
+- `had_input_entity` → `Precursor` instances (the starting materials)
+- `had_output_entity` → `CatalystSample` (the resulting catalyst)
+
+Twelve preparation methods are currently defined, each as a concrete `PreparationMethod` subclass:
+
+- **Wet chemistry:** Impregnation, Co-Precipitation, Deposition-Precipitation, Sol-Gel, Molecular Synthesis
+- **Thermal / gas-phase:** Solvothermal, Combustion Synthesis, Flame Spray Pyrolysis, Sublimation, Plasma-Assisted
+- **Mechanical / energy-assisted:** Mechanochemical Synthesis, Microwave-Assisted, Sonochemical Synthesis
+- **Surface / thin-film:** Atomic Layer Deposition, Exsolution Synthesis
+
+### Characterization
+
+**What it is:** The measurement of a catalyst or catalytic system using an analytical technique. Characterization is also a `DataGeneratingActivity` — it produces measurement data.
+
+**Key links:**
+
+- `evaluated_entity` → the `CatalystSample` or material being measured
+- `realized_plan` → a `CharacterizationTechnique` subclass (the measurement protocol)
+- `carried_out_by` → the instrument (`Device`) performing the measurement
+
+Twenty-eight techniques are currently defined, organised into groups:
+
+| Group | Techniques |
+|---|---|
+| Diffraction | Powder XRD, Single Crystal XRD |
+| X-ray spectroscopy | XAS/XANES/EXAFS, XPS, EDX |
+| Vibrational spectroscopy | FTIR, DRIFTS, Raman, NMR |
+| Electron microscopy | TEM, SEM |
+| Thermal analysis | TGA, TPR, TPO |
+| Surface & pore analysis | BET |
+| Elemental analysis | ICP-AES, Elemental Analysis (CHNS) |
+| Optical & electronic | UV-Vis, Photoluminescence, Photoluminescence Lifetime |
+| Electrochemistry | Cyclic Voltammetry, Conductivity Measurement |
+| Particle sizing | Dynamic Light Scattering |
+| Mass spectrometry | ESI-MS, GC-MS, HPLC-MS |
+| Chromatography | GC, HPLC |
+
+### Reaction
+
+**What it is:** The catalytic reaction being studied. Unlike Synthesis and Characterization, Reaction is **not** a `DataGeneratingActivity`. It is the process being *observed*, not the process generating the dataset.
+
+**Key links:**
+
+- `carried_out_by` → a `ReactorDesignType` (the physical reactor)
+- `had_input_entity` → reactant feeds
+- `product_identification_method` → a `CharacterizationTechnique` used for product analysis
+
+Eight reactor design types are defined:
+`FixedBedReactor` · `CSTR` · `PlugFlowReactor` · `Autoclave` · `SlurryReactor` · `Microreactor` · `ElectrochemicalReactor` · `FluidizedBedReactor`
+
+??? info "Operando experiments"
+ For in-situ or operando experiments (e.g. XRD measured while a reaction runs), the dataset carries **both** links simultaneously:
+ ```yaml
+ was_generated_by:
+ - type: Characterization # PowderXRD — the process that made the data
+ is_about_activity:
+ - type: Reaction # the catalytic process being monitored
+ ```
+
+### Simulation
+
+**What it is:** A computational study of a catalyst or catalytic mechanism. Simulation is a `DataGeneratingActivity` — it generates data computationally.
+
+**Key links:**
+
+- `realized_plan` → a `SimulationMethod` subclass (DFT, MD, Microkinetics, MonteCarlo)
+- `carried_out_by` → a `Software` agent (the simulation package)
+- `evaluated_entity` → the catalyst model or structure being simulated
+
+Twelve calculated property classes capture the type of computed output: `ElectronicStructure`, `BandGap`, `ThermodynamicStability`, `PhononDispersion`, `Surfaces`, `GrainBoundaries`, `ElasticConstants`, `DielectricTensors`, `EquationsOfState`, `AqueousStability`, `Piezoelectricity`, `Ferroelectrics`.
+
+---
+
+## Pattern 1: Classification via rdf\_type
+
+??? abstract "Pattern summary"
+ Flexible, machine-actionable classification of datasets, activities, and entities using ontology terms — without creating a separate class for every possible value.
+
+Rather than defining a fixed class hierarchy for every type of catalysis or every synthesis method, CoreMeta4Cat uses a single `rdf_type` slot on each class to carry a controlled vocabulary term from Voc4Cat, CHMO, or another ontology. This keeps the schema compact while staying fully machine-actionable.
+
+**On CatalysisDataset** — classify the catalysis research field:
+
+```yaml
+rdf_type:
+ id: voc4cat:0007001
+ title: "heterogeneous catalysis"
+```
+
+**On Synthesis** — classify the preparation method type:
+
+```yaml
+type: Synthesis
+rdf_type:
+ id: voc4cat:0007016
+ title: "impregnation"
+realized_plan:
+ type: Impregnation # the concrete method class with all parameter slots
+```
+
+**On Characterization** — classify the measurement technique:
+
+```yaml
+type: Characterization
+rdf_type:
+ id: CHMO:0000158
+ title: "powder X-ray diffraction"
+realized_plan:
+ type: PowderXRD # the concrete technique class with all measurement slots
+```
+
+The `rdf_type` slot gives the machine-readable ontology term; the concrete subclass (`Impregnation`, `PowderXRD`, …) provides the structured parameter slots. Both are used together.
+
+The allowed values for `rdf_type` on `CatalysisDataset` are defined in `CatalysisResearchFieldEnum`:
+
+| Value | Ontology term | Description |
+|---|---|---|
+| `heterogeneous_catalysis` | `voc4cat:0007001` | Catalyst and reactants in different phases |
+| `homogeneous_catalysis` | `voc4cat:0000294` | Catalyst and reactants in the same phase |
+| `electrocatalysis` | `voc4cat:0000216` | Catalysis of electrochemical reactions |
+| `biocatalysis` | `voc4cat:0000204` | Enzyme or whole-cell catalysis |
+| `hybrid_catalysis` | *(pending)* | Combination of two or more approaches |
+| `other` | — | Fallback for unlisted fields |
+
+---
+
+## Pattern 2: Activities and Plans
+
+??? abstract "Pattern summary"
+ A two-part structure separates *what was done* (the Activity) from *the protocol describing how to do it* (the Plan). This mirrors the PROV-O model and keeps the schema clean.
+
+Each data class that generates data follows this two-part structure:
+
+```
+Activity (what was done) Plan (the protocol)
+───────────────────────── ───────────────────────────
+Synthesis ──→ PreparationMethod
+Characterization ──→ CharacterizationTechnique
+Simulation ──→ SimulationMethod
+```
+
+The Activity carries the **instance-level data** (who did it, when, on what sample, with what output). The Plan carries the **method-level data** (parameter settings, instrument configuration, protocol steps).
+
+```yaml
+# The activity — what happened
+id: ex:synthesis-001
+type: Synthesis
+nominal_composition: "5wt% Ni/Al2O3"
+had_input_entity:
+ - id: ex:precursor-001
+ type: Precursor
+ name: "Ni(NO3)2·6H2O"
+ precursor_quantity: 1.24 # g
+had_output_entity:
+ - id: ex:catalyst-001
+ type: CatalystSample
+
+# The plan — the protocol
+realized_plan:
+ id: ex:method-001
+ type: Impregnation
+ impregnation_type: incipient_wetness
+ impregnation_duration: 12.0 # h
+ drying_temperature: 120.0 # °C
+ drying_time: 12.0 # h
+ calcination_final_temperature: 500.0 # °C
+ calcination_dwelling_time: 4.0 # h
+ calcination_gaseous_environment: "air"
+```
+
+This separation means a single `PreparationMethod` record could in principle be shared across multiple `Synthesis` activities — a direct gain for reproducibility.
+
+---
+
+## Pattern 3: Mixin classes
+
+??? abstract "Pattern summary"
+ Slot groups that are shared across multiple methods are factored into reusable mixin classes, so each slot is defined exactly once and inherited wherever needed.
+
+Many preparation methods share common process steps — drying, calcination, precipitation. Rather than repeating the same slots in every method class, CoreMeta4Cat uses **mixin classes** that bundle related slots:
+
+| Mixin | Slots it provides | Used by |
+|---|---|---|
+| `DryingMixin` | `drying_device`, `drying_temperature`, `drying_time`, `drying_atmosphere` | Impregnation, CoPrecipitation, DepositionPrecipitation, SonochemicalSynthesis, MolecularSynthesis |
+| `CalcinationMixin` | `calcination_initial_temperature`, `calcination_final_temperature`, `calcination_dwelling_time`, `calcination_heating_rate`, `calcination_gaseous_environment`, `calcination_gas_flow_rate`, `number_of_cycles` | Impregnation, CoPrecipitation, DepositionPrecipitation, SonochemicalSynthesis, ExsolutionSynthesis |
+| `PrecipitationMixin` | `precipitating_agent`, `synthesis_ph`, `mixing_rate`, `mixing_time`, `mixing_temperature`, `order_of_addition`, `aging_temperature`, `aging_time` | CoPrecipitation, DepositionPrecipitation |
+| `ThermalSynthesisMixin` | `synthesis_temperature`, `synthesis_duration`, `equipment`, `vessel_type`, `atmosphere` | Solvothermal, PlasmaAssisted, CombustionSynthesis, MicrowaveAssisted, MechanochemicalSynthesis, Sublimation |
+
+The same pattern is used in the Characterization subprofile for analytical techniques:
+
+| Mixin | Used by |
+|---|---|
+| `XRaySourceMixin` | PowderXRD, SingleCrystalXRD, XPS, EDX |
+| `ElectronMicroscopyMixin` | TEM, SEM |
+| `TemperatureProgramMixin` | TPR, TPO, Thermogravimetry |
+| `ChromatographyMixin` | GC, HPLC, GC-MS, HPLC-MS |
+| `MassRangeMixin` | GC-MS, HPLC-MS, ESI-MS |
+| `ElectrochemistryMixin` | CyclicVoltammetry, ConductivityMeasurement |
+
+In LinkML, a mixin class has no `class_uri` of its own and generates no independent node shape. It is a pure slot container, mixed in via the `mixins:` key on a concrete class.
+
+---
+
+## Pattern 4: Shared slots in catcore\_common
+
+??? abstract "Pattern summary"
+ Slots referenced by two or more subprofiles are declared once in `catcore_common.yaml` and imported by all subprofiles. This keeps the schema DRY (Don't Repeat Yourself).
+
+Some slots appear in multiple data classes — for example, `temperature` is relevant to Synthesis (calcination), Characterization (temperature-programmed experiments), and Reaction (reactor temperature). These shared slots live in `catcore_common.yaml`:
+
+```yaml
+# catcore_common.yaml — shared slots include:
+atmosphere, temperature, flow_rate, heating_rate,
+equipment, sample_mass, stirring_speed, stirring_duration,
+drying_*, calcination_*, concentration, solvent,
+experiment_duration, step_size, resolution, ...
+```
+
+Slots that are exclusive to a single subprofile are declared in that subprofile file only.
+
+---
+
+## 🔬 Deep dive: The EvaluatedActivity distinction
+
+??? warning "Technical section"
+ This section is intended for schema developers and DCAT-AP-PLUS integrators. It is not required reading for data providers.
+
+One of the most important architectural decisions in CoreMeta4Cat is that **Reaction is not a `DataGeneratingActivity`**. Instead it is an `EvaluatedActivity`.
+
+In DCAT-AP-PLUS, the distinction is:
+
+| Class | Meaning | Links to dataset via |
+|---|---|---|
+| `DataGeneratingActivity` | A process that produces the data in the dataset | `prov:wasGeneratedBy` |
+| `EvaluatedActivity` | A process that the dataset is *about*, but which did not produce it | `is_about_activity` |
+
+For catalysis, a `Reaction` is the catalytic process being studied. The data is generated by *measuring* that reaction — via a `Characterization` activity. The `Reaction` itself does not produce the data file.
+
+This distinction enables operando experiments to be described correctly:
+
+```yaml
+# Operando XRD during CO oxidation
+was_generated_by:
+ - type: Characterization # PowderXRD run — this produced the data
+ rdf_type:
+ id: CHMO:0000158
+ title: "powder X-ray diffraction"
+
+is_about_activity:
+ - type: Reaction # the CO oxidation reaction being monitored
+ catalyst_quantity: 50.0
+ reactant: ["1 vol% CO", "2 vol% O2"]
+ carried_out_by:
+ type: FixedBedReactor
+```
+
+If `Reaction` were modelled as a `DataGeneratingActivity`, this relationship would collapse: it would be impossible to distinguish the measurement from the catalytic process it monitors.
+
+The same distinction appears in DCAT-AP-PLUS itself — the NMR example in the base documentation uses `was_generated_by: NMRSpectroscopy` (the measurement) and `evaluated_entity: MaterialSample` (the thing measured). CoreMeta4Cat extends this by adding `is_about_activity: Reaction` for cases where a process — not just a material — is being monitored.
+
+---
+
+## Import hierarchy
+
+The full import chain, from the CoreMeta4Cat top level down to the DCAT-AP-PLUS base, is:
+
+```
+catcore.yaml
+ └── catcore_common.yaml
+ └── chem_dcat_ap
+ └── chemical_reaction_ap
+ └── chemical_entities_ap
+ └── material_entities_ap
+ └── dcat_ap_plus ← DCAT-AP-PLUS base
+ ├── catcore_synthesis_ap.yaml
+ ├── catcore_characterization_ap.yaml
+ ├── catcore_reaction_ap.yaml
+ └── catcore_simulation_ap.yaml
+```
+
+Each layer adds domain-specific classes and slots on top of the layer below, without modifying it. This means CoreMeta4Cat datasets remain valid DCAT-AP-PLUS instances, which in turn remain valid DCAT-AP datasets.
From b0dbdc8aafd23222f38a30ac70d620138191fa2c Mon Sep 17 00:00:00 2001
From: khatamirad <104424728+khatamirad@users.noreply.github.com>
Date: Fri, 10 Jul 2026 16:18:08 +0200
Subject: [PATCH 05/10] Delete docs/design-patterns.md
Another .md file was uploaded, but the naming was wrong (design_pattern.md instead of design-pattern.md)
This file is being deleted to allow renaming the updated file taking over.
---
docs/design-patterns.md | 382 ----------------------------------------
1 file changed, 382 deletions(-)
delete mode 100644 docs/design-patterns.md
diff --git a/docs/design-patterns.md b/docs/design-patterns.md
deleted file mode 100644
index 347ff0db7..000000000
--- a/docs/design-patterns.md
+++ /dev/null
@@ -1,382 +0,0 @@
----
-title: Design Patterns
-description: How CoreMeta4Cat is structured and why
----
-
-# Design Patterns
-
-This page explains the key structural decisions behind CoreMeta4Cat — how the four pillars are modelled, how they connect to a dataset, and what design patterns make the schema extensible and machine-actionable.
-
-
----
-
-## Reading guide
-
-This page is written in three tiers. Most users only need the first two.
-
-| Tier | Who it's for | Sections |
-|---|---|---|
-| **Overview** | Everyone — data providers, repository managers | [The entry point](#the-entry-point-catalysisdataset), [The four pillars](#the-four-pillars) |
-| **Pattern explanations** | Users who want to understand how to navigate or extend the schema | [Classification pattern](#pattern-1-classification-via-rdf_type), [Activity pattern](#pattern-2-activities-and-plans), [Mixin pattern](#pattern-3-mixin-classes) |
-| **Technical depth** | Schema developers and DCAT-AP-PLUS integrators | [Sections marked with 🔬](#deep-dive-the-evaluated-activity-distinction) |
-
----
-
-## The entry point: CatalysisDataset
-
-Every CoreMeta4Cat record starts with a **`CatalysisDataset`**. This is a `dcat:Dataset` — fully compatible with plain DCAT and DCAT-AP — extended with four additional link slots that connect to the four CoreMeta4Cat pillars.
-
-```yaml
-id: ex:dataset-001
-type: CatalysisDataset # → dcat:Dataset
-
-# Layer 1: global classification
-rdf_type:
- id: voc4cat:0007001
- title: "heterogeneous catalysis"
-
-# Layer 2: links to the four pillars
-was_generated_by:
- - id: ex:synthesis-001
- type: Synthesis
- - id: ex:characterization-001
- type: Characterization
-
-is_about_activity:
- - id: ex:reaction-001
- type: Reaction
-
-is_about_entity:
- - id: ex:catalyst-001
- type: CatalystSample
-```
-
-The key points here are:
-
-- `rdf_type` carries a **controlled vocabulary term** from [Voc4Cat](https://nfdi4cat.github.io/voc4cat/) to classify which field of catalysis the dataset belongs to.
-- `was_generated_by` links to **activities that produced the data** (Synthesis, Characterization, Simulation).
-- `is_about_activity` links to the **Reaction being studied** — which is the catalytic process itself, not a data-generating step.
-- `is_about_entity` links to the **catalyst sample or material** the dataset concerns.
-
----
-
-## The four pillars
-
-The four CoreMeta4Cat pillars — **Synthesis**, **Characterization**, **Reaction**, and **Simulation** — are the core of the metadata model. Each is a separate class, defined in its own subprofile module, and linked from the `CatalysisDataset` via the slots above.
-
-```
-catcore.yaml (aggregator + CatalysisDataset)
- ├── catcore_common.yaml (shared slots and enumerations)
- ├── catcore_synthesis_ap.yaml (Synthesis + 12 preparation methods)
- ├── catcore_characterization_ap.yaml (Characterization + 28 techniques)
- ├── catcore_reaction_ap.yaml (Reaction + 8 reactor types)
- └── catcore_simulation_ap.yaml (Simulation + 4 methods + 12 properties)
-```
-
-### Synthesis
-
-**What it is:** The process of preparing a catalyst. Synthesis is a `DataGeneratingActivity` — it produces data *about* the preparation, and it produces a `CatalystSample` as its physical output.
-
-**Key links:**
-
-- `realized_plan` → a `PreparationMethod` subclass (the protocol used)
-- `had_input_entity` → `Precursor` instances (the starting materials)
-- `had_output_entity` → `CatalystSample` (the resulting catalyst)
-
-**Twelve preparation methods** are currently defined, each as a concrete `PreparationMethod` subclass:
-
-
-
-- **Wet chemistry**
-
- Impregnation, Co-Precipitation, Deposition-Precipitation, Sol-Gel, Molecular Synthesis
-
-- **Thermal / gas-phase**
-
- Solvothermal, Combustion Synthesis, Flame Spray Pyrolysis, Sublimation, Plasma-Assisted
-
-- **Mechanical / energy-assisted**
-
- Mechanochemical Synthesis, Microwave-Assisted, Sonochemical Synthesis
-
-- **Surface / thin-film**
-
- Atomic Layer Deposition, Exsolution Synthesis
-
-
-
-### Characterization
-
-**What it is:** The measurement of a catalyst or catalytic system using an analytical technique. Characterization is also a `DataGeneratingActivity` — it produces measurement data.
-
-**Key links:**
-
-- `evaluated_entity` → the `CatalystSample` or material being measured
-- `realized_plan` → a `CharacterizationTechnique` subclass (the measurement protocol)
-- `carried_out_by` → the instrument (`Device`) performing the measurement
-
-**Twenty-eight techniques** are currently defined, organised into groups:
-
-| Group | Techniques |
-|---|---|
-| Diffraction | Powder XRD, Single Crystal XRD |
-| X-ray spectroscopy | XAS/XANES/EXAFS, XPS, EDX |
-| Vibrational spectroscopy | FTIR, DRIFTS, Raman, NMR |
-| Electron microscopy | TEM, SEM |
-| Thermal analysis | TGA, TPR, TPO |
-| Surface & pore analysis | BET |
-| Elemental analysis | ICP-AES, Elemental Analysis (CHNS) |
-| Optical & electronic | UV-Vis, Photoluminescence, Photoluminescence Lifetime |
-| Electrochemistry | Cyclic Voltammetry, Conductivity Measurement |
-| Particle sizing | Dynamic Light Scattering |
-| Mass spectrometry | ESI-MS, GC-MS, HPLC-MS |
-| Chromatography | GC, HPLC |
-
-### Reaction
-
-**What it is:** The catalytic reaction being studied. Unlike Synthesis and Characterization, Reaction is **not** a `DataGeneratingActivity`. It is the process being *observed*, not the process generating the dataset.
-
-**Key links:**
-
-- `carried_out_by` → a `ReactorDesignType` (the physical reactor)
-- `had_input_entity` → reactant feeds
-- `product_identification_method` → a `CharacterizationTechnique` used for product analysis
-
-**Eight reactor design types** are defined:
-
-`FixedBedReactor` · `CSTR` · `PlugFlowReactor` · `Autoclave` · `SlurryReactor` · `Microreactor` · `ElectrochemicalReactor` · `FluidizedBedReactor`
-
-!!! info "Operando experiments"
- For in-situ or operando experiments (e.g. XRD measured while a reaction runs), the dataset carries **both** links simultaneously:
- ```yaml
- was_generated_by:
- - type: Characterization # PowderXRD — the process that made the data
- is_about_activity:
- - type: Reaction # the catalytic process being monitored
- ```
-
-### Simulation
-
-**What it is:** A computational study of a catalyst or catalytic mechanism. Simulation is a `DataGeneratingActivity` — it generates data computationally.
-
-**Key links:**
-
-- `realized_plan` → a `SimulationMethod` subclass (DFT, MD, Microkinetics, MonteCarlo)
-- `carried_out_by` → a `Software` agent (the simulation package)
-- `evaluated_entity` → the catalyst model or structure being simulated
-
-**Twelve calculated property classes** capture the type of computed output: `ElectronicStructure`, `BandGap`, `ThermodynamicStability`, `PhononDispersion`, `Surfaces`, `GrainBoundaries`, `ElasticConstants`, `DielectricTensors`, `EquationsOfState`, `AqueousStability`, `Piezoelectricity`, `Ferroelectrics`.
-
----
-
-## Pattern 1: Classification via rdf_type
-
-!!! abstract "Pattern summary"
- Flexible, machine-actionable classification of datasets, activities, and entities using ontology terms — without creating a separate class for every possible value.
-
-Rather than defining a fixed class hierarchy for every type of catalysis or every synthesis method, CoreMeta4Cat uses a single `rdf_type` slot on each class to carry a controlled vocabulary term from Voc4Cat, CHMO, or another ontology. This keeps the schema compact while staying fully machine-actionable.
-
-**On CatalysisDataset** — classify the catalysis research field:
-
-```yaml
-rdf_type:
- id: voc4cat:0007001
- title: "heterogeneous catalysis"
-```
-
-**On Synthesis** — classify the preparation method type:
-
-```yaml
-type: Synthesis
-rdf_type:
- id: voc4cat:0007016
- title: "impregnation"
-realized_plan:
- type: Impregnation # the concrete method class with all parameter slots
-```
-
-**On Characterization** — classify the measurement technique:
-
-```yaml
-type: Characterization
-rdf_type:
- id: CHMO:0000158
- title: "powder X-ray diffraction"
-realized_plan:
- type: PowderXRD # the concrete technique class with all measurement slots
-```
-
-The `rdf_type` slot gives the machine-readable ontology term; the concrete subclass (`Impregnation`, `PowderXRD`, …) provides the structured parameter slots. Both are used together.
-
-The allowed values for `rdf_type` on `CatalysisDataset` are defined in `CatalysisResearchFieldEnum`:
-
-| Value | Ontology term | Description |
-|---|---|---|
-| `heterogeneous_catalysis` | `voc4cat:0007001` | Catalyst and reactants in different phases |
-| `homogeneous_catalysis` | `voc4cat:0000294` | Catalyst and reactants in the same phase |
-| `electrocatalysis` | `voc4cat:0000216` | Catalysis of electrochemical reactions |
-| `biocatalysis` | `voc4cat:0000204` | Enzyme or whole-cell catalysis |
-| `hybrid_catalysis` | *(pending)* | Combination of two or more approaches |
-| `other` | — | Fallback for unlisted fields |
-
----
-
-## Pattern 2: Activities and Plans
-
-!!! abstract "Pattern summary"
- A two-part structure separates *what was done* (the Activity) from *the protocol describing how to do it* (the Plan). This mirrors the PROV-O model and keeps the schema clean.
-
-Each pillar that generates data follows this two-part structure:
-
-```
-Activity (what was done) Plan (the protocol)
-───────────────────────── ───────────────────────────
-Synthesis ──→ PreparationMethod
-Characterization ──→ CharacterizationTechnique
-Simulation ──→ SimulationMethod
-```
-
-The Activity carries the **instance-level data** (who did it, when, on what sample, with what output). The Plan carries the **method-level data** (parameter settings, instrument configuration, protocol steps).
-
-```yaml
-# The activity — what happened
-id: ex:synthesis-001
-type: Synthesis
-nominal_composition: "5wt% Ni/Al2O3"
-had_input_entity:
- - id: ex:precursor-001
- type: Precursor
- name: "Ni(NO3)2·6H2O"
- precursor_quantity: 1.24 # g
-had_output_entity:
- - id: ex:catalyst-001
- type: CatalystSample
-
-# The plan — the protocol
-realized_plan:
- id: ex:method-001
- type: Impregnation
- impregnation_type: incipient_wetness
- impregnation_duration: 12.0 # h
- drying_temperature: 120.0 # °C
- drying_time: 12.0 # h
- calcination_final_temperature: 500.0 # °C
- calcination_dwelling_time: 4.0 # h
- calcination_gaseous_environment: "air"
-```
-
-This separation means a single `PreparationMethod` record could in principle be shared across multiple `Synthesis` activities — a direct gain for reproducibility.
-
----
-
-## Pattern 3: Mixin classes
-
-!!! abstract "Pattern summary"
- Slot groups that are shared across multiple methods are factored into reusable mixin classes, so each slot is defined exactly once and inherited wherever needed.
-
-Many preparation methods share common process steps — drying, calcination, precipitation. Rather than repeating the same slots in every method class, CoreMeta4Cat uses **mixin classes** that bundle related slots:
-
-| Mixin | Slots it provides | Used by |
-|---|---|---|
-| `DryingMixin` | `drying_device`, `drying_temperature`, `drying_time`, `drying_atmosphere` | Impregnation, CoPrecipitation, DepositionPrecipitation, SonochemicalSynthesis, MolecularSynthesis |
-| `CalcinationMixin` | `calcination_initial_temperature`, `calcination_final_temperature`, `calcination_dwelling_time`, `calcination_heating_rate`, `calcination_gaseous_environment`, `calcination_gas_flow_rate`, `number_of_cycles` | Impregnation, CoPrecipitation, DepositionPrecipitation, SonochemicalSynthesis, ExsolutionSynthesis |
-| `PrecipitationMixin` | `precipitating_agent`, `synthesis_ph`, `mixing_rate`, `mixing_time`, `mixing_temperature`, `order_of_addition`, `aging_temperature`, `aging_time` | CoPrecipitation, DepositionPrecipitation |
-| `ThermalSynthesisMixin` | `synthesis_temperature`, `synthesis_duration`, `equipment`, `vessel_type`, `atmosphere` | Solvothermal, PlasmaAssisted, CombustionSynthesis, MicrowaveAssisted, MechanochemicalSynthesis, Sublimation |
-
-The same pattern is used in the **Characterization** subprofile for analytical techniques:
-
-| Mixin | Used by |
-|---|---|
-| `XRaySourceMixin` | PowderXRD, SingleCrystalXRD, XPS, EDX |
-| `ElectronMicroscopyMixin` | TEM, SEM |
-| `TemperatureProgramMixin` | TPR, TPO, Thermogravimetry |
-| `ChromatographyMixin` | GC, HPLC, GC-MS, HPLC-MS |
-| `MassRangeMixin` | GC-MS, HPLC-MS, ESI-MS |
-| `ElectrochemistryMixin` | CyclicVoltammetry, ConductivityMeasurement |
-
-In LinkML, a mixin class has no `class_uri` of its own and generates no independent node shape. It is a pure slot container, mixed in via the `mixins:` key on a concrete class.
-
----
-
-## Pattern 4: Shared slots in catcore_common
-
-!!! abstract "Pattern summary"
- Slots referenced by two or more subprofiles are declared once in `catcore_common.yaml` and imported by all subprofiles. This keeps the schema DRY (Don't Repeat Yourself).
-
-Some slots appear in multiple pillars — for example, `temperature` is relevant to Synthesis (calcination), Characterization (temperature-programmed experiments), and Reaction (reactor temperature). These shared slots live in `catcore_common.yaml`:
-
-```
-catcore_common.yaml — shared slots include:
- atmosphere, temperature, flow_rate, heating_rate,
- equipment, sample_mass, stirring_speed, stirring_duration,
- drying_*, calcination_*, concentration, solvent,
- experiment_duration, step_size, resolution, ...
-```
-
-Slots that are exclusive to a single subprofile are declared in that subprofile file only.
-
----
-
-## 🔬 Deep dive: The EvaluatedActivity distinction
-
-!!! warning "Technical section"
- This section is intended for schema developers and DCAT-AP-PLUS integrators. It is not required reading for data providers.
-
-One of the most important architectural decisions in CoreMeta4Cat is that **Reaction is not a `DataGeneratingActivity`**. Instead it is an `EvaluatedActivity`.
-
-In DCAT-AP-PLUS, the distinction is:
-
-| Class | Meaning | Links to dataset via |
-|---|---|---|
-| `DataGeneratingActivity` | A process that produces the data in the dataset | `prov:wasGeneratedBy` |
-| `EvaluatedActivity` | A process that the dataset is *about*, but which did not produce it | `is_about_activity` |
-
-For catalysis, a `Reaction` is the catalytic process being studied. The data is generated by *measuring* that reaction — via a `Characterization` activity. The `Reaction` itself does not produce the data file.
-
-This distinction enables operando experiments to be described correctly:
-
-```yaml
-# Operando XRD during CO oxidation
-was_generated_by:
- - type: Characterization # PowderXRD run — this produced the data
- rdf_type:
- id: CHMO:0000158
- title: "powder X-ray diffraction"
-
-is_about_activity:
- - type: Reaction # the CO oxidation reaction being monitored
- catalyst_quantity: 50.0
- reactant: ["1 vol% CO", "2 vol% O2"]
- carried_out_by:
- type: FixedBedReactor
-```
-
-If `Reaction` were modelled as a `DataGeneratingActivity`, this relationship would collapse: it would be impossible to distinguish the measurement from the catalytic process it monitors.
-
-The same distinction appears in DCAT-AP-PLUS itself — the NMR example in the base documentation uses `was_generated_by: NMRSpectroscopy` (the measurement) and `evaluated_entity: MaterialSample` (the thing measured). CoreMeta4Cat extends this by adding `is_about_activity: Reaction` for cases where a process — not just a material — is being monitored.
-
----
-
-## Import hierarchy
-
-The full import chain, from the CoreMeta4Cat top level down to the DCAT-AP-PLUS base, is:
-
-```
-catcore.yaml
- └── catcore_common.yaml
- └── chem_dcat_ap
- └── chemical_reaction_ap
- └── chemical_entities_ap
- └── material_entities_ap
- └── dcat_ap_plus ← DCAT-AP-PLUS base
- ├── catcore_synthesis_ap.yaml
- ├── catcore_characterization_ap.yaml
- ├── catcore_reaction_ap.yaml
- └── catcore_simulation_ap.yaml
-```
-
-Each layer adds domain-specific classes and slots on top of the layer below, without modifying it. This means CoreMeta4Cat datasets remain valid DCAT-AP-PLUS instances, which in turn remain valid DCAT-AP datasets.
From d94b0d78d483b440858bf1c782b4b47eaf534554 Mon Sep 17 00:00:00 2001
From: khatamirad <104424728+khatamirad@users.noreply.github.com>
Date: Fri, 10 Jul 2026 16:18:21 +0200
Subject: [PATCH 06/10] Rename design_patterns.md to design-patterns.md
---
docs/{design_patterns.md => design-patterns.md} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename docs/{design_patterns.md => design-patterns.md} (100%)
diff --git a/docs/design_patterns.md b/docs/design-patterns.md
similarity index 100%
rename from docs/design_patterns.md
rename to docs/design-patterns.md
From c6bc94f20e0403c61b667f67cd176c08d0ba215b Mon Sep 17 00:00:00 2001
From: khatamirad <104424728+khatamirad@users.noreply.github.com>
Date: Fri, 10 Jul 2026 16:22:16 +0200
Subject: [PATCH 07/10] How-to-extend text updated
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
| # | Type | Location in page | Description |
|---|---|---|---|
| 1 | Added | Top of page, after opening sentence | Audience routing notice (`!!! note`) for non-developer visitors |
| 2 | Edited | "Before you start" block | Converted from plain indented block to `!!! tip` admonition |
| 3 | Edited | Throughout | "pillars" → "data classes" for terminology consistency |
| 4 | Added | All YAML code blocks | Language tags added for syntax highlighting |
| 5 | Edited | Mixin scope callout | Converted from plain block to `!!! tip` admonition |
---
docs/how-to-extend.md | 56 +++++++++++++++++--------------------------
1 file changed, 22 insertions(+), 34 deletions(-)
diff --git a/docs/how-to-extend.md b/docs/how-to-extend.md
index c43ee626b..5ce769a5c 100644
--- a/docs/how-to-extend.md
+++ b/docs/how-to-extend.md
@@ -1,20 +1,14 @@
----
-title: How to Extend
-description: Rules and patterns for extending CoreMeta4Cat with new methods, techniques, and properties
----
-
# How to Extend CoreMeta4Cat
-This page explains how to add new entries to the CoreMeta4Cat schema — new preparation methods, characterisation techniques, reactor types, simulation methods, or shared slots. Each section follows the same general pattern, adapted to the specific pillar.
+This page explains how to add new entries to the CoreMeta4Cat schema — new preparation methods, characterisation techniques, reactor types, simulation methods, or shared slots. Each section follows the same general pattern, adapted to the specific data class.
-
+
-!!! tip "Before you start"
- Read the [Design Patterns](design-patterns.md) page first if you are new to the schema. Understanding the Activity/Plan split and the mixin pattern will make the extension rules below straightforward.
+!!! note "Not what you were looking for?"
+ This page is for developers who want to contribute new terms to the CoreMeta4Cat schema. If you are a researcher who wants to check or annotate your dataset, start with the [Getting Started](https://nfdi4cat.github.io/CoreMeta4Cat/latest/getting-started/) page instead.
+
+!!! tip "Read Design Patterns first"
+ If you are new to the schema, read the [Design Patterns](https://nfdi4cat.github.io/CoreMeta4Cat/latest/design-patterns/) page first. Understanding the Activity/Plan split and the mixin pattern will make the extension rules below straightforward.
---
@@ -22,11 +16,9 @@ This page explains how to add new entries to the CoreMeta4Cat schema — new pre
These rules apply when extending any part of CoreMeta4Cat.
-**Rule 1 — Extend, don't modify.**
-Add new subclasses and slots. Do not rename or remove existing classes, slots, or enum values — this would break backward compatibility for any dataset already using them.
+**Rule 1 — Extend, don't modify.** Add new subclasses and slots. Do not rename or remove existing classes, slots, or enum values — this would break backward compatibility for any dataset already using them.
-**Rule 2 — Inherit from the right parent.**
-Each extension type has a designated parent class (see the table below). Always use `is_a:` with that parent, not with a sibling class.
+**Rule 2 — Inherit from the right parent.** Each extension type has a designated parent class (see the table below). Always use `is_a:` with that parent, not with a sibling class.
| What you are adding | Parent class | File |
|---|---|---|
@@ -38,17 +30,13 @@ Each extension type has a designated parent class (see the table below). Always
| New mixin (slot group) | *(no parent — mixin: true)* | Appropriate subprofile |
| New shared slot | *(no class — top-level slot)* | `catcore_common.yaml` |
-**Rule 3 — Register an ontology term.**
-Every new class should have a `class_uri:` pointing to a term in an established ontology (Voc4Cat, CHMO, OBI, NCIT, …). If no suitable term exists yet, use a provisional catcore-prefixed URI (`catcore:MyNewClass`) and open a Voc4Cat issue to request a proper term.
+**Rule 3 — Register an ontology term.** Every new class should have a `class_uri:` pointing to a term in an established ontology (Voc4Cat, CHMO, OBI, NCIT, …). If no suitable term exists yet, use a provisional catcore-prefixed URI (`catcore:MyNewClass`) and open a Voc4Cat issue to request a proper term.
-**Rule 4 — Declare slots in the right file.**
-Slots used by exactly one class go in that class's subprofile file. Slots shared by two or more classes go in `catcore_common.yaml`.
+**Rule 4 — Declare slots in the right file.** Slots used by exactly one class go in that class's subprofile file. Slots shared by two or more classes go in `catcore_common.yaml`.
-**Rule 5 — Apply existing mixins before adding new slots.**
-If your new class needs drying, calcination, precipitation, or thermal process parameters, apply the appropriate mixin rather than redeclaring those slots. Only add method-specific slots beyond what the mixin provides.
+**Rule 5 — Apply existing mixins before adding new slots.** If your new class needs drying, calcination, precipitation, or thermal process parameters, apply the appropriate mixin rather than redeclaring those slots. Only add method-specific slots beyond what the mixin provides.
-**Rule 6 — Mark obligation levels.**
-Every slot in a new class should have either `required: true` (Mandatory), `recommended: true` (Recommended), or neither (Optional). Do not leave obligations implicit.
+**Rule 6 — Mark obligation levels.** Every slot in a new class should have either `required: true` (Mandatory), `recommended: true` (Recommended), or neither (Optional). Do not leave obligations implicit.
---
@@ -78,9 +66,9 @@ MyNewMethod:
Slots already provided by mixins must not be redeclared. Only list slots that are unique to this method:
```yaml
- slots:
- - my_specific_parameter_a
- - my_specific_parameter_b
+slots:
+ - my_specific_parameter_a
+ - my_specific_parameter_b
```
**3. Declare the new slots in the slots section.**
@@ -217,7 +205,7 @@ slots:
slot_uri: catcore:neutron_wavelength
multivalued: true
unit:
- ucum_code: Ao # Angstrom
+ ucum_code: Ao
moderator_type:
description: Type of neutron moderator (e.g. cold, thermal, hot source).
@@ -426,15 +414,15 @@ SomeConcreteClass:
- MyNewMixin
```
-!!! warning "Mixin scope"
+!!! tip "Mixin scope"
A mixin should cover a coherent, reusable process step — not an arbitrary collection of slots. If a set of slots is only needed by one class, declare the slots directly on that class rather than creating a mixin.
---
## 🔬 Deep dive: Extending the import hierarchy
-!!! warning "Technical section"
- This section is for schema developers who need to introduce a new chemistry-layer or intermediate module between CoreMeta4Cat and DCAT-AP-PLUS. Most users extending the four pillars do not need this.
+??? warning "Technical section"
+ This section is for schema developers who need to introduce a new chemistry-layer or intermediate module between CoreMeta4Cat and DCAT-AP-PLUS. Most users extending the four data classes do not need this.
CoreMeta4Cat sits at the top of a layered import chain:
@@ -442,9 +430,9 @@ CoreMeta4Cat sits at the top of a layered import chain:
catcore.yaml → catcore_common.yaml → chem_dcat_ap → … → dcat_ap_plus
```
-If you need to introduce a new intermediate chemistry layer (e.g. a `polymer_catalysis_ap` that adds polymer-specific base classes used across multiple pillars), add it between `catcore_common` and the first pillar that needs it. Import it in `catcore_common.yaml` via the `imports:` key, and document the new layer in the import hierarchy diagram in `catcore.yaml`.
+If you need to introduce a new intermediate chemistry layer (e.g. a `polymer_catalysis_ap` that adds polymer-specific base classes used across multiple data classes), add it between `catcore_common` and the first data class module that needs it. Import it in `catcore_common.yaml` via the `imports:` key, and document the new layer in the import hierarchy diagram in `catcore.yaml`.
-Do not import new intermediate layers directly in individual pillar files — this would create hidden import order dependencies and make the schema harder to reason about.
+Do not import new intermediate layers directly in individual data class files — this would create hidden import order dependencies and make the schema harder to reason about.
---
From 38978ca3cacbef96a16540f0f01c5e7b82b8cd48 Mon Sep 17 00:00:00 2001
From: khatamirad <104424728+khatamirad@users.noreply.github.com>
Date: Fri, 10 Jul 2026 16:28:34 +0200
Subject: [PATCH 08/10] updated text for intended-users section
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
| # | Type | Location in page | Description |
|---|---|---|---|
| 1 | Edited | Opening paragraph | Rewritten to accurately describe what the page does |
| 2 | Added | After opening paragraph | New "Who is CoreMeta4Cat for?" section — five user-type subsections |
| 3 | Added | After user-type subsections | New "How different groups use CoreMeta4Cat" routing table |
| 4 | Edited | "Are you using CoreMeta4Cat?" | Converted to `!!! info` callout within "Projects and repositories" section |
| 5 | Fixed | Two locations | GitHub links corrected from personal fork to official repository |
---
docs/coremeta4cat-users.md | 86 +++++++++++++++++++++++++-------------
1 file changed, 56 insertions(+), 30 deletions(-)
diff --git a/docs/coremeta4cat-users.md b/docs/coremeta4cat-users.md
index 20c8ae6ed..0f1f40ea3 100644
--- a/docs/coremeta4cat-users.md
+++ b/docs/coremeta4cat-users.md
@@ -1,51 +1,77 @@
----
-title: CoreMeta4Cat Users
-description: Projects, repositories, and communities that adopt CoreMeta4Cat
+# Intended Users
+
+CoreMeta4Cat is designed for anyone who produces, manages, or builds tools around catalysis research data. This page describes who the standard is for, how different groups use it, and which projects and repositories have adopted it.
+
+
+
---
-# CoreMeta4Cat Users
+## Who is CoreMeta4Cat for?
-This page lists projects, data repositories, and communities that have adopted CoreMeta4Cat as their metadata standard. It is also the right place to understand how CoreMeta4Cat fits into the broader NFDI4Cat research data infrastructure.
+### Experimental researchers
-
+If you run catalytic experiments — synthesis, characterisation, reaction testing — CoreMeta4Cat tells you exactly what metadata to record alongside your data so that it can be understood and reused by others, including your future self. You do not need to know anything about schemas, ontologies, or FAIR principles to use it. Start with the [vocabulary reference workbook](https://nfdi4cat.github.io/CoreMeta4Cat/latest/assets/coremeta4cat_vocabulary.xlsx) and the [Getting Started](https://nfdi4cat.github.io/CoreMeta4Cat/latest/getting-started/) guide.
----
+**CoreMeta4Cat helps you:**
+- Know which metadata fields are mandatory, recommended, or optional for your specific experiment type
+- Use consistent field names and units that other researchers — and data repositories — will recognise
+- Prepare your dataset for publication, repository deposit, or FAIR compliance without extra rework
-## NFDI4Cat
+### Computational researchers
-
+If you run DFT calculations, molecular dynamics simulations, or microkinetic models, CoreMeta4Cat defines the minimum metadata for your computational outputs — software, method, settings, and calculated properties. The same vocabulary links your simulation data to experimental datasets, enabling direct comparison and validation.
-CoreMeta4Cat is developed within the [NFDI4Cat](https://nfdi4cat.org) initiative — the National Research Data Infrastructure consortium for catalysis sciences in Germany. NFDI4Cat brings together universities, research institutions, and industrial partners to build shared data infrastructure for the catalysis community.
+### Data stewards and repository managers
+
+If you manage a research data repository or institutional data infrastructure, CoreMeta4Cat provides a validated, community-agreed schema for catalysis data intake. The LinkML source generates SHACL shapes, JSON Schema, and Python/Pydantic classes automatically, making integration into existing repository workflows straightforward.
+
+**CoreMeta4Cat gives you:**
+- A structured, versioned metadata schema with clear obligation levels (Mandatory / Recommended / Optional)
+- Automatic generation of validation artefacts (SHACL, JSON Schema) from a single source
+- A direct connection to the Voc4Cat controlled vocabulary and DCAT-AP-PLUS provenance layer
+
+### Tool and ELN developers
-CoreMeta4Cat is the community-driven metadata model proposed within this framework, designed to enable semantically enriched, interoperable catalysis data across experimental, computational, and digitally curated research workflows.
+If you develop electronic lab notebooks, data management platforms, or analysis tools used in catalysis labs, CoreMeta4Cat provides a community-agreed data model to map your internal schema against. Aligning your tool's output to CoreMeta4Cat makes your users' data immediately compatible with repositories and other tools in the NFDI4Cat ecosystem.
+
+### PhD students and early-career researchers
+
+If you are new to research data management, CoreMeta4Cat is a practical starting point. Rather than confronting abstract FAIR principles, it gives you a concrete, catalysis-specific list of what to document for your experiment type. The [Getting Started](https://nfdi4cat.github.io/CoreMeta4Cat/latest/getting-started/) page is written for exactly this audience — no prior knowledge of metadata standards required.
---
-## Are you using CoreMeta4Cat?
+## How different groups use CoreMeta4Cat
-If your project, repository, or tool uses CoreMeta4Cat, we would love to list it here. Please open an issue or pull request on the [CoreMeta4Cat GitHub repository](https://github.com/HendrikBorgelt/CoreMeta4Cat) with the following information:
+| User type | Primary use | Entry point |
+|---|---|---|
+| Experimental researcher | Record and annotate dataset metadata | [Vocabulary workbook](https://nfdi4cat.github.io/CoreMeta4Cat/latest/assets/coremeta4cat_vocabulary.xlsx) · [Getting Started](https://nfdi4cat.github.io/CoreMeta4Cat/latest/getting-started/) |
+| Computational researcher | Document simulation inputs, settings, and outputs | [Simulation data class](https://nfdi4cat.github.io/CoreMeta4Cat/latest/simulation/) |
+| Data steward / repository | Implement as metadata intake schema | [Schema Reference](https://nfdi4cat.github.io/CoreMeta4Cat/latest/elements/overview/) · [Design Patterns](https://nfdi4cat.github.io/CoreMeta4Cat/latest/design-patterns/) |
+| Tool / ELN developer | Map internal schema to CoreMeta4Cat | [How to Extend](https://nfdi4cat.github.io/CoreMeta4Cat/latest/how-to-extend/) · [GitHub](https://github.com/nfdi4cat/CoreMeta4Cat) |
+| PhD student | Learn what metadata to document | [Getting Started — Level 1 and 2](https://nfdi4cat.github.io/CoreMeta4Cat/latest/getting-started/) |
-| Field | What to provide |
-|---|---|
-| **Project name** | The name of the project, repository, or tool |
-| **Organisation** | The institution or consortium responsible |
-| **Description** | One or two sentences on how CoreMeta4Cat is used |
-| **Link** | A URL to the project, dataset collection, or publication |
-| **Contact** | An optional name or email for follow-up |
+---
+
+## Projects and repositories using CoreMeta4Cat
+
+CoreMeta4Cat is developed within the [NFDI4Cat](https://nfdi4cat.org) initiative — the National Research Data Infrastructure consortium for catalysis sciences in Germany. NFDI4Cat brings together universities, research institutions, and industrial partners to build shared data infrastructure for the catalysis community.
+
+!!! info "Is your project listed here?"
+ If your project, repository, or tool uses CoreMeta4Cat, please open an issue or pull request on the [CoreMeta4Cat GitHub repository](https://github.com/nfdi4cat/CoreMeta4Cat) with the following information:
+
+ | Field | What to provide |
+ |---|---|
+ | **Project name** | The name of the project, repository, or tool |
+ | **Organisation** | The institution or consortium responsible |
+ | **Description** | One or two sentences on how CoreMeta4Cat is used |
+ | **Link** | A URL to the project, dataset collection, or publication |
+ | **Contact** | An optional name or email for follow-up |
---
## Scope of adoption
-CoreMeta4Cat is designed to be adopted at different levels, depending on the use case:
+CoreMeta4Cat can be adopted at different levels depending on your use case — from simply using the vocabulary reference as a documentation guide, all the way to full semantic integration.
**Metadata collection and submission**
Research groups can use CoreMeta4Cat to structure the metadata they report alongside published datasets, whether in institutional repositories, domain repositories, or supplementary materials of publications.
@@ -68,4 +94,4 @@ Because CoreMeta4Cat maps every class and slot to established ontology terms (Vo
| [Voc4Cat](https://nfdi4cat.github.io/voc4cat/) | The NFDI4Cat controlled vocabulary, used for `rdf_type` classification terms throughout CoreMeta4Cat |
| [DCAT-AP-PLUS](https://nfdi-de.github.io/dcat-ap-plus/dev/) | The base provenance layer that CoreMeta4Cat extends |
| [LinkML](https://linkml.io/) | The schema language and tooling used to define and validate CoreMeta4Cat |
-| [CoreMeta4Cat on GitHub](https://github.com/HendrikBorgelt/CoreMeta4Cat) | Schema source files, issue tracker, and contribution guide |
+| [CoreMeta4Cat on GitHub](https://github.com/nfdi4cat/CoreMeta4Cat) | Schema source files, issue tracker, and contribution guide |
From 375f61a9cdde6e153ad02faa8939e1c3b68f9b0b Mon Sep 17 00:00:00 2001
From: khatamirad <104424728+khatamirad@users.noreply.github.com>
Date: Fri, 10 Jul 2026 16:32:39 +0200
Subject: [PATCH 09/10] updated the text for about section
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
| # | Type | Location in page | Description |
|---|---|---|---|
| 1 | Added | Between all sections | Horizontal dividers for visual section separation |
| 2 | Edited | Citation section | "still pending" → "in preparation" |
| 3 | Added | Citation section | Zenodo DOI badge |
| 4 | Added | Contact and Contributions | Sentence linking to NFDI4Cat community channels |
| 5 | Edited | Funding table | Column alignment normalised |
---
docs/about.md | 19 ++++++++++++++++---
1 file changed, 16 insertions(+), 3 deletions(-)
diff --git a/docs/about.md b/docs/about.md
index 10ec31c36..4a30c3031 100644
--- a/docs/about.md
+++ b/docs/about.md
@@ -2,23 +2,32 @@
Robust data-sharing guidelines are essential in catalysis research to ensure high-quality metadata, reproducibility, and the sustained progress of digital catalysis. CoreMeta4Cat — an initiative under [NFDI4Cat](https://nfdi4cat.org) — specifies the minimum information that must be reported alongside catalysis research data, going beyond conventional field-independent metadata. The guideline helps researchers handle and standardise data across this versatile research field in accordance with the [FAIR principles](https://www.go-fair.org/fair-principles/) (Findable, Accessible, Interoperable, Reusable). Integration of CoreMeta4Cat into data repositories ensures the availability of high-quality metadata and facilitates efficient access to and querying of published datasets.
+---
+
## Terminology and Vocabulary
The terminology employed in CoreMeta4Cat is based on [Voc4Cat](https://nfdi4cat.github.io/voc4cat/), a controlled vocabulary developed under NFDI4Cat that supports standardised semantic representation and advances ontology development in catalysis. Terms not yet covered by Voc4Cat are provisionally defined within the model and incorporated as the vocabulary is updated. CoreMeta4Cat is built on top of [DCAT-AP+](https://nfdi-de.github.io/dcat-ap-plus/) and its chemistry extension [ChemDCAT-AP](https://nfdi-de.github.io/chem-dcat-ap/), enabling interoperability with broader research data infrastructures.
+---
## Citation
If you use CoreMeta4Cat in your research, please cite:
-> *CoreMeta4Cat: Minimum Information Guidelines for Catalysis Research Data.* NFDI4Cat. [https://nfdi4cat.github.io/CoreMeta4Cat/](https://nfdi4cat.github.io/CoreMeta4Cat/)
+> *CoreMeta4Cat: Minimum Information Guidelines for Catalysis Research Data.* NFDI4Cat.
+
+A journal publication is in preparation.
+
+[](https://doi.org/10.5281/zenodo.20564227)
-A journal publication is still pending.
+---
## Acknowledgements
CoreMeta4Cat builds on the provenance and metadata infrastructure established by [DCAT-AP+](https://nfdi-de.github.io/dcat-ap-plus/) and [ChemDCAT-AP](https://nfdi-de.github.io/chem-dcat-ap/). These schemas provide the foundational data model — including the activity, entity, and attribute patterns — on which the CatCore application profile is defined. We gratefully acknowledge the work of the DCAT-AP+ and ChemDCAT-AP development teams.
+---
+
## Funding
CoreMeta4Cat is funded by the German Research Foundation (DFG) and the German Federal Ministry of Education and Research (BMBF) as part of the National Research Data Infrastructure (NFDI):
@@ -26,8 +35,12 @@ CoreMeta4Cat is funded by the German Research Foundation (DFG) and the German Fe
| Project | Funder | Grant | Link |
|---|---|---|---|
| **NFDI4Cat** — NFDI for Catalysis-Related Sciences | DFG | [441926934](https://gepris.dfg.de/gepris/projekt/441926934) | [nfdi4cat.org](https://nfdi4cat.org/) |
-| **CarboDiol** — Carbohydrates to α-ω-Diols 2.0| BMBF | [03XP0612B](https://materialneutral.info/project/carbo-diol2-0/) | — |
+| **CarboDiol** — Carbohydrates to α-ω-Diols 2.0 | BMBF | [03XP0612B](https://materialneutral.info/project/carbo-diol2-0/) | — |
+
+---
## Contact and Contributions
CoreMeta4Cat is developed openly on [GitHub](https://github.com/nfdi4cat/CoreMeta4Cat). Contributions, issue reports, and suggestions are welcome via the repository's issue tracker.
+
+For questions about the standard or its adoption, open an issue on GitHub or reach out via the [NFDI4Cat community channels](https://nfdi4cat.org/en/contact/).
From 72582016938d3396f094cf293971019de0703616 Mon Sep 17 00:00:00 2001
From: khatamirad <104424728+khatamirad@users.noreply.github.com>
Date: Fri, 10 Jul 2026 16:35:21 +0200
Subject: [PATCH 10/10] updated text in section contributing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
| # | Type | Location in page | Description |
|---|---|---|---|
| 1 | Added | "Contribute code or schema changes" section | Link to How to Extend page |
| 2 | Edited | "Contribute code or schema changes" section | Parentheses → em dash (stylistic) |
| 3 | Added | Bottom of page | New "Not sure where to start?" closing section |
---
docs/contributing.md | 12 ++++++++++--
1 file changed, 10 insertions(+), 2 deletions(-)
diff --git a/docs/contributing.md b/docs/contributing.md
index 86b872d2a..3fc2dcb5f 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -29,7 +29,7 @@ Not sure whether a field exists, or how to annotate something? Use the [GitHub D
## Understanding the vocabulary workbook
-Download the [vocabulary reference workbook](assets/coremeta4cat_vocabulary.xlsx) for a structured overview of all fields, organised by data class and colour-coded by importance (Mandatory / Recommended / Optional). The workbook opens with an **Introduction** sheet and a **Legend** sheet explaining the colour coding and column meanings.
+Download the [vocabulary reference workbook](https://nfdi4cat.github.io/CoreMeta4Cat/latest/assets/coremeta4cat_vocabulary.xlsx) for a structured overview of all fields, organised by data class and colour-coded by importance (Mandatory / Recommended / Optional). The workbook opens with an **Introduction** sheet and a **Legend** sheet explaining the colour coding and column meanings.
The schema is the authoritative source — the workbook is generated from it automatically.
@@ -37,4 +37,12 @@ The schema is the authoritative source — the workbook is generated from it aut
## Contribute code or schema changes
-If you want to contribute a schema change yourself (add a class, slot, or enumeration), please first open an issue to discuss the change. Then follow the developer guidelines in [CONTRIBUTING.md](https://github.com/nfdi4cat/CoreMeta4Cat/blob/main/CONTRIBUTING.md) on GitHub.
+If you want to contribute a schema change yourself — add a class, slot, or enumeration — please first open an issue to discuss the change. Then follow the developer guidelines in [CONTRIBUTING.md](https://github.com/nfdi4cat/CoreMeta4Cat/blob/main/CONTRIBUTING.md) on GitHub.
+
+For detailed instructions on how to structure a new preparation method, characterisation technique, reactor type, or simulation method, see the [How to Extend](https://nfdi4cat.github.io/CoreMeta4Cat/latest/how-to-extend/) page.
+
+---
+
+## Not sure where to start?
+
+If you are new to CoreMeta4Cat and just want to check whether your dataset covers the right metadata fields, the [Getting Started](https://nfdi4cat.github.io/CoreMeta4Cat/latest/getting-started/) page is the right place to begin — no GitHub account or coding knowledge needed.
-
Synthesis](#synthesis)**
-
-- **[
Characterization](#characterization)**
-
-- **[
Reaction](#reaction)**
-
-- **[
Simulation](#simulation)**
-
-
-
-
-
-