Contextual entities

Overview

Teaching: 2 min
Exercises: 2 min

Questions

• How can I describe things in the world?

• How can I give details about licenses?

Objectives

• Understand the difference between contextual and data entities

• Add a contextual entity to the RO-Crate

Contextual entities

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.

Adding entities to the JSON array

You may have noticed we’re adding incrementally to the @graph array. It is important to remember the , 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 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 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 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, while a contextual entity is referenced using any other defined property.

Detailing licenses

We have previously declared two different license cross-references. While following the URLs in this case explain the licenses well, it is also best practice to include a very brief summary of contextual entities in the RO-Crate Metadata Document. This is more important if the cross-reference do not use a permalink and may change over time. As a minimum, each referenced entity should have a @type and name property. It is also possible to add url for more information

Add licence entities

Add a contextual entity for each of the two licenses, see the licensing section for details:

Solution

{
    "@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/"
},  

An additional exercise is to try to unify the two entites so that both use spdx identifiers, remembering to update the corresponding license cross-references when changing the @id. However, not all licenses have a direct SPDX identifier.

Key Points

• 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