source commit: 74a464e

Author: actions-user

01-introduction.md

@@ -0,0 +1,71 @@
+---
+title: Introduction
+teaching: 17
+exercises: 0
+#requirements:
+#- type: none
+#  title: "Files and folder organization"
+#- type: none
+#  title: "Familiarity with JSON file format and editor/IDE"
+#- type: external
+#  title: "An overview of the RO-Crate concept and its implementations"
+#  link: "https://gallantries.github.io/video-library/videos/ro-crates/intro/slides/"
+#- type: "internal"
+#  topic_name: data-science
+#  tutorials:
+#      - cli-basics
+#
+#license: Apache-2.0
+#
+#copyright: © Copyright 2021-2023 University of Technology Sydney, The University of Manchester UK and RO-Crate contributors
+#
+---
+
+::::::::::::::::::::::::::::::::::::::: questions
+- How do I package data in a FAIR way?
+- How can I list the authors of individual files?
+- Can I use multiple licenses in the same data package?
+- How can I visualize JSON-LD metadata?
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::: objectives
+- Construct an RO-Crate by hand using JSON
+- Describe each part of the Research Object
+- Learn basic JSON-LD to create FAIR metadata
+- Connect different parts of the Research Object using identifiers
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+## Introduction
+
+This tutorial assumes you have already completed
+[An overview of the RO-Crate concept and its implementations](https://gallantries.github.io/video-library/videos/ro-crates/intro/slides/):
+
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/5GYdN5B1tc8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen>
+  <a href="https://www.youtube.com/watch?v=5GYdN5B1tc8"><img src="https://i.ytimg.com/vi/5GYdN5B1tc8/maxresdefault.jpg" alt="An overview of the RO-Crate concept and its implementations" />
+</iframe>
+
+_Video: An overview of the RO-Crate concept and its implementations_ (see also [slides and transcript](https://doi.org/10.5281/zenodo.7828632))
+
+
+## Tutorial walk-through
+
+In this tutorial, meant to be read along with the [RO-Crate specification](https://www.researchobject.org/ro-crate/1.1/),
+we'll walk through the initial steps for creating a basic RO-Crate.
+You are invited to replicate the below steps on your local computer.
+
+::::::::::::::::::::::::::::::::::::::: callout
+## Abbreviations
+- FAIR: Findable, Accessible, Interoperable, Reusable; a set of principles for publishing research data and metadata
+- JSON: JavaScript Object Notation, a generic structured text-based data format
+- JSON-LD: JSON Linked Data, a way to express Linked Data (RDF) using regular JSON
+- RO-Crate: Research Object Crate; a way to package research data with structured FAIR metadata
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::: keypoints
+- RO-Crate provides a structure to make FAIR data packages
+- schema.org in JSON-LD provides a controlled vocabulary for FAIR metadata
+- Each entity of the crate is described separately
+- Cross-references between entities create a graph
+- The RO-Crate specification recommends which types and keys to use
+::::::::::::::::::::::::::::::::::::::::::::::::::

02-folder-as-crate-root.md

@@ -0,0 +1,92 @@
+---
+title: Turning a folder into an RO-Crate
+teaching: 4
+exercises: 3
+---
+
+::::::::::::::::::::::::::::::::::::::: objectives
+- Creating a skeleton RO-Crate Metadata File
+- Use the JSON-LD pre-amble to enable Linked Data
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: questions
+- How can I start a new RO-Crate?
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+
+## Turning a folder into an RO-Crate
+
+In the simplest form, to describe some data on disk,
+an _RO-Crate Metadata File_ is placed in a folder
+alongside a set of files or folders. 
+
+First create a new folder `crate1/`
+and add a single file `data.csv` to represent our dataset:
+
+```
+"Date","Minimum temperature (°C)","Maximum temperature (°C)","Rainfall (mm)"
+2022-02-01,16.0,28.4,0.6
+2022-02-02,16.3,17.2,12.4
+```
+
+
+Next, to turn this folder into an RO-Crate,
+we need to add the _RO-Crate Metadata File_, which has a fixed filename.
+Create the file `ro-crate-metadata.json`
+using [Visual Studio Code](https://code.visualstudio.com/) or your favourite editor,
+then add the following JSON:
+
+```json
+{
+  "@context": "https://w3id.org/ro/crate/1.1/context",
+  "@graph": [
+
+  ]
+}
+```
+
+Your folder should now look like this:
+
+![Folder listing of crate1, including data.csv and ro-crate-metadata.json](fig/crate1-folders.svg){alt='Any folder can be made into an RO-Crate by adding `ro-crate-metadata.json`'}
+
+The presence of the reserved `ro-crate-metadata.json` filename
+means that `crate1` (and its children) can now be considered to be an **RO-Crate**.
+We call the top-level folder of the crate for the **RO-Crate Root**
+and can now refer to its content with relative file paths.
+
+We also need to make some declaration within the JSON file to turn it into a valid _RO-Crate Metadata Document_,
+explained in the next session.
+
+
+## JSON-LD preamble
+
+The preamble of `@context` and `@graph` are JSON-LD structures
+that help provide global identifiers to the JSON keys and types
+used in the rest of the RO-Crate document.
+These will largely map to definitions in the [schema.org](http://schema.org/) vocabulary,
+which can be used by RO-Crate extensions to provide additional metadata beyond the RO-Crate specifications.
+It is this feature of JSON-LD that helps make RO-Crate extensible for many different purposes
+-- this is explored further in the specification's [appendix on JSON-LD](https://www.researchobject.org/ro-crate/1.1/appendix/jsonld.html).
+In short, only JSON keys (_properties_) and types defined this way can be used within the RO-Crate Metadata Document.
+
+However, in the general case it should be sufficient to follow the RO-Crate JSON examples directly without deeper JSON-LD understanding.
+The RO-Crate Metadata Document contains a flat list of _entities_ as JSON objects in the `@graph` array.
+These entities are cross-referenced using `@id` identifiers, rather than being deeply nested.
+This is one major difference from JSON structures you may have experienced before.
+The `@type` keyword associates an object with a predefined type from the JSON-LD context.
+Almost any property can alternatively be used with an `[]` array to provide multiple values.
+
+The rest of this tutorial,
+and indeed most of the [RO-Crate specification](https://www.researchobject.org/ro-crate/1.1/),
+specify which entities can be added to the `@graph` array. 
+
+
+:::::::::::::::::::::::::::::::::::::::: keypoints
+- Adding a RO-Crate Metadata file to a folder turns it into an RO-Crate
+- The RO-Crate Root is the top-level folder of the crate
+- RO-Crate uses schema.org as base vocabulary
+- The JSON-LD context enables optional Linked Data processing
+- Descriptions are listed flatly as entities in the @graph array
+::::::::::::::::::::::::::::::::::::::::::::::::::
+

03-metadata-descriptor.md

@@ -0,0 +1,56 @@
+---
+title: Making a metadata descriptor
+teaching: 2
+exercises: 2
+
+---
+
+::::::::::::::::::::::::::::::::::::::: questions
+- Which RO-Crate version is used?
+- How can the crate self-identify as an RO-Crate?
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::: objectives
+- Add the first entity to the JSON-LD @graph
+- Indicate the version of RO-Crate
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+## RO-Crate Metadata descriptor 
+
+The first JSON-LD _entity_ to add in the `@graph` array has the `@id` value of `ro-crate-metadata.json` to describe the JSON file itself:
+
+
+```json
+{
+    "@id": "ro-crate-metadata.json",
+    "@type": "CreativeWork",
+    "conformsTo": {"@id": "https://w3id.org/ro/crate/1.1"},
+    "about": {"@id": "./"}
+}
+```
+
+This required entity, known as the [RO-Crate Metadata Descriptor](https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#ro-crate-metadata-file-descriptor),
+helps this file self-identify as an RO-Crate Metadata Document,
+which is conforming to (`conformsTo`) the RO-Crate specification version 1.1.
+Notice that the `conformsTo` URL corresponds to the `@context` URL version-wise,
+but they have two different functions.
+The context brings the defined terms into the metadata document,
+while the conformance declares which RO-Crate conventions of using those terms are being followed.
+
+::::::::::::::::::::::::::::::::::::::: callout
+## RO-Crate versions
+This tutorial is written for RO-Crate 1.1,
+the RO-Crate website will list the [current specification version](https://www.researchobject.org/ro-crate/specification.html)
+-- RO-Crates can generally be upgraded to newer versions following [semantic versioning](https://semver.org/) conventions,
+but check the [change log](https://www.researchobject.org/ro-crate/1.1/appendix/changelog.html) for any important changes.
+The next development version of the specification, indicated with a `-DRAFT` status,
+may still be subject to changes and should only be used with caution.
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::: keypoints
+- The RO-Crate Metadata Descriptor describes the JSON-LD file itself
+- RO-Crate specifications are versioned
+- The version of RO-Crate is indicated using the conformsTo property
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+

04-root.md

@@ -0,0 +1,67 @@
+---
+title: Declaring the root folder
+teaching: 2
+exercises: 1
+---
+
+:::::::::::::::::::::::::::::::::::::::: questions
+- What is the root folder?
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: objectives
+- Create a top-level entity that can list the parts of the crate
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+## RO-Crate Root
+
+Next we'll add another entity to the `@graph` array,
+to describe the [RO-Crate Root](https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#direct-properties-of-the-root-data-entity):
+
+```json
+{
+    "@id": "./",
+    "@type": "Dataset",
+    "hasPart": [ 
+
+    ]
+}
+```
+
+:::::::::::::::::::::::::::::::::::::::: callout
+## Adding entities to the JSON array
+
+Because we're adding incrementally to the `@graph` array.
+It is important to remember the comma `,` between each entity,
+**except** for the final entity in the JSON array;
+and likewise for the properties within the JSON object for each entity.
+This is an artefact of the strict [JSON](https://www.json.org/) file format rules to simplify parsing.
+The order of the entities within the `@graph` JSON-LD array
+and the order of the keys within a JSON object is _not significant_.
+The _graph_ content is given by the `@id` cross-references.
+
+You will add a comma here between the `ro-crate-metadata.json` entity, and the root data entity.
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+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.
+This reference from `ro-crate-metadata.json` is therefore semantically marking the `crate1` folder as being the RO-Crate Root.
+
+
+:::::::::::::::::::::::::::::::::::::::: discussion
+## RO-Crates can be published on the Web
+ 
+This example is a folder-based RO-Crate stored on disk,
+and therefore absolute paths are avoided,
+e.g. in case the root folder is moved or archived as a ZIP file. 
+ 
+If the crate is being served from a Web service,
+such as a data repository or database where files are not organized in folders,
+then the `@id` might be an absolute URI instead of `./`
+-- this is one reason why we point to the root entity from the metadata descriptor,
+see section [Root Data Entity](https://www.researchobject.org/ro-crate/1.1/root-data-entity.html) for details.
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: keypoints
+- The RO-Crate Root is the top-level object of the RO-Crate
+- The root identifier may be a URL, but commonly just ./ for the current folder
+::::::::::::::::::::::::::::::::::::::::::::::::::
+

05-root-metadata.md

@@ -0,0 +1,76 @@
+---
+title: Describing the root entity
+teaching: 4
+exercises: 4
+---
+:::::::::::::::::::::::::::::::::::::::: questions
+- How can I describe the crate?
+- How do I specify the license of the RO-Crate?
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: objectives
+- Learn about required metadata for the RO-Crate Root
+- Understand license identifiers using SPDX
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+## Describing the root entity
+
+When describing the [root entity](https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#direct-properties-of-the-root-data-entity),
+the properties generally apply to the whole of the crate.
+For instance it is a good idea to give a description of why these resources are gathered in a crate,
+as well as giving the crate a name and license for FAIR reuse and citation.
+
+:::::::::::::::::::::::::::::::::::::::: challenge
+## Add metadata to root entity
+
+Try to add the `name`, `description` and `datePublished` properties,
+and for `license` as a cross-reference,
+use [SPDX](https://spdx.org/licenses/) license list to find the identifier for Creative Commons Zero
+or another license of your choice:
+
+:::::::::::::::  solution
+```json
+{
+  "@id": "./",
+  "@type": "Dataset",
+  "hasPart": [ ],
+  "name": "Example crate",
+  "description": "I created this example by following the tutorial",
+  "datePublished": "2023-05-22T12:03:00+0100",
+  "license": { "@id": "http://spdx.org/licenses/CC0-1.0"}  
+}
+```
+:::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+:::::::::::::::::::::::::::::::::::::::: callout
+## License identifiers
+
+In the above solution,
+the identifier for CC0-1.0 <http://spdx.org/licenses/CC0-1.0> is slightly
+different from their listed web page URI <https://spdx.org/licenses/CC0-1.0.html>
+-- the former is chosen to align with [SPDX JSON-LD identifiers](https://github.com/spdx/license-list-data/tree/main/jsonld),
+which unfortunately are not shown directly on their website as _permalinks_. 
+It is not a requirement in RO-Crate to use permalinks for `@id` of entities like licenses, 
+it is nevertheless best practice to propagate permalinks where known.
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: discussion
+## Choosing a license
+
+Choosing a license appropriate for your dataset can be non-trivial,
+particularly if third-party data/software and multiple organizations are involved.
+See [FAIR Cookbook on licensing](https://faircookbook.elixir-europe.org/content/recipes/reusability/ATI-licensing.html).
+It is worth noting that an RO-Crate permits data entities to have a `license` different from the overall Crate license.
+It is still recommended to choose an overall Crate license that can legally apply across all the content in the RO-Crate Root.
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: keypoints
+- Name, description, date published and license are required for the RO-Crate Root"
+- RO-Crate allows multiple licenses for different parts
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+