Skip to content

Commit 115d571

Browse files
siamaknsiamakn
committed
Addressed review comments
1 parent 61d7e46 commit 115d571

File tree

2 files changed

+63
-62
lines changed

2 files changed

+63
-62
lines changed

‎docs/tutorial/customization/custom_schemas.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,17 @@ Custom schemas in NOMAD define how data is structured, stored, and displayed, al
66
- Define data structures that dictate how information is organized and presented.
77
- Enable ELN functionality for manual data input and structured documentation.
88
- Extract structured data from files using parsers, which allow NOMAD to read data from raw files.
9-
- Transform and enrich data post-upload using normalizers, ensuring compatibility with schema requirements and enhancing metadata consistency.
9+
- Transform and enrich data, post-upload, using [normalizers](../../reference/glossary.md#normalizer), ensuring compatibility with schema requirements and enhancing metadata consistency.
1010

1111

1212
There are two primary approaches to creating custom schemas:
1313

14-
- **Python schemas**: These offer highest possible level of customization by allowing the integration of **custom parsers** and **normalizers**, enabling maximum automation.
15-
- **Serialized schemas (YAML/JSON)**: Human-readable and easier to write and manage, ideal for defining customized ELNs without coding skills. However, they do not support normalizers.
14+
- **Python schemas**: These offer highest possible level of customization by allowing the integration of [parsers](../../reference/glossary.md#parser) and [normalizers](../../reference/glossary.md#normalizer), enabling maximum automation.
15+
- **Serialized schemas (YAML/JSON)**: Human-readable and easier to write and manage, ideal for defining customized ELNs without coding skills. They can be used on both the central NOMAD and any Oasis instance without requiring configuration changes, making them especially convenient for quick customization.
16+
1617

1718
This part of the tutorial covers the following topics:
1819

1920
- [YAML schemas](custom_yaml.md): Defining structured YAML schemas for NOMAD.
2021
- [Custom ELN with YAML](custom_eln.md): Creating an ELN schema to enable structured metadata entry.
21-
- [Tabular parser in YAML](custom_tabular.md): Utilizing the built-in tabular parser to process spreadsheet data.
22-
- [Python schemas](custom_python.md): Exploring Python schemas and their advanced capabilities.
23-
- [Normalizers](custom_normalizer.md): Implementing normalizers to automate data processing.
22+
- [Tabular parser in YAML](custom_tabular.md): Utilizing the built-in tabular parser to process spreadsheet data.

‎docs/tutorial/customization/custom_yaml.md‎

Lines changed: 58 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,15 @@
33

44
## Guidelines for building a custom schema
55

6-
NOMAD YAML schema files must have the `.archive.yaml` extension for NOMAD to recognize them as schema files. Below are six main guidelines for creating a custom YAML schema file.
6+
To define custom YAML schemas in NOMAD, you need to create a YAML file with the `.archive.yaml` extension. These files represent a [schema package](../../reference/glossary.md#schema-package), which can include one or more section and quantity definitions.. Below are six main guidelines for creating a custom YAML schema file.
77

88
??? info "1. NOMAD's `archive.yaml` files start with the `definitions:` keyword, and must have a `name:`, and can have a `description:`."
99

1010
NOMAD syntax:
1111
```yaml
1212
definitions:
13-
name:
14-
description:
13+
name: ...
14+
description: ...
1515
```
1616

1717
Example:
@@ -28,13 +28,13 @@ NOMAD YAML schema files must have the `.archive.yaml` extension for NOMAD to rec
2828

2929
```yaml
3030
definitions:
31-
name:
32-
description:
31+
name: ...
32+
description: ...
3333

3434
sections:
35-
My_first_section:
36-
My_second_section:
37-
My_third_section:
35+
MyFirstSection: ...
36+
MySecondSection: ...
37+
MyThirdSection: ...
3838
```
3939

4040

@@ -49,28 +49,28 @@ NOMAD YAML schema files must have the `.archive.yaml` extension for NOMAD to rec
4949
description: This is a custom schema that includes several sections.
5050

5151
sections:
52-
My_first_section:
52+
MyFirstSection:
5353
base_sections:
5454
- nomad.datamodel.data.EntryData
55-
- nomad.datamodel.metainfo.eln.Sample
55+
- nomad.datamodel.metainfo.eln.ELNSample
5656

57-
My_second_section:
58-
My_third_section:
57+
MySecondSection: ...
58+
MyThirdSection: ...
5959
```
6060

6161
or alternatively in the form of a Python list:
6262

6363
```yaml
6464
definitions:
65-
name: My NOMAD ELN
65+
name: My NOMAD Custom Schema
6666
description: This is a custom schema that includes several sections.
6767

6868
sections:
69-
My_first_section:
70-
base_sections: ['nomad.datamodel.data.EntryData', 'nomad.datamodel.metainfo.eln.Sample']
69+
MyFirstSection:
70+
base_sections: ['nomad.datamodel.data.EntryData', 'nomad.datamodel.metainfo.eln.ELNSample']
7171

72-
My_second_section:
73-
My_third_section:
72+
MySecondSection: ...
73+
MyThirdSection: ...
7474
```
7575

7676
??? info "4. Each section can contain quantities, other sections, and subsections."
@@ -80,23 +80,24 @@ NOMAD YAML schema files must have the `.archive.yaml` extension for NOMAD to rec
8080

8181
```yaml
8282
definitions:
83-
name: My NOMAD ELN
83+
name: My NOMAD Custom Schema
8484
description: This is a custom schema that includes several sections.
8585

8686
sections:
87-
My_first_section:
87+
MyFirstSection:
8888
base_sections:
8989
- nomad.datamodel.data.EntryData
90-
- nomad.datamodel.metainfo.eln.Sample
91-
quantities:
92-
90+
- nomad.datamodel.metainfo.eln.ELNSample
91+
quantities:
92+
first_quantity:
93+
type: str # Uses python type notation like: int, np.float64, etc.
9394
sub_sections:
94-
My_first_subsection:
95-
section:
96-
My_second_subsection:
97-
section:
98-
My_second_section:
99-
My_third_section:
95+
my_first_subsection:
96+
section: ...
97+
my_second_subsection:
98+
section: ...
99+
MySecondSection: ...
100+
MyThirdSection: ...
100101
```
101102

102103

@@ -105,44 +106,45 @@ NOMAD YAML schema files must have the `.archive.yaml` extension for NOMAD to rec
105106

106107
```yaml
107108
definitions:
108-
name: My NOMAD ELN
109+
name: My NOMAD Custom Schema
109110
description: This is a custom schema that includes several sections.
110111

111112
sections:
112-
My_first_section:
113+
MyFirstSection:
113114
base_sections:
114115
- nomad.datamodel.data.EntryData
115-
- nomad.datamodel.metainfo.eln.Sample
116+
- nomad.datamodel.metainfo.eln.ELNSample
116117
quantities:
117118
first_quantity:
118-
- type: #For example, str or np.float64
119-
- shape: #For example scalar or list (['*'])
120-
- unit: #For example, meters, amperes, or seconds
119+
type: #For example, str or np.float64
120+
shape: #For example scalar or list (['*'])
121+
unit: #For example, meters, amperes, or seconds
121122
sub_sections:
122-
My_first_subsection:
123-
section:
124-
My_second_subsection:
125-
section:
126-
My_third_subsection:
127-
section:
128-
129-
My_second_section:
130-
My_third_section:
123+
my_first_subsection:
124+
section: ...
125+
my_second_subsection:
126+
section: ...
127+
my_third_subsection:
128+
section: ...
129+
130+
MySecondSection: ...
131+
MyThirdSection: ...
131132
```
132133

133134
??? info "6. Sections and quantities can have annotations"
134135
Annotations provide additional information that NOMAD can use to alter its behavior around these definitions and how users can interact with them. The keyword for annotations is `m_annotations:`.
135136
Among the various functionalities that annotations provide, they enable the transformation of schema sections, subsections, and quantities into ELN components that users can edit directly within the GUI.
137+
136138
```yaml
137139
definitions:
138-
name: My NOMAD ELN
140+
name: My NOMAD Custom Schema
139141
description: This is an electronic lab notebook schema that includes several sections.
140142
141143
sections:
142-
My_first_section:
144+
MyFirst_Section:
143145
base_sections:
144146
- nomad.datamodel.data.EntryData
145-
- nomad.datamodel.metainfo.eln.Sample
147+
- nomad.datamodel.metainfo.eln.ELNSample
146148
quantities:
147149
first_quantity:
148150
- type: #For example, str or np.float64
@@ -151,14 +153,14 @@ NOMAD YAML schema files must have the `.archive.yaml` extension for NOMAD to rec
151153
m_annotations:
152154
annotation_name:
153155
key1: value1
154-
sub_section:
155-
My_first_subsection:
156-
section:
157-
My_second_subsection:
158-
section:
159-
My_third_subsection:
160-
section:
161-
162-
My_second_section:
163-
My_third_section:
156+
sub_sections:
157+
my_first_subsection:
158+
section: ...
159+
my_second_subsection:
160+
section: ...
161+
my_third_subsection:
162+
section: ...
163+
164+
MySecondSection: ...
165+
MyThirdSection: ...
164166
```

0 commit comments

Comments
 (0)