Root Data Entity

Table of contents

1. RO-Crate Metadata File Descriptor
   1. Finding the Root Data Entity
   2. Purpose of Metadata File
2. Direct properties of the Root Data Entity
3. Minimal example of RO-Crate

The Root Data Entity is a Dataset that represent the RO-Crate as a whole; a Research Object that includes the Data Entities and the related Contextual Entities.

As explained in section RO-Crate structure, the RO-Crate description is stored as JSON-LD in the RO-Crate Metadata File ro-crate-metadata.json in the RO-Crate root directory.

RO-Crate Metadata File Descriptor

The RO-Crate JSON-LD MUST contain a self-describing RO-Crate Metadata File Descriptor with the @id value ro-crate-metadata.json (or ro-crate-metadata.jsonld in legacy crates) and @type CreativeWork. This descriptor MUST have an about property referencing the Root Data Entity, which SHOULD have an @id of ./.

{ "@context": "https://w3id.org/ro/crate/1.1/context", 
  "@graph": [
    {
        "@type": "CreativeWork",
        "@id": "ro-crate-metadata.json",
        "conformsTo": {"@id": "https://w3id.org/ro/crate/1.1"},
        "about": {"@id": "./"}
    },
    
    {
      "@id": "./",
      "@type": "Dataset",
      ...
    }
  ]
}

The conformsTo of the RO-Crate Metadata File Descriptor SHOULD be a versioned permalink URI of the RO-Crate specification that the RO-Crate JSON-LD conforms to. The URI SHOULD start with https://w3id.org/ro/crate/.

Finding the Root Data Entity

Consumers processing the RO-Crate as an JSON-LD graph can thus reliably find the Root Data Entity by following this algorithm:

1. For each entity in @graph array
2. ..if the conformsTo property is a URI that starts with https://w3id.org/ro/crate/
3. ….from this entity’s about object keep the @id URI as variable root
4. For each entity in @graph array
5. .. if the entity has an @id URI that matches root return it

See also the appendix on finding RO-Crate Root in RDF triple stores.

Purpose of Metadata File

To ensure a base-line interoperability between RO-Crates, and for an RO-Crate to be considered a Valid RO-Crate, a minimum set of metadata is required for the Root Data Entity. As stated earlier the RO-Crate Metadata File is not an exhaustive manifest or inventory, that is, it does not necessarily list or describe all files in the package. For this reason, there are no minimum metadata requirements in terms of describing Data Entities (files and folders) other than the Root Data Entity. Extensions of RO-Crate dealing with specific types of dataset may put further constraints or requirements of metadata beyond the Root Data Entity (see the appendix Extending RO-Crate).

The RO-Crate Metadata File Descriptor MAY contain information such as licensing for the RO-Crate Metadata File so metadata can be licensed separately from Data.

The table below outlines the properties that the Root Data Entity MUST have to be minimally valid and additionally highlights properties required to meet other common use-cases:

Direct properties of the Root Data Entity

The Root Data Entity MUST have the following properties:

• @type: MUST be Dataset
• @id: MUST end with / and SHOULD be the string ./
• name: SHOULD identify the dataset to humans well enough to disambiguate it from other RO-Crates
• description: SHOULD further elaborate on the name to provide a summary of the context in which the dataset is important.
• datePublished: MUST be a string in ISO 8601 date format and SHOULD be specified to at least the precision of a day, MAY be a timestamp down to the millisecond.
• license: SHOULD link to a Contextual Entity in the RO-Crate Metadata File with a name and description. MAY have a URI (eg for Creative Commons or Open Source licenses). MAY, if necessary be a textual description of how the RO-Crate may be used.

These requirements are stricter than those published for Google Dataset Search which requires a Dataset to have a name and description,

The properties above are not sufficient to generate a DataCite citation. Advice on integrating with DataCite will be provided in a future version of this specification, or as an implementation guide.

Minimal example of RO-Crate

The following RO-Crate Metadata File represents a minimal description of an RO-Crate.

{ "@context": "https://w3id.org/ro/crate/1.1/context", 
  "@graph": [

 {
    "@type": "CreativeWork",
    "@id": "ro-crate-metadata.json",
    "conformsTo": {"@id": "https://w3id.org/ro/crate/1.1"},
    "about": {"@id": "./"}
 },  
 {
    "@id": "./",
    "identifier": "https://doi.org/10.4225/59/59672c09f4a4b",
    "@type": "Dataset",
    "datePublished": "2017",
    "name": "Data files associated with the manuscript:Effects of facilitated family case conferencing for ...",
    "description": "Palliative care planning for nursing home residents with advanced dementia ...",
    "license": {"@id": "https://creativecommons.org/licenses/by-nc-sa/3.0/au/"}
 },
 {
  "@id": "https://creativecommons.org/licenses/by-nc-sa/3.0/au/",
  "@type": "CreativeWork",
  "description": "This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Australia License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/au/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.",
  "identifier": "https://creativecommons.org/licenses/by-nc-sa/3.0/au/",
  "name": "Attribution-NonCommercial-ShareAlike 3.0 Australia (CC BY-NC-SA 3.0 AU)"
 }
 ]
}