Merge pull request #10 from eScienceLab/ro-crate-1.3

RO Crate 1.3

Author: OliverWoolland

README.md

@@ -96,8 +96,8 @@ ROCrate crate;
 
 ### Create an Entity 
 
-To create an entity, instantiate the `Entity` class. You can must provide a type, 
-or list of types.
+To create an entity, instantiate the `Entity` class. You must provide a type, 
+or can provide a list of types.
 
 ```cpp
 // Single type
@@ -139,16 +139,28 @@ Entity alice({"Person"});
 crate.addEntity("#alice", alice);
 ```
 
+### Add additional context to an RO-Crate
+
+To add additional context to an RO-Crate, use the `addContext` method. The first 
+argument is the id of the context to add. The second is the context link itself 
+which must be non-empty.
+
+```cpp
+ROCrate crate;
+
+crate.addContext("txc", "https://purl.archive.org/language-data-commons/terms#");
+```
+
 ### Write out an RO-Crate
 
 To write out an RO-Crate, use the `writeOut` method. The argument is the path to 
 write the RO-Crate to. This will write out the `ro-crate-metadata.json` file.
 
 ```cpp
-crate.writeOut("./routput/");o
+crate.writeOut("./routput/ro-crate-metadata.json");
 ```
 
-## Explaination
+## Explanation
 
 These notes are mostly aimed at developers who want to understand the design of 
 this library, but may be of interest to users as well.

include/ro-crate.hpp

