Merge pull request #75 from jmanideep/update_spec

Update Specification
TheELNConsortium · Jun 15, 2024 · 23fcd7c · 23fcd7c
2 parents 4d7c8a8 + 8df7f05
commit 23fcd7c
Showing 1 changed file with 76 additions and 62 deletions.
diff --git a/SPECIFICATION.md b/SPECIFICATION.md
@@ -22,7 +22,7 @@ The rest of the archive is composed of 0 or more folders that each describe one
 
 Example for file: some-data.eln
 
-~~~yaml
+```yaml
 <root>
   some-data.eln/
     - ro-crate-metadata.json
@@ -38,28 +38,28 @@ Example for file: some-data.eln
       - subfolder-with-data/:
         - some-data.bin
         - some-data2.bin
-~~~
+```
 
 ## Structure of ro-crate-metadata.json
 
 This is of course described in the [RO-Crate Specification](https://w3id.org/ro/crate/1.1) but let's go over an example to understand how it works.
 
 ### Root
 
-At the root of our json-ld object, we have a context and a graph. The graph will contain an array of everything we put in our crate.
+At the root of our JSON-LD object, we have a context and a graph. The graph will contain an array of everything we put in our crate. Each node object in the graph represents the properties of a node serialized by the JSON-LD.
 
-~~~json
+```json
 {
   "@context": "https://w3id.org/ro/crate/1.1/context",
   "@graph": [<EVERYTHING IS IN THERE>]
 }
-~~~
+```
 
-### First object: ro-crate-metadata.json
+### First node: ro-crate-metadata.json
 
-The first thing we do is describe the `ro-crate-metadata.json` object:
+The first node we describe here is the `ro-crate-metadata.json`:
 
-~~~json
+```json
 {
   "@id": "ro-crate-metadata.json",
   "@type": "CreativeWork",
@@ -70,83 +70,97 @@ The first thing we do is describe the `ro-crate-metadata.json` object:
     "@id": "https://w3id.org/ro/crate/1.1"
   },
   "dateCreated": "2022-05-30T12:25:36+0200",
+  "sdPublisher": {
+    "@id": "https://eln-example.com"
+  }
 }
-~~~
-
-It is a `CreativeWork` about the current directory where it is, and conforms to the RO-Crate specification. Other fields like `dateCreated` (added here), `sdPublisher` or [any other property](https://schema.org/CreativeWork) of `CreativeWork` can be added.
-
-
-### Second object: current directory
-
-The second object is basically describing the current directory (`./`).
-
-~~~json
- {
-    "@id": "./",
-    "@type": [
-      "Dataset"
-    ],
-    "hasPart": [
-      "./2022-05-29 - Some-experiment",
-      "./2022-05-29 - Some-experiment/2022-05-30-export.elabftw.csv",
-      "./2022-05-29 - Some-experiment/2022-05-29 - Some-experiment.pdf",
-      "./2022-05-29 - Some-experiment/example.mp4",
-      "./2022-05-29 - Some-experiment/example.pdb",
-      "./2022-05-29 - Some-experiment/example.jpg",
-      "./2022-05-29 - Id-asperiores-explicabo-quod-mollitia",
-      "./2022-05-29 - Id-asperiores-explicabo-quod-mollitia/2022-05-30-export.elabftw.csv",
-      "./2022-05-29 - Id-asperiores-explicabo-quod-mollitia/2022-05-29 - Id-asperiores-explicabo-quod-mollitia.pdf",
-      "./2022-05-29 - Id-asperiores-explicabo-quod-mollitia/example.pps",
-    ]
+```
+
+It is a `CreativeWork` about the current directory where it is, and conforms to the RO-Crate specification. Other fields like `dateCreated` (added here) or [any other property](https://schema.org/CreativeWork) of `CreativeWork` can be added.
+
+In addition to the properties outlined in the [RO-Crate Metadata File Descriptor](https://www.researchobject.org/ro-crate/specification/1.1/root-data-entity.html#ro-crate-metadata-file-descriptor), this node SHOULD include `sdPublisher` property, which references the Organization entity containing additional metadata.
+
+The Organization entity SHOULD contain an `@id`, `@type: Organization`, `name` and `url` properties. Any other properties of `Organization` MAY also be added.
+
+### Second node: current directory
+
+The second node is basically describing the current directory (`./`).
+
+```json
+{
+  "@id": "./",
+  "@type": ["Dataset"],
+  "hasPart": [
+    {
+      "@id": "./2022-05-29 - Some-experiment/"
+    },
+    {
+      "@id": "./2022-05-29 - Id-asperiores-explicabo-quod-mollitia/"
+    }
+  ]
 }
-~~~
+```
 
-Its type is an array of `Dataset` and `hasPart` which corresponds to the differents `@id` of the other objects. Think of it like a Table of Contents.
+Its type is an array of `Dataset` and `hasPart` which corresponds to the different `@id`s of the other nodes. Think of it like a Table of Contents.
 
 ### The rest
 
-After that, all the other objects have an `@type` of either `Dataset` for directories or `File` for well..., files. And the `@id` corresponds to something in the `hasPart` of `./`.
+Subsequently, all the remaining nodes are assigned a `@type` of either `Dataset` for directories or `File` for individual files. And the `@id` corresponds to something in the `hasPart` of `./`.
+
+If a Dataset node has additional files, they should be listed in its `hasPart` property and can be referenced through their `@id`.
+
+All nodes with `@type: Dataset` SHOULD include `name`, `author` properties. Furthermore, other properties of `Dataset`, such as `identifier`, `dateCreated`, `dateModified`, `text`, `keywords`, `comment` MAY also be added.
 
-All objects (nodes) with a `@type` such as `Comment` or `Person` exist at the root node (once), and can be referenced via their `@id` in other parts.
+All nodes with `@type: File` SHOULD include `name`, `encodingFormat`, `contentSize` properties. Furthermore, other properties of `File`, such as `description`, `sha256`, `author`, `identifier`, `dateCreated`, `dateModified`, `text` MAY also be added.
+
+All nodes with a `@type` such as `Comment` or `Person` exist at the root node (once), and can be referenced via their `@id` in other parts.
 
 For instance, a "comment" on an experiment will exist as a `@type: Comment` node at the root node, and be referenced through its `@id` in the `comment` part of the experiment's node. See "Example Dataset with Comment" example below.
 
 #### Example Dataset
 
-~~~json
+```json
 {
-    "@id": "./2022-05-29 - Some-experiment",
-    "@type": "Dataset",
-    "author": {
-      "@id": "./author/23"
+  "@id": "./2022-05-29 - Some-experiment/",
+  "@type": "Dataset",
+  "author": {
+    "@id": "./author/23"
+  },
+  "dateCreated": "2022-05-29 16:17:38",
+  "dateModified": "2022-05-29 16:17:57",
+  "name": "Some experiment",
+  "text": "<h1><span style=\"font-size:14pt;\">Goal :</span></h1>\n<p> </p>\n<h1><span style=\"font-size:14pt;\">Procedure :</span></h1>\n<p> </p>\n<h1><span style=\"font-size:14pt;\">Results :<br></span></h1>\n<p> </p>",
+  "url": "https://elab.example.com/experiments.php?mode=view&id=256",
+  "hasPart": [
+    {
+      "@id": "./2022-05-29 - Some-experiment/2022-05-30-export.elabftw.csv"
     },
-    "dateCreated": "2022-05-29 16:17:38",
-    "dateModified": "2022-05-29 16:17:57",
-    "name": "Some experiment",
-    "text": "<h1><span style=\"font-size:14pt;\">Goal :</span></h1>\n<p> </p>\n<h1><span style=\"font-size:14pt;\">Procedure :</span></h1>\n<p> </p>\n<h1><span style=\"font-size:14pt;\">Results :<br></span></h1>\n<p> </p>",
-    "url": "https://elab.example.com/experiments.php?mode=view&id=256"
+    {
+      "@id": "./2022-05-29 - Some-experiment/2022-05-29 - Some-experiment.pdf"
+    }
+  ]
 }
-~~~
+```
 
 #### Example File
 
-~~~json
+```json
 {
-    "@id": "./2022-05-29 - Some-experiment/2022-05-30-export.elabftw.csv",
-    "@type": "File",
-    "description": "CSV Export",
-    "name": "2022-05-30-export.elabftw.csv",
-    "contentType": "text/csv; charset=UTF-8",
-    "contentSize": "247",
-    "sha256": "f3278e796c687371cc63a600b6f12ea32167067fed3ef98099d0c1aad2426531"
+  "@id": "./2022-05-29 - Some-experiment/2022-05-30-export.elabftw.csv",
+  "@type": "File",
+  "description": "CSV Export",
+  "name": "2022-05-30-export.elabftw.csv",
+  "encodingFormat": "text/csv; charset=UTF-8",
+  "contentSize": "247",
+  "sha256": "f3278e796c687371cc63a600b6f12ea32167067fed3ef98099d0c1aad2426531"
 }
-~~~
+```
 
 #### Example Dataset with Comment
 
 Here we show three nodes, the Dataset (main experiment), a Comment and a Person. The Person leaving the Comment is the same as the author of the Dataset.
 
-~~~json
+```json
 {
   "@id": "./some-unique-id/23",
   "@type": "Dataset",
@@ -171,12 +185,12 @@ Here we show three nodes, the Dataset (main experiment), a Comment and a Person.
   }
 },
 {
-   "@id": "./some-author-id/44"
+   "@id": "./some-author-id/44",
    "@type": "Person",
    "familyName": "Tapie",
    "givenName": "Bernard"
 }
-~~~
+```
 
 ### Going further