Skip to content

Commit 97adeee

Browse files
elichadelichad
committed
resolve mixed-up filenames
1 parent 61f2813 commit 97adeee

File tree

3 files changed

+143
-143
lines changed

3 files changed

+143
-143
lines changed

‎episodes/03-metadata-descriptor.md‎

Lines changed: 36 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,56 @@
11
---
2-
title: Declaring the root folder
2+
title: Making a metadata descriptor
33
teaching: 2
4-
exercises: 1
4+
exercises: 2
5+
56
---
67

7-
:::::::::::::::::::::::::::::::::::::::: questions
8-
- What is the root folder?
8+
::::::::::::::::::::::::::::::::::::::: questions
9+
- Which RO-Crate version is used?
10+
- How can the crate self-identify as an RO-Crate?
911
::::::::::::::::::::::::::::::::::::::::::::::::::
1012

11-
:::::::::::::::::::::::::::::::::::::::: objectives
12-
- Create a top-level entity that can list the parts of the crate
13+
::::::::::::::::::::::::::::::::::::::: objectives
14+
- Add the first entity to the JSON-LD @graph
15+
- Indicate the version of RO-Crate
1316
::::::::::::::::::::::::::::::::::::::::::::::::::
1417

15-
## RO-Crate Root
18+
## RO-Crate Metadata descriptor
19+
20+
Next, we'll add another _entity_ to the `@graph` array has the `@id` value of `ro-crate-metadata.json` to describe the JSON file itself:
1621

