Updates for 1.2 and suggestions from ACM run through

Author: Abigail Miller

CODE_OF_CONDUCT.md

@@ -1,3 +1,7 @@
+---
+title: "Contributor Code of Conduct"
+---
+
 # Contributor Code of Conduct
 
 Contributors to the RO-Crate community, including this tutorial, are expected to comply with our [Code of Conduct](https://github.com/ResearchObject/ro-crate/blob/main/CODE_OF_CONDUCT.md) to ensure an open and inclusive environment. You may email [email protected] to report any Code of Conduct concerns.

config.yaml

@@ -67,10 +67,10 @@ contact: "[email protected]"
 # Order of episodes in your lesson
 episodes:
   - 01-introduction.md
-  - 02-folder-as-crate-root.md
-  - 03-metadata-descriptor.md
-  - 04-root.md
-  - 05-root-metadata.md
+  - 02-folder-as-crate-root.md  
+  - 03-root.md  
+  - 04-root-metadata.md
+  - 05-metadata-descriptor.md
   - 06-cross-references.md
   - 07-data-entities.md
   - 08-contextual-entities.md
@@ -79,7 +79,8 @@ episodes:
   - 11-triples.md
   - 12-html-preview.md
   - 13-complete.md
-  - 14-next-steps.md
+  - 14-common-pitfalls.md
+  - 15-next-steps.md
 
 # Information for Learners
 learners:

episodes/01-introduction.md

@@ -23,16 +23,18 @@ exercises: 0
 
 ::::::::::::::::::::::::::::::::::::::: questions
 - How do I package data in a FAIR way?
+- How does an RO-Crate identify and describe its contents?
+- What is the difference between data entities and context entities?
+- What is the role of JSON-LD in RO-Crate?
 - 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?
+- How can I validate and visualize RO-Crate 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
+- Describe each part of the RO-Crate
+- Connect different parts of the RO-Crate using identifiers
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 
@@ -50,16 +52,19 @@ _Video: An overview of the RO-Crate concept and its implementations_ (see also [
 
 ## Tutorial walk-through
 
-In this tutorial, meant to be read along with the [RO-Crate specification](https://www.researchobject.org/ro-crate/1.1/),
+In this tutorial, meant to be read along with the [RO-Crate specification](https://www.researchobject.org/ro-crate/1.2/),
 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
+- FAIR: Findable, Accessible, Interoperable, Reusable; a set of principles for publishing research data and metadata.
+- FDO: FAIR Digital Object; a set of recommendations to improve findability, accessibility, interoperability, and reproducibility for any digital object.
+- 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.
+- PID: Persistent Identifier; a long-lasting reference to a digital object.
+- URI: Uniform Resource Identifier; a string of characters that identifies a resource.
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 ::::::::::::::::::::::::::::::::::::::: keypoints

episodes/02-folder-as-crate-root.md

@@ -67,7 +67,7 @@ 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).
+-- this is explored further in the specification's [appendix on JSON-LD](https://www.researchobject.org/ro-crate/1.2/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.
@@ -78,7 +78,7 @@ The `@type` keyword associates an object with a predefined type from the JSON-LD
 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/),
+and indeed most of the [RO-Crate specification](https://www.researchobject.org/ro-crate/specification/1.2/),
 specify which entities can be added to the `@graph` array. 
 
 

episodes/04-root.md episodes/03-root.mdepisodes/04-root.md renamed to episodes/03-root.md

@@ -14,8 +14,8 @@ exercises: 1
 
 ## 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):
+First we'll add an entity to the `@graph` array,
+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):
 
 ```json
 {
@@ -27,23 +27,8 @@ to describe the [RO-Crate Root](https://www.researchobject.org/ro-crate/1.1/root
 }
 ```
 
-:::::::::::::::::::::::::::::::::::::::: 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.
+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.
+This will be referenced from `ro-crate-metadata.json`, semantically marking the `crate1` folder as being the RO-Crate Root.
 
 
 :::::::::::::::::::::::::::::::::::::::: discussion
@@ -57,11 +42,38 @@ 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.
+see section [Root Data Entity](https://www.researchobject.org/ro-crate/specification/1.2/root-data-entity.html) for details.
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
+:::::::::::::::::::::::::::::::::::::::: challenge
+## Add an additional type
+
+1. Navigate the schema.org type list to find a subtype of `CreativeWork` that is suitable for a learning resource.
+2. Modify the root entity's `@type` to be an array.
+3. Add the type name for learning resource at the end of the array.
+
+:::::::::::::::  solution
+```json
+{
+   "@id": "./",
+   "@type": ["Dataset", "LearningResource"],
+   "hasPart": [ 
+     {"@id": "data.csv"} 
+   ],
+   "…": "…"
+}
+```
+:::::::::::::::::::::::::
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+The root has several metadata properties that describe the RO-Crate as a whole,
+considering it as a Research Object of collected resources.
+The section on [root data entity](https://www.researchobject.org/ro-crate/specification/1.2/root-data-entity.html)
+details further the required and recommended properties of the root `./`. 
+
 :::::::::::::::::::::::::::::::::::::::: 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
+- The root identifier is commonly just ./ for the current folder, but can be a URL
+- The root is always typed as a Dataset, but can have additional types
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 

episodes/05-root-metadata.md episodes/04-root-metadata.mdepisodes/05-root-metadata.md renamed to episodes/04-root-metadata.md

@@ -15,7 +15,7 @@ exercises: 4
 
 ## 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),
+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),
 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.
@@ -36,7 +36,7 @@ or another license of your choice:
   "hasPart": [ ],
   "name": "Example crate",
   "description": "I created this example by following the tutorial",
-  "datePublished": "2023-05-22T12:03:00+0100",
+  "datePublished": "2023-05-22",
   "license": { "@id": "http://spdx.org/licenses/CC0-1.0"}  
 }
 ```

episodes/03-metadata-descriptor.md episodes/05-metadata-descriptor.mdepisodes/03-metadata-descriptor.md renamed to episodes/05-metadata-descriptor.md

@@ -11,25 +11,25 @@ exercises: 2
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 ::::::::::::::::::::::::::::::::::::::: objectives
-- Add the first entity to the JSON-LD @graph
+- Add the next 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:
+The next 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"},
+    "conformsTo": {"@id": "https://w3id.org/ro/crate/1.2"},
     "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),
+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-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,
@@ -39,14 +39,52 @@ while the conformance declares which RO-Crate conventions of using those terms a
 
 ::::::::::::::::::::::::::::::::::::::: callout
 ## RO-Crate versions
-This tutorial is written for RO-Crate 1.1,
+This tutorial is written for RO-Crate 1.2,
 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.
+but check the [change log](https://www.researchobject.org/ro-crate/specification/1.2/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.
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
+:::::::::::::::::::::::::::::::::::::::: 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.
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
+
+Your RO-Crate metadata file should now containt two entities and look like this:
+
+```json
+{
+    "@context": "https://w3id.org/ro/crate/1.2/context",
+    "@graph": [
+        {
+            "@id": "./",
+            "@type": "Dataset",
+            "hasPart": [
+            ]
+        },
+        {
+            "@id": "ro-crate-metadata.json",
+            "@type": "CreativeWork",
+            "conformsTo": {"@id": "https://w3id.org/ro/crate/1.2"},
+            "about": {"@id": "./"}
+        }
+    ]
+}
+```
+
 ::::::::::::::::::::::::::::::::::::::: keypoints
 - The RO-Crate Metadata Descriptor describes the JSON-LD file itself
 - RO-Crate specifications are versioned

episodes/06-cross-references.md

@@ -4,28 +4,64 @@ teaching: 3
 exercises: 4
 ---
 :::::::::::::::::::::::::::::::::::::::: questions
-- How can I describe an entity further?
+- How does RO Crate use flattened JSON-LD?
 - How can I cross-reference different entities?
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::: objectives
-- Understand cross-references in flattened JSON-LD
+- Understand cross-references in RO Crate
 - Add a data entity reference from the root entity
-- Add another type to the root entity
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 
-
 ## About cross-references
 
+In many JSON documents, related information is nested inside parent objects. For example:
+```json
+{
+  "@id": "./",
+  "@type": "Dataset",
+  "name": "My Dataset",
+  "author": {
+    "@type": "Person",
+    "name": "Josiah Carberry",
+    "affiliation": "Brown University"
+  }
+}
+```
+
+While this is readable, it can become hard to manage when entities are reused or grow in complexity.
+
+In contrast, RO-Crate uses a flattened structure, where each entity is described just once, and connected using @id cross-references:
+
+```json
+[
+  {
+    "@id": "./",
+    "@type": "Dataset",
+    "name": "My Dataset",
+    "author": { "@id": "https://orcid.org/0000-0002-1825-0097" }
+  },
+  {
+    "@id": "https://orcid.org/0000-0002-1825-0097",
+    "@type": "Person",
+    "name": "Josiah Carberry",
+    "affiliation": "Brown University"
+  }
+]
+```
+
 In a RO-Crate Metadata Document,
 entities are cross-referenced using `@id` reference objects,
 rather than using deeply nested JSON objects.
-In short, this _flattened JSON-LD_ style (shown below) allows any entity to reference any other entity,
-and RO-Crate consumers can directly find all the descriptions of a given entity as a single JSON object. 
+In short, this _flattened JSON-LD_ style allows any entity to reference any other entity,
+and RO-Crate consumers can directly find all the descriptions of a given entity as a single JSON object.
+
+Think of @id as the entity’s “name tag”, you describe it once and refer to it anywhere in the graph.
 
 ![JSON block with id `ro-crate-metadata.json` has some attributes, `conformsTo` RO-Crate 1.2, and `about` referencing id `./`. In second JSON block with id <code>./</code> we see additional attributes such as its name and description.](fig/introduction-figure-1.svg){alt="showing RO-Crate Metadata descriptor's `about` property pointing at the RO-Crate Root entity with matching `@id`"}
 
+
 :::::::::::::::::::::::::::::::::::::::: challenge
 ## Add cross-reference to data entity
 
@@ -47,41 +83,10 @@ and add such a cross-reference to the file `data.csv` using the _property_ calle
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 
-The RO-Crate root is always typed `Dataset`,
-though `@type` may in some cases have additional types by using a JSON array instead of a single value.
-Most entities can have such more specific types,
-e.g. chosen from [schema.org type list](https://schema.org/docs/full.html).
-
-:::::::::::::::::::::::::::::::::::::::: challenge
-## Add an additional type
-
-1. Navigate the schema.org type list to find a subtype of `CreativeWork` that is suitable for a learning resource.
-2. Modify the root entity's `@type` to be an array.
-3. Add the type name for learning resource at the end of the array.
-
-:::::::::::::::  solution
-```json
-{
-   "@id": "./",
-   "@type": ["Dataset", "LearningResource"],
-   "hasPart": [ 
-     {"@id": "data.csv"} 
-   ],
-   "…": "…"
-}
-```
-:::::::::::::::::::::::::
-::::::::::::::::::::::::::::::::::::::::::::::::::
-
-The root has several metadata properties that describe the RO-Crate as a whole,
-considering it as a Research Object of collected resources.
-The section on [root data entity](https://www.researchobject.org/ro-crate/1.1/root-data-entity.html)
-details further the required and recommended properties of the root `./`. 
-
 :::::::::::::::::::::::::::::::::::::::: keypoints
 - The @id uniquely identifies the entity within the RO-Crate
-- The @id key is used for cross-referencing
-- Multiple types can be listed by using an array
+- Flattened JSON-LD helps keep each entity self-contained
+- Reuse of @id avoids duplication and enables linking
 ::::::::::::::::::::::::::::::::::::::::::::::::::