Merge pull request #9 from a-mile/acm_rep_updates

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

Author: elichad

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.

LICENSE.md

@@ -21,7 +21,7 @@ This tutorial has been adapted from the revised [RO-Crate introduction for 1.2](
 * 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
 

config.yaml

@@ -68,9 +68,9 @@ contact: "[email protected]"
 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 @@ then add the following JSON:
 
 ```json
 {
-  "@context": "https://w3id.org/ro/crate/1.1/context",
+  "@context": "https://w3id.org/ro/crate/1.2/context",
   "@graph": [
 
   ]
@@ -56,7 +56,7 @@ 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.
+explained in the next section.
 
 
 ## JSON-LD preamble
@@ -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. 
 
 
@@ -88,5 +88,4 @@ specify which entities can be added to the `@graph` array.
 - 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,48 @@ 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
+
+## 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.	
+::::::::::::::::::::::::::::::::::::::::::::::::::
+
 ::::::::::::::::::::::::::::::::::::::: 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.
 ::::::::::::::::::::::::::::::::::::::::::::::::::
@@ -52,5 +68,3 @@ may still be subject to changes and should only be used with caution.
 - RO-Crate specifications are versioned
 - The version of RO-Crate is indicated using the conformsTo property
 ::::::::::::::::::::::::::::::::::::::::::::::::::
-
-

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 @@ 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"}  
 }
 ```
@@ -68,9 +68,6 @@ It is still recommended to choose an overall Crate license that can legally appl
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::: 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
-::::::::::::::::::::::::::::::::::::::::::::::::::
-
-
-
+::::::::::::::::::::::::::::::::::::::::::::::::::