diff --git a/SPECIFICATION.md b/SPECIFICATION.md index 394debe..09c6df0 100644 --- 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 some-data.eln/ - ro-crate-metadata.json @@ -38,7 +38,7 @@ Example for file: some-data.eln - subfolder-with-data/: - some-data.bin - some-data2.bin -~~~ +``` ## Structure of ro-crate-metadata.json @@ -46,20 +46,20 @@ This is of course described in the [RO-Crate Specification](https://w3id.org/ro/ ### 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": [] } -~~~ +``` -### 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": "

Goal :

\n

\n

Procedure :

\n

\n

Results :

\n

", + "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": "

Goal :

\n

\n

Procedure :

\n

\n

Results :

\n

", - "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