Update references to 1.2 spec, re-ordering, content updates

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 conduct@researchobject.org to report any Code of Conduct concerns.

LICENSE.md

@@ -10,7 +10,7 @@
 
 Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
 
 http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. 
 
@@ -21,7 +21,7 @@
 * Adaptation to Galaxy Training Material rendering
 * Explicit links to RO-Crate specifications
 * Example changed to different organization and license
-* Modiied for Carpentries style
+* Modified for Carpentries style
 
 # Examples
 
@@ -31,6 +31,6 @@
 # Trademarks
 
 "Software Carpentry" and "Data Carpentry" and their respective logos
 are registered trademarks of [Community Initiatives][CI].
 
 [ci]: http://communityin.org/

config.yaml

@@ -68,9 +68,9 @@ contact: "ro-crate@researchobject.org"
 episodes:
   - 01-introduction.md
   - 02-folder-as-crate-root.md
-  - 03-metadata-descriptor.md
   - 04-root.md
   - 05-root-metadata.md
+  - 03-metadata-descriptor.md
   - 06-cross-references.md
   - 07-data-entities.md
   - 08-contextual-entities.md
@@ -79,6 +79,7 @@ episodes:
   - 11-triples.md
   - 12-html-preview.md
   - 13-complete.md
+  - 15-common-pitfalls.md
   - 14-next-steps.md
 
 # Information for 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

@@ -39,7 +39,7 @@
 
 ```json
 {
-  "@context": "https://w3id.org/ro/crate/1.1/context",
+  "@context": "https://w3id.org/ro/crate/1.2/context",
   "@graph": [
 
   ]
@@ -56,7 +56,7 @@
 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.
+explained in the next section.
 
 
 ## JSON-LD preamble
@@ -64,10 +64,10 @@
 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).
+-- 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 @@
 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. 
 
 
@@ -88,5 +88,4 @@
 - 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
-::::::::::::::::::::::::::::::::::::::::::::::::::
-
+::::::::::::::::::::::::::::::::::::::::::::::::::

episodes/03-metadata-descriptor.md

@@ -17,32 +17,32 @@ exercises: 2
 
 ## 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:
+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:
 
 
 ```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-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.
+which is conforming to (`conformsTo`) the RO-Crate specification version 1.2.
 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,
+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.
 ::::::::::::::::::::::::::::::::::::::::::::::::::

episodes/04-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,36 @@ 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.
+as you will see in the next section.
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
-:::::::::::::::::::::::::::::::::::::::: 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
+:::::::::::::::::::::::::::::::::::::::: 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.
+In the next section we will cover 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 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

@@ -15,7 +15,7 @@
 
 ## 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 @@
   "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"}  
 }
 ```
@@ -49,7 +49,7 @@
 ## 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_. 
@@ -68,9 +68,6 @@
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::: keypoints
-- Name, description, date published and license are required for the RO-Crate Root"
+- Name, description, date published and license are required for the RO-Crate Root
 - RO-Crate allows multiple licenses for different parts
-::::::::::::::::::::::::::::::::::::::::::::::::::
-
-
-
+::::::::::::::::::::::::::::::::::::::::::::::::::

episodes/06-cross-references.md

@@ -9,23 +9,59 @@ exercises: 4
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::: 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,8 @@ 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
+::::::::::::::::::::::::::::::::::::::::::::::::::