17-
First we'll add an entity to the `@graph` array,
18-
to describe the [RO-Crate Root](https://www.researchobject.org/ro-crate/specification/1.2/root-data-entity.html#direct-properties-of-the-root-data-entity):
1922

2023
```json
2124
{
22-
"@id": "./",
23-
"@type": "Dataset",
24-
"hasPart": [
25-
26-
]
25+
"@id": "ro-crate-metadata.json",
26+
"@type": "CreativeWork",
27+
"conformsTo": {"@id": "https://w3id.org/ro/crate/1.2"},
28+
"about": {"@id": "./"}
2729
}
2830
```
2931

30-
By convention, in RO-Crate the `@id` value of `./` means that this entity describes the folder in which the RO-Crate metadata file is located. The root data entity always has the `@type` value of `Dataset`, which is a [schema.org](https://schema.org/Dataset) type.
31-
This will be referenced from `ro-crate-metadata.json`, semantically marking the `crate1` folder as being the RO-Crate Root.
32-
33-
34-
:::::::::::::::::::::::::::::::::::::::: discussion
35-
## RO-Crates can be published on the Web
36-
37-
This example is a folder-based RO-Crate stored on disk,
38-
and therefore absolute paths are avoided,
39-
e.g. in case the root folder is moved or archived as a ZIP file.
40-
41-
If the crate is being served from a Web service,
42-
such as a data repository or database where files are not organized in folders,
43-
then the `@id` might be an absolute URI instead of `./`
44-
-- this is one reason why we point to the root entity from the metadata descriptor,
45-
as you will see in the next section.
32+
This required entity, known as the [RO-Crate Metadata Descriptor](https://www.researchobject.org/ro-crate/specification/1.2/root-data-entity.html#ro-crate-metadata-file-descriptor),
33+
helps this file self-identify as an RO-Crate Metadata Document,
34+
which is conforming to (`conformsTo`) the RO-Crate specification version 1.2.
35+
Notice that the `conformsTo` URL corresponds to the `@context` URL version-wise,
36+
but they have two different functions.
37+
The context brings the defined terms into the metadata document,
38+
while the conformance declares which RO-Crate conventions of using those terms are being followed.
39+
40+
::::::::::::::::::::::::::::::::::::::: callout
41+
## RO-Crate versions
42+
This tutorial is written for RO-Crate 1.2,
43+
the RO-Crate website will list the [current specification version](https://www.researchobject.org/ro-crate/specification.html)
44+
-- RO-Crates can generally be upgraded to newer versions following [semantic versioning](https://semver.org/) conventions,
45+
but check the [change log](https://www.researchobject.org/ro-crate/specification/1.2/appendix/changelog.html) for any important changes.
46+
The next development version of the specification, indicated with a `-DRAFT` status,
47+
may still be subject to changes and should only be used with caution.
4648
::::::::::::::::::::::::::::::::::::::::::::::::::
4749

48-
:::::::::::::::::::::::::::::::::::::::: challenge
49-
## Add an additional type
50-
51-
1. Navigate the schema.org type list to find a subtype of `CreativeWork` that is suitable for a learning resource.
52-
2. Modify the root entity's `@type` to be an array.
53-
3. Add the type name for learning resource at the end of the array.
54-
55-
::::::::::::::: solution
56-
```json
57-
{
58-
"@id": "./",
59-
"@type": ["Dataset", "LearningResource"],
60-
"hasPart": [
61-
{"@id": "data.csv"}
62-
],
63-
"…": "…"
64-
}
65-
```
66-
:::::::::::::::::::::::::
50+
::::::::::::::::::::::::::::::::::::::: keypoints
51+
- The RO-Crate Metadata Descriptor describes the JSON-LD file itself
52+
- RO-Crate specifications are versioned
53+
- The version of RO-Crate is indicated using the conformsTo property
6754
::::::::::::::::::::::::::::::::::::::::::::::::::
6855

69-
The root has several metadata properties that describe the RO-Crate as a whole,
70-
considering it as a Research Object of collected resources.
71-
In the next section we will cover the required and recommended properties of the root `./`.
7256

73-
:::::::::::::::::::::::::::::::::::::::: keypoints
74-
- The RO-Crate Root is the top-level object of the RO-Crate
75-
- The root identifier is commonly just ./ for the current folder, but can be a URL
76-
- The root is always typed as a Dataset, but can have additional types
77-
::::::::::::::::::::::::::::::::::::::::::::::::::

‎episodes/04-root.md‎

Lines changed: 53 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,77 @@
11
---
2-
title: Describing the root entity
3-
teaching: 4
4-
exercises: 4
2+
title: Declaring the root folder
3+
teaching: 2
4+
exercises: 1
55
---
6+
67
:::::::::::::::::::::::::::::::::::::::: questions
7-
- How can I describe the crate?
8-
- How do I specify the license of the RO-Crate?
8+
- What is the root folder?
99
::::::::::::::::::::::::::::::::::::::::::::::::::
1010

1111
:::::::::::::::::::::::::::::::::::::::: objectives
12-
- Learn about required metadata for the RO-Crate Root
13-
- Understand license identifiers using SPDX
12+
- Create a top-level entity that can list the parts of the crate
1413
::::::::::::::::::::::::::::::::::::::::::::::::::
1514

16-
## Describing the root entity
17-
18-
When describing the [root entity](https://www.researchobject.org/ro-crate/specification/1.2/root-data-entity.html#direct-properties-of-the-root-data-entity),
19-
the properties generally apply to the whole of the crate.
20-
For instance it is a good idea to give a description of why these resources are gathered in a crate,
21-
as well as giving the crate a name and license for FAIR reuse and citation.
15+
## RO-Crate Root
2216

23-
:::::::::::::::::::::::::::::::::::::::: challenge
24-
## Add metadata to root entity
17+
First we'll add an entity to the `@graph` array,
18+
to describe the [RO-Crate Root](https://www.researchobject.org/ro-crate/specification/1.2/root-data-entity.html#direct-properties-of-the-root-data-entity):
2519

26-
Try to add the `name`, `description` and `datePublished` properties,
27-
and for `license` as a cross-reference,
28-
use [SPDX](https://spdx.org/licenses/) license list to find the identifier for Creative Commons Zero
29-
or another license of your choice:
30-
31-
::::::::::::::: solution
3220
```json
3321
{
34-
"@id": "./",
35-
"@type": "Dataset",
36-
"hasPart": [ ],
37-
"name": "Example crate",
38-
"description": "I created this example by following the tutorial",
39-
"datePublished": "2023-05-22",
40-
"license": { "@id": "http://spdx.org/licenses/CC0-1.0"}
22+
"@id": "./",
23+
"@type": "Dataset",
24+
"hasPart": [
25+
26+
]
4127
}
4228
```
43-
:::::::::::::::::::::::::
4429

45-
::::::::::::::::::::::::::::::::::::::::::::::::::
30+
By convention, in RO-Crate the `@id` value of `./` means that this entity describes the folder in which the RO-Crate metadata file is located. The root data entity always has the `@type` value of `Dataset`, which is a [schema.org](https://schema.org/Dataset) type.
31+
This will be referenced from `ro-crate-metadata.json`, semantically marking the `crate1` folder as being the RO-Crate Root.
4632

4733

48-
:::::::::::::::::::::::::::::::::::::::: callout
49-
## License identifiers
50-
51-
In the above solution,
52-
the identifier for CC0-1.0 <http://spdx.org/licenses/CC0-1.0> is slightly
53-
different from their listed web page URI <https://spdx.org/licenses/CC0-1.0.html>
54-
-- the former is chosen to align with [SPDX JSON-LD identifiers](https://github.com/spdx/license-list-data/tree/main/jsonld),
55-
which unfortunately are not shown directly on their website as _permalinks_.
56-
It is not a requirement in RO-Crate to use permalinks for `@id` of entities like licenses,
57-
it is nevertheless best practice to propagate permalinks where known.
34+
:::::::::::::::::::::::::::::::::::::::: discussion
35+
## RO-Crates can be published on the Web
36+
37+
This example is a folder-based RO-Crate stored on disk,
38+
and therefore absolute paths are avoided,
39+
e.g. in case the root folder is moved or archived as a ZIP file.
40+
41+
If the crate is being served from a Web service,
42+
such as a data repository or database where files are not organized in folders,
43+
then the `@id` might be an absolute URI instead of `./`
44+
-- this is one reason why we point to the root entity from the metadata descriptor,
45+
as you will see in the next section.
5846
::::::::::::::::::::::::::::::::::::::::::::::::::
5947

60-
:::::::::::::::::::::::::::::::::::::::: discussion
61-
## Choosing a license
48+
:::::::::::::::::::::::::::::::::::::::: challenge
49+
## Add an additional type
50+
51+
1. Navigate the schema.org type list to find a subtype of `CreativeWork` that is suitable for a learning resource.
52+
2. Modify the root entity's `@type` to be an array.
53+
3. Add the type name for learning resource at the end of the array.
6254

63-
Choosing a license appropriate for your dataset can be non-trivial,
64-
particularly if third-party data/software and multiple organizations are involved.
65-
See [FAIR Cookbook on licensing](https://faircookbook.elixir-europe.org/content/recipes/reusability/ATI-licensing.html).
66-
It is worth noting that an RO-Crate permits data entities to have a `license` different from the overall Crate license.
67-
It is still recommended to choose an overall Crate license that can legally apply across all the content in the RO-Crate Root.
55+
::::::::::::::: solution
56+
```json
57+
{
58+
"@id": "./",
59+
"@type": ["Dataset", "LearningResource"],
60+
"hasPart": [
61+
{"@id": "data.csv"}
62+
],
63+
"…": "…"
64+
}
65+
```
66+
:::::::::::::::::::::::::
6867
::::::::::::::::::::::::::::::::::::::::::::::::::
6968

69+
The root has several metadata properties that describe the RO-Crate as a whole,
70+
considering it as a Research Object of collected resources.
71+
In the next section we will cover the required and recommended properties of the root `./`.
72+
7073
:::::::::::::::::::::::::::::::::::::::: keypoints
71-
- Name, description, date published and license are required for the RO-Crate Root
72-
- RO-Crate allows multiple licenses for different parts
74+
- The RO-Crate Root is the top-level object of the RO-Crate
75+
- The root identifier is commonly just ./ for the current folder, but can be a URL
76+
- The root is always typed as a Dataset, but can have additional types
7377
::::::::::::::::::::::::::::::::::::::::::::::::::

‎episodes/05-root-metadata.md‎

Lines changed: 54 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,73 @@
11
---
2-
title: Making a metadata descriptor
3-
teaching: 2
4-
exercises: 2
5-
2+
title: Describing the root entity
3+
teaching: 4
4+
exercises: 4
65
---
7-
8-
::::::::::::::::::::::::::::::::::::::: questions
9-
- Which RO-Crate version is used?
10-
- How can the crate self-identify as an RO-Crate?
6+
:::::::::::::::::::::::::::::::::::::::: questions
7+
- How can I describe the crate?
8+
- How do I specify the license of the RO-Crate?
119
::::::::::::::::::::::::::::::::::::::::::::::::::
1210

13-
::::::::::::::::::::::::::::::::::::::: objectives
14-
- Add the first entity to the JSON-LD @graph
15-
- Indicate the version of RO-Crate
11+
:::::::::::::::::::::::::::::::::::::::: objectives
12+
- Learn about required metadata for the RO-Crate Root
13+
- Understand license identifiers using SPDX
1614
::::::::::::::::::::::::::::::::::::::::::::::::::
1715

18-
## RO-Crate Metadata descriptor
16+
## Describing the root entity
1917

20-
Next, we'll add another _entity_ to the `@graph` array has the `@id` value of `ro-crate-metadata.json` to describe the JSON file itself:
18+
When describing the [root entity](https://www.researchobject.org/ro-crate/specification/1.2/root-data-entity.html#direct-properties-of-the-root-data-entity),
19+
the properties generally apply to the whole of the crate.
20+
For instance it is a good idea to give a description of why these resources are gathered in a crate,
21+
as well as giving the crate a name and license for FAIR reuse and citation.
2122

23+
:::::::::::::::::::::::::::::::::::::::: challenge
24+
## Add metadata to root entity
2225

26+
Try to add the `name`, `description` and `datePublished` properties,
27+
and for `license` as a cross-reference,
28+
use [SPDX](https://spdx.org/licenses/) license list to find the identifier for Creative Commons Zero
29+
or another license of your choice:
30+
31+
::::::::::::::: solution
2332
```json
2433
{
25-
"@id": "ro-crate-metadata.json",
26-
"@type": "CreativeWork",
27-
"conformsTo": {"@id": "https://w3id.org/ro/crate/1.2"},
28-
"about": {"@id": "./"}
34+
"@id": "./",
35+
"@type": "Dataset",
36+
"hasPart": [ ],
37+
"name": "Example crate",
38+
"description": "I created this example by following the tutorial",
39+
"datePublished": "2023-05-22",
40+
"license": { "@id": "http://spdx.org/licenses/CC0-1.0"}
2941
}
3042
```
43+
:::::::::::::::::::::::::
3144

32-
This required entity, known as the [RO-Crate Metadata Descriptor](https://www.researchobject.org/ro-crate/specification/1.2/root-data-entity.html#ro-crate-metadata-file-descriptor),
33-
helps this file self-identify as an RO-Crate Metadata Document,
34-
which is conforming to (`conformsTo`) the RO-Crate specification version 1.2.
35-
Notice that the `conformsTo` URL corresponds to the `@context` URL version-wise,
36-
but they have two different functions.
37-
The context brings the defined terms into the metadata document,
38-
while the conformance declares which RO-Crate conventions of using those terms are being followed.
39-
40-
::::::::::::::::::::::::::::::::::::::: callout
41-
## RO-Crate versions
42-
This tutorial is written for RO-Crate 1.2,
43-
the RO-Crate website will list the [current specification version](https://www.researchobject.org/ro-crate/specification.html)
44-
-- RO-Crates can generally be upgraded to newer versions following [semantic versioning](https://semver.org/) conventions,
45-
but check the [change log](https://www.researchobject.org/ro-crate/specification/1.2/appendix/changelog.html) for any important changes.
46-
The next development version of the specification, indicated with a `-DRAFT` status,
47-
may still be subject to changes and should only be used with caution.
4845
::::::::::::::::::::::::::::::::::::::::::::::::::
4946

50-
::::::::::::::::::::::::::::::::::::::: keypoints
51-
- The RO-Crate Metadata Descriptor describes the JSON-LD file itself
52-
- RO-Crate specifications are versioned
53-
- The version of RO-Crate is indicated using the conformsTo property
47+
48+
:::::::::::::::::::::::::::::::::::::::: callout
49+
## License identifiers
50+
51+
In the above solution,
52+
the identifier for CC0-1.0 <http://spdx.org/licenses/CC0-1.0> is slightly
53+
different from their listed web page URI <https://spdx.org/licenses/CC0-1.0.html>
54+
-- the former is chosen to align with [SPDX JSON-LD identifiers](https://github.com/spdx/license-list-data/tree/main/jsonld),
55+
which unfortunately are not shown directly on their website as _permalinks_.
56+
It is not a requirement in RO-Crate to use permalinks for `@id` of entities like licenses,
57+
it is nevertheless best practice to propagate permalinks where known.
5458
::::::::::::::::::::::::::::::::::::::::::::::::::
5559

60+
:::::::::::::::::::::::::::::::::::::::: discussion
61+
## Choosing a license
62+
63+
Choosing a license appropriate for your dataset can be non-trivial,
64+
particularly if third-party data/software and multiple organizations are involved.
65+
See [FAIR Cookbook on licensing](https://faircookbook.elixir-europe.org/content/recipes/reusability/ATI-licensing.html).
66+
It is worth noting that an RO-Crate permits data entities to have a `license` different from the overall Crate license.
67+
It is still recommended to choose an overall Crate license that can legally apply across all the content in the RO-Crate Root.
68+
::::::::::::::::::::::::::::::::::::::::::::::::::
5669

70+
:::::::::::::::::::::::::::::::::::::::: keypoints
71+
- Name, description, date published and license are required for the RO-Crate Root
72+
- RO-Crate allows multiple licenses for different parts
73+
::::::::::::::::::::::::::::::::::::::::::::::::::

0 commit comments

Comments
 (0)