@@ -177,6 +177,15 @@ namespace rocrate {
      */
     Entity& getEntity(const std::string& id);
 
+    /**
+     * Adds a context entry to the RO-Crate's root metadata entity.
+     *
+     * @param key The context key to add.
+     * @param value The context value associated with the key.
+     * @throw std::invalid_argument if the key or value is empty.
+     */
+    void addContext(const std::string& key, const std::string& value);
+
     /**
      * Serializes the RO-Crate to a JSON file at the specified path.
      *
@@ -200,6 +209,7 @@ namespace rocrate {
     ) const;
 
     EntityRegister entities_;
+    std::map<std::string, std::string> context_;
   };
 
   inline ROCrate::ROCrate() {
@@ -210,7 +220,7 @@ namespace rocrate {
     Entity rootEntity({"CreativeWork"});
     rootEntity.set(
         "conformsTo",
-        "https://w3id.org/ro/crate/1.1",
+        "https://w3id.org/ro/crate/1.3",
         ValueType::Reference
     );
     addEntity("ro-crate-metadata.json", rootEntity);
@@ -249,12 +259,35 @@ namespace rocrate {
     return it->second;
   }
 
-  inline void ROCrate::writeOut(const std::string& path) {    
+  inline void ROCrate::addContext(const std::string& key, const std::string& value) {
+    // Validate the context
+    if (key.empty()) {
+      throw std::invalid_argument("Context key cannot be empty.");
+    }
+    if (value.empty()) {
+      throw std::invalid_argument("Context value cannot be empty.");
+    }
+
+    // Add the context entry to the RO-Crate's root metadata entity
+    context_[key] = value;
+  }
+
+  inline void ROCrate::writeOut(const std::string& path) {
+    // Create the JSON representation of the RO-Crate
     nlohmann::json outCrate = {
-        {"@context", "https://w3id.org/ro/crate/1.1/context"},
+        {"@context", "https://w3id.org/ro/crate/1.3/context"},
         {"@graph", nlohmann::json::array()}
     };
 
+    // Add the context entries to the JSON representation
+    if (!context_.empty()) {
+      outCrate["@context"] = nlohmann::json::array();
+      outCrate["@context"].push_back("https://w3id.org/ro/crate/1.3/context");
+      for (const auto& [key, value] : context_) {
+        outCrate["@context"].push_back({{key, value}});
+      }
+    }
+
     // Iterate over the entities, conver to json and append to the graph
     for (const auto& [id, entity] : entities_) {
       outCrate["@graph"].push_back(serializeEntity(id, entity));

tests/fixtures/example-with-file-author-location.json

@@ -0,0 +1,45 @@
+{ "@context": "https://w3id.org/ro/crate/1.3/context",
+  "@graph": [
+    {
+      "@type": "CreativeWork",
+      "@id": "ro-crate-metadata.json",
+      "conformsTo": {"@id": "https://w3id.org/ro/crate/1.3"},
+      "about": {"@id": "./"}
+    },  
+    {
+      "@id": "./",
+      "@type": "Dataset",
+      "name": "Example Dataset",
+      "datePublished": "2016-02-01",
+      "author": {"@id": "https://orcid.org/0000-0003-4953-0830"},
+      "license": "CC-BY",
+      "hasPart": [
+        {
+          "@id": "cp7glop.ai"
+        },
+        {
+          "@id": "lots_of_little_files/"
+        }
+      ]
+    },
+    {
+      "@id": "cp7glop.ai",
+      "@type": "File",
+      "name": "Diagram showing trend to increase",
+      "contentSize": "383766",
+      "description": "Illustrator file for Glop Pot",
+      "encodingFormat": "application/pdf"
+    },
+    {
+      "@id": "lots_of_little_files/",
+      "@type": "Dataset",
+      "name": "Too many files",
+      "description": "This directory contains many small files -- the name of the file is a date in YYYY-MM-DD.csv, each file contains daily temperature readings, sampled hourly for the Glop Pot cave."
+    },
+    {
+      "@id": "https://orcid.org/0000-0003-4953-0830",
+      "@type": "Person",
+      "name": "Michael Lake"
+    }
+  ]
+}

tests/fixtures/example-with-file-directory.json

@@ -1,9 +1,9 @@
-{ "@context": "https://w3id.org/ro/crate/1.1/context",
+{ "@context": "https://w3id.org/ro/crate/1.3/context",
   "@graph": [
     {
         "@type": "CreativeWork",
         "@id": "ro-crate-metadata.json",
-        "conformsTo": {"@id": "https://w3id.org/ro/crate/1.1"},
+        "conformsTo": {"@id": "https://w3id.org/ro/crate/1.3"},
         "about": {"@id": "./"}
   },  
   {
@@ -16,7 +16,7 @@
       {
         "@id": "https://zenodo.org/record/3541888/files/ro-crate-1.0.0.pdf"
       }
-      ]
+    ]
   },
   {
     "@id": "survey-responses-2019.csv",

tests/fixtures/example-with-web-resources.json

@@ -1,27 +1,36 @@
-{ "@context": "https://w3id.org/ro/crate/1.1/context", 
+{ "@context": "https://w3id.org/ro/crate/1.3/context", 
   "@graph": [
 
  {
-    "@type": "CreativeWork",
     "@id": "ro-crate-metadata.json",
-    "conformsTo": {"@id": "https://w3id.org/ro/crate/1.1"},
-    "about": {"@id": "./"}
+    "@type": "CreativeWork",
+    "about": {"@id": "./"},
+    "conformsTo": {"@id": "https://w3id.org/ro/crate/1.3"}
  },  
  {
     "@id": "./",
-    "identifier": "https://doi.org/10.4225/59/59672c09f4a4b",
     "@type": "Dataset",
+    "identifier": {"@id": "https://doi.org/10.4225/59/59672c09f4a4b"},
+    "cite-as": "https://doi.org/10.4225/59/59672c09f4a4b",
     "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/"}
+    "license": {"@id": "https://creativecommons.org/licenses/by-nc-sa/3.0/au/"},
+    "creditText": "Agar, M. et al., 2017. Data supporting \"Effects of facilitated family case conferencing for advanced dementia: A cluster randomised clinical trial\". https://doi.org/10.4225/59/59672c09f4a4b"
+ },
+ {
+    "@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)"
  },
  {
-  "@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)"
- }
+    "@id": "https://doi.org/10.4225/59/59672c09f4a4b",
+    "@type": "PropertyValue",
+    "propertyID": "https://registry.identifiers.org/registry/doi",
+    "value": "doi:10.4225/59/59672c09f4a4b",
+    "url": "https://doi.org/10.4225/59/59672c09f4a4b"
+  }
  ]
 }

tests/fixtures/minimal-example-of-ro-crate.json

@@ -0,0 +1,50 @@
+{ "@context": [
+    "https://w3id.org/ro/crate/1.3/context",
+    {"txc": "https://purl.archive.org/language-data-commons/terms#"}
+  ],
+  "@graph": [
+    {
+      "@id": "ro-crate-metadata.json",
+      "@type": "CreativeWork",
+      "description": "RO-Crate Metadata File Descriptor (this file)",
+      "conformsTo": {"@id": "https://w3id.org/ro/crate/1.3"},
+      "about": {"@id": "./"}
+    },
+    {
+      "@id": "./",
+      "@type": "Dataset",
+      "description": "This is an experimental language data ontology based on OLAC terms for use in the ATAP and LDaCA projects",
+      "name": "Language Data Ontology",
+      "mentions": [
+        {"@id": "txc:Annotation"},
+        {"@id": "txc:CollectionEvent"}
+      ]
+    },
+    {
+      "@id": "txc:Annotation",
+      "@type": "rdfs:Class",
+      "name": "Annotation",
+      "sameAs": "http://www.language-archives.org/REC/type-20020628.html#annotation",
+      "rdfs:comment": "The resource includes information which annotates some other linguistic record.",
+      "rdfs:label": "Annotation",
+      "rdfs:subClassOf": {
+        "@id": "schema:CreativeWork"
+      }
+    },
+    {
+      "@id": "txc:CollectionEvent",
+      "@type": "rdfs:Class",
+      "name": "CollectionEvent",
+      "rdfs:comment": "A description of an event at which one or more PrimaryTexts were captured, e.g. as video or audio",
+      "rdfs:label": "CollectionEvent",
+      "rdfs:subClassOf": [
+        {
+          "@id": "schema:Event"
+        },
+        {
+          "@id": "schema:CreateAction"
+        }
+      ]
+    }
+  ]
+}