diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 98f48fbe..3821784f 100644 --- a/CODE_OF_CONDUCT.md +++ b/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. diff --git a/LICENSE.md b/LICENSE.md index 83ba4f1c..73a9ccb7 100644 --- a/LICENSE.md +++ b/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 diff --git a/config.yaml b/config.yaml index 7552f731..dea9f257 100644 --- a/config.yaml +++ b/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 diff --git a/episodes/01-introduction.md b/episodes/01-introduction.md index 91620282..84da662e 100644 --- a/episodes/01-introduction.md +++ b/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 diff --git a/episodes/02-folder-as-crate-root.md b/episodes/02-folder-as-crate-root.md index fe508e88..fc95368b 100644 --- a/episodes/02-folder-as-crate-root.md +++ b/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 -:::::::::::::::::::::::::::::::::::::::::::::::::: - +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/03-metadata-descriptor.md b/episodes/03-metadata-descriptor.md index 4dabf820..79d33d91 100644 --- a/episodes/03-metadata-descriptor.md +++ b/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 :::::::::::::::::::::::::::::::::::::::::::::::::: - - diff --git a/episodes/04-root.md b/episodes/04-root.md index e3938cc1..835410a9 100644 --- a/episodes/04-root.md +++ b/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 +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/05-root-metadata.md b/episodes/05-root-metadata.md index c3bff227..9329b10d 100644 --- a/episodes/05-root-metadata.md +++ b/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 -:::::::::::::::::::::::::::::::::::::::::::::::::: - - - +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/06-cross-references.md b/episodes/06-cross-references.md index 128aeaa1..41fd2d4e 100644 --- a/episodes/06-cross-references.md +++ b/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 ./ 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 +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/07-data-entities.md b/episodes/07-data-entities.md index 132a95e7..bf9fdb24 100644 --- a/episodes/07-data-entities.md +++ b/episodes/07-data-entities.md @@ -5,7 +5,7 @@ exercises: 2 --- :::::::::::::::::::::::::::::::::::::::: questions -- How do I describe the files in my RO-Crate? +- How do I describe the data files in my RO-Crate? :::::::::::::::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::: objectives @@ -26,7 +26,7 @@ a reference to the entity describing the file `data.csv`. RO-Crates can also contain data entities that are folders and Web resources, as well as non-File data like online databases --- see section on [data entities](https://www.researchobject.org/ro-crate/1.1/data-entities.html). +-- see section on [data entities](https://www.researchobject.org/ro-crate/specification/1.2/data-entities.html). :::::::::::::::::::::::::::::::::::::::::::::::::: We should now be able to follow the `@id` reference for the corresponding _data entity_ JSON block for our CSV file, @@ -61,7 +61,7 @@ and can be particularly important for less common file extensions frequently enc For more information on describing files and folders, including their recommended and required attributes, -see section on [data entities](https://www.researchobject.org/ro-crate/1.1/data-entitites.html). +see section on [data entities](https://www.researchobject.org/ro-crate/specification/1.2/data-entities.html). :::::::::::::::::::::::::::::::::::::::: challenge ## Override the licence @@ -85,10 +85,8 @@ see section on [data entities](https://www.researchobject.org/ro-crate/1.1/data- ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: + :::::::::::::::::::::::::::::::::::::::: keypoints - Data entities are files & folders within the root, as well as external Web references - Required properties for files are name and encodingFormat -- License can be overridden for particular data entities -:::::::::::::::::::::::::::::::::::::::::::::::::: - - +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/08-contextual-entities.md b/episodes/08-contextual-entities.md index be8064ad..fec069b0 100644 --- a/episodes/08-contextual-entities.md +++ b/episodes/08-contextual-entities.md @@ -5,8 +5,8 @@ exercises: 2 --- :::::::::::::::::::::::::::::::::::::::: questions -- How can I describe things in the world? -- How can I give details about licenses? +- How can I describe contextual information about how data was created? +- How can I represent an instrument used to generate a data file? :::::::::::::::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::: objectives @@ -19,12 +19,19 @@ exercises: 2 Entities that we have added under `hasPart` are considered _data entities_, while entities only referenced from those are considered _contextual entities_ --- they help explain the crate and its content. + +A contextual entity might describe: +- The software that processed the data +- The instrument that captured it +- The project that funded it +- The people that contributed to creating it + +These entities don’t contain data themselves but give semantic context to the data you’re describing. You may notice the subtle difference between a _data entity_ that is conceptually part of the RO-Crate and is file-like (containing bytes), while a _contextual entity_ is a representation of a real-life organization that can't be downloaded: following the URL, we would only get its _description_. -The section [contextual entities](https://www.researchobject.org/ro-crate/1.1/contextual-entities.html) +The section [contextual entities](https://www.researchobject.org/ro-crate/specification/1.2/contextual-entities.html) explores several of the entities that can be added to the RO-Crate to provide it with a **context**, for instance how to link to authors and their affiliations. Simplifying slightly, a data entity is referenced from `hasPart` in a `Dataset`, @@ -69,10 +76,40 @@ An additional exercise is to try to unify the two entities so that both use spdx remembering to update the corresponding `license` cross-references when changing the `@id`. However, not all licenses have a direct SPDX identifier. -:::::::::::::::::::::::::::::::::::::::: keypoints -- Contextual entities are not considered part of the crate -- Cross-references should be expanded as contextual entities -- It is recommended to provide a human-readable name for licenses +## Instrument details + +For example, the instrument used to capture weather data is not itself part of the dataset, but knowing what device created the measurements helps the data consumer interpret and validate the data. + +:::::::::::::::::::::::::::::::::::::::: challenge +## Add an instrument as a contextual entity + +In your data.csv entity, use instrument to reference the equipment used. +Then define the instrument entity in the @graph. + +::::::::::::::: solution +```json +{ + "@id": "data.csv", + "@type": "File", + "name": "Rainfall Katoomba 2022-02", + "description": "Rainfall data for Katoomba, NSW Australia February 2022", + "encodingFormat": "text/csv", + "instrument": { "@id": "https://example.org/instrument/ws-2000" } +}, +{ + "@id": "https://example.org/instrument/ws-2000", + "@type": "IndividualProduct", + "name": "WS-2000 Weather Station", + "description": "Automated weather station used to record temperature and rainfall data.", + "url": "https://example.org/instrument/ws-2000" +}, +``` +::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: +:::::::::::::::::::::::::::::::::::::::: keypoints +- Contextual entities are not considered part of the crate’s file structure +- Instruments, software, and projects can be described as contextual entities +- Contextual entities can provide provenance about data capture and processing +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/09-authorship.md b/episodes/09-authorship.md index d8975cab..714b6e6b 100644 --- a/episodes/09-authorship.md +++ b/episodes/09-authorship.md @@ -25,7 +25,7 @@ Moving back to the RO-Crate root `./`, let's specify who are the authors of the :::::::::::::::::::::::::::::::::::::::: challenge ## Add an author and affiliation -1. Add yourself as an [`author`](https://www.researchobject.org/ro-crate/1.1/contextual-entities.html#people) +1. Add yourself as an [`author`](https://www.researchobject.org/ro-crate/specification/1.2/contextual-entities.html#people) of the crate using the type `Person` 2. Include your preferred name. 3. If you don't have an [ORCID](https://orcid.org/), you may use either the URL of your main home page at your institution, @@ -54,7 +54,7 @@ Moving back to the RO-Crate root `./`, let's specify who are the authors of the ## Who can be authors of an RO-Crate? When we say someone is an author of a crate, -it means they have contributed something substansively to its content (typically the data). +it means they have contributed something substantively to its content (typically the data). Agreement on what is considered authorship on a dataset can be tricky; you may decide some people would be better represented as `contributor`. One advantage of RO-Crate is that authorship can be declared explicitly also on each data entity, @@ -118,4 +118,4 @@ as their names may not be globally unique. - Organization entities can be shared by multiple persons having the same affiliation - Crate authors made (some) of the crate's content - Publishers of an RO-Crate are typically organizations -:::::::::::::::::::::::::::::::::::::::::::::::::: +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/10-validating.md b/episodes/10-validating.md index 5d947824..ad1946cb 100644 --- a/episodes/10-validating.md +++ b/episodes/10-validating.md @@ -47,7 +47,7 @@ you should see output under _Expanded_ looking something like: ], "http://purl.org/dc/terms/conformsTo": [ { - "@id": "https://w3id.org/ro/crate/1.1" + "@id": "https://w3id.org/ro/crate/1.2" } ] }, @@ -76,14 +76,13 @@ Click on the circles to expand or collapse the details of the graph's different As the RO-Crate Metadata Document is valid JSON-LD it is also possible to process it using Linked Data technologies such as triple stores and SPARQL queries. It is beyond the scope of this tutorial to explain this aspect fully, -but interested readers should consider how to [handle relative URI references](https://www.researchobject.org/ro-crate/1.1/appendix/relative-uris.html). +but interested readers should consider how to [handle relative URI references](https://www.researchobject.org/ro-crate/specification/1.2/appendix/relative-uris.html). As an example, try the _Table_ button and notice that the entities with relative identifiers are not included. This is because when converting to RDF you need absolute URIs which do not readily exist when a crate is stored on disk, we've not decided where the crate is to be published yet. -::::::::::::::::::::::::::::::::::::::::keypoints +:::::::::::::::::::::::::::::::::::::::: keypoints - RO-Crate metadata files are valid JSON-LD - The JSON-LD Playground can do basic validation and visualization - Further use of RO-Crate as Linked Data is possible, but may require handling of relative URI references -:::::::::::::::::::::::::::::::::::::::::::::::::: - +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/11-triples.md b/episodes/11-triples.md index 6d77e4be..4762f751 100644 --- a/episodes/11-triples.md +++ b/episodes/11-triples.md @@ -19,13 +19,13 @@ e.g. to demonstrate how it might be described at a web resource, a 'base' URI is needed that will point to that resource, i.e. resolve as a page or file on the web. -Try to specify a hypothetical base URI by modifing the graph's `@context` within the [JSON-LD Playground](https://json-ld.org/playground/) +Try to specify a hypothetical base URI by modifying the graph's `@context` within the [JSON-LD Playground](https://json-ld.org/playground/) (do not modify the `ro-crate-metadata.json` on disk), and revisit the _Table_ rendering. ```json { "@context": [ - "https://w3id.org/ro/crate/1.1/context", + "https://w3id.org/ro/crate/1.2/context", { "@base": "arcp://uuid,deffa754-c764-4e04-aabf-e600c6200553/" } ], "…": "…" diff --git a/episodes/12-html-preview.md b/episodes/12-html-preview.md index e797447b..7233a2f8 100644 --- a/episodes/12-html-preview.md +++ b/episodes/12-html-preview.md @@ -11,7 +11,6 @@ exercises: 3 :::::::::::::::::::::::::::::::::::::::: objectives - Explore a HTML preview of an RO-Crate -- (Advanced) Try the ro-crate-html tool :::::::::::::::::::::::::::::::::::::::::::::::::: ## HTML preview @@ -37,7 +36,7 @@ Try navigating the [preview of the running example](../files/rainfall-1.2.1/ro-c ::::::::::::::: solution 1. CC BY-NC-SA 4.0 International 2. Brown University -3. The context, and for root dataset: existance, valid identifier, name, description, license and date published. +3. The context, and for root dataset: existence, valid identifier, name, description, license and date published. 4. The other entities were not checked, e.g. the `affiliation` of the author. ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -45,31 +44,19 @@ Try navigating the [preview of the running example](../files/rainfall-1.2.1/ro-c ## Advanced: Generating HTML preview -If you have [Node JS](https://nodejs.org/) installed, -you can install and try the [ro-crate-html](https://www.npmjs.com/package/ro-crate-html) tool on your `crate1` folder: +The [LDACA RO-Crate Playground](https://ro-crate.ldaca.edu.au/) is a web-based tool that lets you upload an RO-Crate and view a structured HTML summary of its metadata. -```bash -npm i -g ro-crate-html -rochtml crate1/ro-crate-metadata.json -``` +Navigate to the [LDACA RO-Crate Playground](https://ro-crate.ldaca.edu.au/) Click "Start Packaging", then click "Examples." From the examples list, click "Try it" for "sample-crate." +You will see a tab called "HTML Preview" that contains a preview of the RO-Crate metadata. -Or if you have [Docker](https://www.docker.com/), something like: +If you want to generate a preview of your own RO-Crate, you can click "Create New" to create a new RO-Crate, where you can upload your data files and add metadata. Once you have added your data files and metadata, click the "HTML Preview" button at the top of the page. -```bash -docker pull simleo/rochtml -docker run -v $(pwd):/crate -it simleo/rochtml -c ro-crate-preview_files /crate/ro-crate-metadata.json -``` +The tool will generate a preview of your RO-Crate, which you can then download as an HTML file. This preview will show the entities in your RO-Crate, including the root dataset, data files, licenses, authors, and any other contextual entities you have added. You can save the resulting HTML page using your browser’s “Save As” feature, or extract the generated preview for distribution. -The above will generate a `ro-crate-preview.html` file within your RO-Crate Root. -Experiment with modifying the Metadata file -and re-generating the HTML preview to see how your rendering differs from the [running example](../files/rainfall-1.2.1/ro-crate-preview.html). :::::::::::::::::::::::::::::::::::::::: keypoints - RO-Crate can be rendered into a HTML preview - RO-Crate previews tend to show each entity separately - The preview HTML can be added as part of the RO-Crate -:::::::::::::::::::::::::::::::::::::::::::::::::: - - - +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/13-complete.md b/episodes/13-complete.md index 9559d16f..a445e34f 100644 --- a/episodes/13-complete.md +++ b/episodes/13-complete.md @@ -25,12 +25,12 @@ The final RO-Crate Metadata Document constructed in this tutorial should look so ```json { - "@context": "https://w3id.org/ro/crate/1.1/context", + "@context": "https://w3id.org/ro/crate/1.2/context", "@graph": [ { "@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": "./"} }, { @@ -41,7 +41,7 @@ The final RO-Crate Metadata Document constructed in this tutorial should look so ], "name": "Example dataset for RO-Crate specification", "description": "Official rainfall readings for Katoomba, NSW 2022, Australia", - "datePublished": "2023-05-22T12:03:00+0100", + "datePublished": "2023-05-22", "license": {"@id": "http://spdx.org/licenses/CC0-1.0"}, "author": { "@id": "https://orcid.org/0000-0002-1825-0097" }, "publisher": {"@id": "https://ror.org/05gq02987"} @@ -52,28 +52,34 @@ The final RO-Crate Metadata Document constructed in this tutorial should look so "name": "Rainfall Katoomba 2022-02", "description": "Rainfall data for Katoomba, NSW Australia February 2022", "encodingFormat": "text/csv", - "license": {"@id": "https://creativecommons.org/licenses/by-nc-sa/4.0/"} + "license": {"@id": "https://creativecommons.org/licenses/by-nc-sa/4.0/"}, + "instrument": { "@id": "https://example.org/instrument/ws-2000" } + }, + { + "@id": "https://example.org/instrument/ws-2000", + "@type": "Individual Product", + "name": "WS-2000 Weather Station", + "description": "Automated weather station used to record temperature and rainfall data.", + "url": "https://example.org/instrument/ws-2000" }, { "@id": "https://creativecommons.org/licenses/by-nc-sa/4.0/", "@type": "CreativeWork", "name": "CC BY-NC-SA 4.0 International", "description": "Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International" - }, + }, { "@id": "http://spdx.org/licenses/CC0-1.0", "@type": "CreativeWork", "name": "CC0-1.0", "description": "Creative Commons Zero v1.0 Universal", "url": "https://creativecommons.org/publicdomain/zero/1.0/" - }, + }, { "@id": "https://orcid.org/0000-0002-1825-0097", "@type": "Person", "name": "Josiah Carberry", - "affiliation": { - "@id": "https://ror.org/05gq02987" - } + "affiliation": { "@id": "https://ror.org/05gq02987" } }, { "@id": "https://ror.org/05gq02987", @@ -90,5 +96,4 @@ The final RO-Crate Metadata Document constructed in this tutorial should look so :::::::::::::::::::::::::::::::::::::::: keypoints - A single RO-Crate lists all the entities - The order of entities in the @graph array is not important -:::::::::::::::::::::::::::::::::::::::::::::::::: - +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/14-next-steps.md b/episodes/14-next-steps.md index 2275cbf1..032f32c1 100644 --- a/episodes/14-next-steps.md +++ b/episodes/14-next-steps.md @@ -15,13 +15,18 @@ exercises: 0 You have completed making a basic RO-Crate. You may try any of the following: -- Add and describe additional data entities, - adding additional properties for [data entities](https://www.researchobject.org/ro-crate/1.1/data-entities.html) -- Follow the RO-Crate specification for additional [contextual entities](https://www.researchobject.org/ro-crate/1.1/contextual-entities.html) you can add to the crate -- Try briefly describing [provenance](https://www.researchobject.org/ro-crate/1.1/provenance.html) - or [software](https://www.researchobject.org/ro-crate/1.1/workflows.html) for any additional data entities you have added. - -:::::::::::::::::::::::::::::::::::::::: keypoints -- RO-Crate specification has further details, e.g. additional contextual entities -:::::::::::::::::::::::::::::::::::::::::::::::::: +- **Add Additional Properties**: Explore the RO-Crate specification for a wide range of properties to describe [data entities](https://www.researchobject.org/ro-crate/specification/1.2/data-entities.html) more comprehensively. + +- **More Contextual Entities**: Discover additional [contextual entities](https://www.researchobject.org/ro-crate/specification/1.2/contextual-entities.html) you can add to your crate, such as projects, grants, or related publications, to enrich the crate's context. + +- **Provenance and Software**: Learn how to describe the [provenance](https://www.researchobject.org/ro-crate/specification/1.2/provenance.html) (origin and history) of your data and include information about the [software](https://www.researchobject.org/ro-crate/specification/1.2/workflows.html) and workflows used in your research. + +- **RO-Crate Profiles**: Delve into [RO-Crate Profiles](https://www.researchobject.org/ro-crate/profiles.html), which are community-defined content checklists that extend the base specification to meet the specific needs of a domain or data type. Profiles impose conventions and may add domain specific terms/vocabularies, effectively making RO-Crates typed and machine-actionable for specific use cases. Examples include the [Workflow RO-Crate profile](https://about.workflowhub.eu/Workflow-RO-Crate/) used by WorkflowHub and the [Five Safes RO-Crate profile](https://trefx.uk/5s-crate/) for trusted workflow execution in Trusted Research Environments (TREs). + +- **FAIR Signposting**: Understand how [FAIR Signposting](https://catalogue.fair-impact.eu/resources/fair-signposting) can be used in combination with RO-Crate to guide machine agents through metadata space. + +- **Bioschemas**: Explore [Bioschemas](https://bioschemas.org/), a life sciences community initiative built on schema.org that defines domain-specific profiles (e.g., Dataset, ComputationalWorkflow, ChemicalSubstance). + +- **Community and Tools**: Join the open [RO-Crate community](https://www.researchobject.org/ro-crate/community) on GitHub, participate in drop-in sessions, and explore the tools and libraries for various programming languages. +- **Real-world Use Cases**: Explore how RO-Crates are being [used in practice](https://www.researchobject.org/ro-crate/use_cases) across various domains. \ No newline at end of file diff --git a/episodes/15-common-pitfalls.md b/episodes/15-common-pitfalls.md new file mode 100644 index 00000000..9e14902d --- /dev/null +++ b/episodes/15-common-pitfalls.md @@ -0,0 +1,125 @@ +--- +title: Avoiding Common pitfalls +teaching: 5 +exercises: 1 +--- + +:::::::::::::::::::::::::::::::::::::::: questions +- What are common mistakes to avoid when authoring RO-Crate packages? +- How can I troubleshoot errors in the metadata file? +:::::::::::::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: objectives +- Recognize common errors in RO-Crate metadata +- Review a checklist of requirements for RO-Crate structure and format +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## Introduction + +Creating RO-Crate packages by hand is a great way to understand their structure, but it’s easy to run into small issues that can break the crate or make it difficult to interpret. This section outlines the most frequent problems and how to avoid them. + +--- + +## Common Mistakes + +### 1. Invalid or malformed JSON + +- **Problem**: Forgetting commas, quotes, or brackets. +- **Fix**: Use an editor with JSON syntax highlighting (e.g., VS Code) and test your crate in the [JSON-LD Playground](https://json-ld.org/playground/). + +> Tip: Run your `ro-crate-metadata.json` through a JSON validator before uploading it anywhere. + +--- + +### 2. Missing `@context` or `@graph` + +- **Problem**: Forgetting to include the required top-level keys in the RO-Crate metadata file. +- **Fix**: Make sure every `ro-crate-metadata.json` starts like this: + +```json +{ + "@context": "https://w3id.org/ro/crate/1.2/context", + "@graph": [ /* your entities here */ ] +} +``` + +### 3. Using nested JSON instead of flat structure + +- **Problem**: Embedding full descriptions of related entities instead of referencing them with `@id`. +- **Fix**: Use cross-referencing. Define each entity once in the `@graph` array and refer to it using its `@id`. + +### 4. Repeating or mismatched @id values +- **Problem**: Accidentally defining two entities with the same @id, or referencing an entity with an @id that doesn’t exist in the `@graph`. +- **Fix**: Ensure every @id is unique and cross-references point to an entity defined in the metadata. + +### 5. Forgetting required metadata on key entities +- **Problem**: The root dataset doesn’t have `name` or `license`, or files are missing `@type`. +- **Fix**: Always include the required fields for the root (./) and for files: +```json +{ + "@id": "./", + "@type": "Dataset", + "name": "My Crate", + "description": "An example research dataset.", + "license": { "@id": "http://spdx.org/licenses/CC0-1.0" } +} +``` +:::::::::::::::::::::::::::::::::::::::: challenge +## Spot the errors +Here's an incorrect metadata example. Identify and fix the issues. + +```json +{ + "@context": "https://w3id.org/ro/crate/1.2/context", + "@graph": [ + { + "@id": "./", + "@type": "Folder", + "name": "Rainfall data", + "hasPart": { + "@id": "data.csv", + "name": "Rainfall Katoomba", + "encodingFormat": "comma separated values", + } + } + ] +} +``` +::::::::::::::: solution +1. The `@type` for the root should be "Dataset", not "Folder". +2. The hasPart value should reference an @id, not contain the full entity. +3. The data.csv entity should be defined separately in the @graph. +4. The encodingFormat should be a valid IANA media type (e.g., "text/csv"). +5. Missing required properties (description, datePublished, license) on the root dataset. +::::::::::::::::::::::::: +:::::::::::::::::::::::::::::::::::::::::::::::::: + +## RO-Crate validation tools + +The [RO-Crate Playground](https://ro-crate.ldaca.edu.au) and the [rocrate-validator](https://rocrate-validator.readthedocs.io/en/latest/) Python package can both be used to check for errors in your RO-Crate metadata. Each of them performs a different set of checks. + +:::::::::::::::::::::::::::::::::::::::: challenge + +Copy and paste your completed JSON-LD into the [RO-Crate Playground](https://ro-crate.ldaca.edu.au), then click "Validate". Are there any issues? + +:::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: challenge + +Install the [rocrate-validator](https://rocrate-validator.readthedocs.io/en/latest/) and run it on the command line against your completed RO-Crate: + +``` +rocrate-validator validate +``` + +Are there any issues? Are the results different to the RO-Crate Playground? + +:::::::::::::::::::::::::::::::::::::::: + +:::::::::::::::::::::::::::::::::::::::: keypoints +- Include a metadata descriptor with @id: "ro-crate-metadata.json" and @type: "CreativeWork" +- Ensure each referenced @id is also defined as an entity in @graph +- Use unique identifiers for each entity +- Ensure every entity has an @id and a meaningful @type +- Use tools like JSON validators and JSON-LD playgrounds to check your metadata +:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file diff --git a/episodes/files/rainfall-1.2.1/index.html b/episodes/files/rainfall-1.2.1/index.html index 392f50ea..544ac775 100644 --- a/episodes/files/rainfall-1.2.1/index.html +++ b/episodes/files/rainfall-1.2.1/index.html @@ -7,14 +7,14 @@