Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Specification #75

Merged
merged 4 commits into from
Jun 15, 2024
Merged

Update Specification #75

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
790b809
Update Specification
jmanideep Jun 12, 2024
e79a4e4
use node terminology
jmanideep Jun 12, 2024
a65b9f0
minor update
jmanideep Jun 13, 2024
8df7f05
minor changes
jmanideep Jun 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 76 additions & 62 deletions SPECIFICATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
jmanideep marked this conversation as resolved.
Show resolved Hide resolved
<root>
some-data.eln/
- ro-crate-metadata.json
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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

Expand Down
Loading