ro-crate 0.4.9 → 0.4.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88f4e08570b547ac985a759af19d619747dd78a9001cd7994f314a42c014e001
-  data.tar.gz: e3711f54d12c1b4d6b1d68d16923dd051ae2b3a01a28a1d1e155a471bb84bfab
+  metadata.gz: 364757350da7d275b02def348bfd97782ad0ae31728c44f0691bc084e4d94ac9
+  data.tar.gz: 6b56ae58b682a4618dcb92ca78cbae720426316bc8ec50b9377fb9fda8ec9137
 SHA512:
-  metadata.gz: 2a468ad85761945fc782b5ccb6943e4d1b53c7bb528dba59ed19f93ab2af08017f212d93bf47f9af983b6f00fd304dd1b2edfaef5e096f04ffdb181fd75352e5
-  data.tar.gz: 89edb2f44a6842a7409c2e3107e76b3c401533738c32e6c18faecc6c9c29e6fd71a0d06fbe20f67fdec62564d00b3c168da36b29662ab8badfe652d923b7ab58
+  metadata.gz: a2b14f9c64528476a18f84d0292311484e975a3dc6085c00c94f5dac8d84fa144e91bb6138c876db4a4079aeec4222eb6a1f91458e2ef0260defa9d3a0a42d57
+  data.tar.gz: b56d257868b7cb94f341e844223d14988c280fff34bb54dd1a676d47681d96afc8193ebb60a22eecfef7e96dc0d2ce03ed1571190a1717fbe56d1b80ed579053

data/Gemfile.lock

@@ -1,31 +1,31 @@
 PATH
   remote: .
   specs:
-    ro-crate (0.4.9)
-      addressable (~> 2.7.0)
+    ro-crate (0.4.13)
+      addressable (>= 2.7, < 2.9)
       rubyzip (~> 2.0.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.7.0)
+    addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
-    docile (1.3.1)
+    docile (1.3.5)
     hashdiff (1.0.1)
-    json (2.3.1)
-    power_assert (0.4.1)
-    public_suffix (4.0.3)
+    power_assert (1.1.3)
+    public_suffix (4.0.6)
     rake (13.0.0)
     rubyzip (2.0.0)
     safe_yaml (1.0.5)
-    simplecov (0.16.1)
+    simplecov (0.21.2)
       docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
-    test-unit (3.2.3)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.2)
+    test-unit (3.2.9)
       power_assert
     webmock (3.8.3)
       addressable (>= 2.3.6)
@@ -39,7 +39,7 @@ PLATFORMS
 DEPENDENCIES
   rake (~> 13.0.0)
   ro-crate!
-  simplecov (~> 0.16.1)
+  simplecov (~> 0.21.2)
   test-unit (~> 3.2.3)
   webmock (~> 3.8.3)
   yard (~> 0.9.25)

data/README.md

@@ -1,5 +1,7 @@
 # ro-crate-ruby
 
+![Tests](https://github.com/ResearchObject/ro-crate-ruby/actions/workflows/tests.yml/badge.svg)
+
 This is a WIP gem for creating, manipulating and reading RO-Crates (conforming to version 1.1 of the specification).
 
 * RO-Crate - https://researchobject.github.io/ro-crate/
@@ -17,6 +19,43 @@ and run `bundle install`.
 
 ## Usage
 
+This gem consists a hierarchy of classes to model RO-Crate "entities": the crate itself, data entities 
+(files and directory) and contextual entities (with a limited set of specializations, such as `ROCrate::Person`). 
+They are all descendents of the `ROCrate::Entity` class, with the `ROCrate::Crate` class representing the crate itself. 
+
+The `ROCrate::Reader` class handles reading of RO-Crates into the above model, from a Zip file or directory.
+
+The `ROCrate::Writer` class can write out an `ROCrate::Crate` instance into a Zip file or directory.
+
+**Note:** for performance reasons, the gem is currently not linked-data aware and will allow you to set properties that 
+are not semantically valid.
+
+### Entities
+Entities correspond to entries in the `@graph` of the RO-Crate's metadata JSON-LD file. Each entity class is 
+basically a wrapper around a set of JSON properties, with some convenience methods for getting/setting some 
+commonly used properties (`crate.name = "My first crate"`).
+ 
+These convenience getter/setter methods will automatically handle turning objects into references and adding them to the 
+`@graph` if necessary.
+
+##### Getting/Setting Arbitrary Properties of Entities
+As well as using the pre-defined getter/setter methods, you can get/set arbitrary properties like so.
+
+To set the "creativeWorkStatus" property of the RO-Crate itself to a string literal:
+```ruby
+crate['creativeWorkStatus'] = 'work-in-progress'
+```
+
+If you want to reference other entities in the crate, you can get a JSON-LD reference from an entity object by using the `reference` method:
+```ruby
+joe = crate.add_person('joe', { name: 'Joe Bloggs' }) # Add the entity to the @graph
+crate['copyrightHolder'] = joe.reference # Reference the entity from the "copyrightHolder" property
+```
+and to resolve those references back to the object, use the `dereference` method:
+```ruby
+joe = crate['copyrightHolder'].dereference
+```
+
 ### Documentation
 
 [Click here for API documentation](https://www.researchobject.org/ro-crate-ruby/).

data/lib/ro_crate/model/crate.rb

@@ -25,6 +25,15 @@ module ROCrate
       super(self, nil, id, properties)
     end
 
+    ##
+    # Lookup an Entity using the given ID (in this Entity's crate).
+    #
+    # @param id [String] The ID to query.
+    # @return [Entity, nil]
+    def dereference(id)
+      entities.detect { |e| e.canonical_id == crate.resolve_id(id) } if id
+    end
+
     ##
     # Create a new file and add it to the crate.
     #
@@ -168,6 +177,15 @@ module ROCrate
       @preview ||= ROCrate::Preview.new(self)
     end
 
+    ##
+    # Set the RO-Crate preview file
+    # @param preview [Preview] the preview to set.
+    #
+    # @return [Preview]
+    def preview=(preview)
+      @preview = claim(preview)
+    end
+
     ##
     # All the entities within the crate. Includes contextual entities, data entities, the crate itself and its metadata file.
     #
@@ -220,32 +238,56 @@ module ROCrate
       entity.class.new(crate, entity.id, entity.raw_properties)
     end
 
-    alias_method :own_entries, :entries
+    alias_method :own_payload, :payload
     ##
-    # # The RO-Crate's "payload" of the crate - a map of all the files/directories contained in the RO-Crate, where the
-    # key is the destination path within the crate and the value is an Entry where the source data can be read.
+    # The file payload of the RO-Crate - a map of all the files/directories contained in the RO-Crate, where the
+    # key is the path relative to the crate's root, and the value is an Entry where the source data can be read.
     #
     # @return [Hash{String => Entry}>]
-    def entries
+    def payload
       # Gather a map of entries, starting from the crate itself, then any directory data entities, then finally any
       # file data entities. This ensures in the case of a conflict, the more "specific" data entities take priority.
-      entries = own_entries
+      entries = own_payload
       non_self_entities = default_entities.reject { |e| e == self }
       sorted_entities = (non_self_entities | data_entities).sort_by { |e| e.is_a?(ROCrate::Directory) ? 0 : 1 }
 
       sorted_entities.each do |entity|
-        entity.entries.each do |path, entry|
+        entity.payload.each do |path, entry|
           entries[path] = entry
         end
       end
 
       entries
     end
+    alias_method :entries, :payload
 
     def get_binding
       binding
     end
 
+    ##
+    # Remove the entity from the RO-Crate.
+    #
+    # @param entity [Entity, String] The entity or ID of an entity to remove from the crate.
+    # @param remove_orphaned [Boolean] Should linked contextual entities also be removed from the crate they are left
+    #                                   dangling (nothing else is linked to them)?
+    #
+    # @return [Entity, nil] The entity that was deleted, or nil if nothing was deleted.
+    def delete(entity, remove_orphaned: true)
+      entity = dereference(entity) if entity.is_a?(String)
+      return unless entity
+
+      deleted = data_entities.delete(entity) || contextual_entities.delete(entity)
+
+      if deleted && remove_orphaned
+        crate_entities = crate.linked_entities(deep: true)
+        to_remove = (entity.linked_entities(deep: true) - crate_entities)
+        to_remove.each(&:delete)
+      end
+
+      deleted
+    end
+
     private
 
     def full_entry_path(relative_path)

data/lib/ro_crate/model/data_entity.rb

@@ -3,6 +3,8 @@ module ROCrate
   # A class to represent a "Data Entity" within an RO-Crate.
   # Data Entities are the actual physical files and directories within the Crate.
   class DataEntity < Entity
+    properties(%w[name contentSize dateModified encodingFormat identifier sameAs author])
+
     def self.format_local_id(id)
       super.chomp('/')
     end
@@ -13,8 +15,6 @@ module ROCrate
     # @return [Class]
     def self.specialize(props)
       type = props['@type']
-      id = props['@id']
-      abs = URI(id)&.absolute? rescue false
       type = [type] unless type.is_a?(Array)
       if type.include?('Dataset')
         ROCrate::Directory
@@ -24,12 +24,13 @@ module ROCrate
     end
 
     ##
-    # A map of all the files/directories associated with this DataEntity.
+    # The payload of all the files/directories associated with this DataEntity, mapped by their relative file path.
     #
     # @return [Hash{String => Entry}>] The key is the location within the crate, and the value is an Entry.
-    def entries
+    def payload
       {}
     end
+    alias_method :entries, :payload
 
     ##
     # A disk-safe filepath based on the ID of this DataEntity.

data/lib/ro_crate/model/directory.rb

@@ -2,8 +2,6 @@ module ROCrate
   ##
   # A data entity that represents a directory of potentially many files and subdirectories (or none).
   class Directory < DataEntity
-    properties(%w[name contentSize dateModified encodingFormat identifier sameAs])
-
     def self.format_local_id(id)
       super + '/'
     end
@@ -30,11 +28,11 @@ module ROCrate
     end
 
     ##
-    # The "payload" of this directory - a map of all the files/directories, where the key is the destination path
+    # The payload of this directory - a map of all the files/directories, where the key is the destination path
     # within the crate and the value is an Entry where the source data can be read.
     #
     # @return [Hash{String => Entry}>]
-    def entries
+    def payload
       entries = {}
       entries[filepath.chomp('/')] = @entry if @entry
 

data/lib/ro_crate/model/entity.rb

@@ -129,16 +129,26 @@ module ROCrate
     # @param id [String] The ID to query.
     # @return [Entity, nil]
     def dereference(id)
-      crate.entities.detect { |e| e.canonical_id == crate.resolve_id(id) } if id
+      crate.dereference(id)
     end
-
     alias_method :get, :dereference
 
+    ##
+    # Remove this entity from the RO-Crate.
+    #
+    # @param remove_orphaned [Boolean] Should linked contextual entities also be removed from the crate (if nothing else is linked to them)?
+    #
+    # @return [Entity, nil] This entity, or nil if nothing was deleted.
+    def delete(remove_orphaned: true)
+      crate.delete(self, remove_orphaned: remove_orphaned)
+    end
+
     def id
       @properties['@id']
     end
 
     def id=(id)
+      @canonical_id = nil
       @properties['@id'] = self.class.format_id(id)
     end
 
@@ -190,13 +200,13 @@ module ROCrate
     #
     # @return [Addressable::URI]
     def canonical_id
-      crate.resolve_id(id)
+      @canonical_id ||= crate.resolve_id(id)
     end
 
     ##
     # Is this entity local to the crate or an external reference?
     #
-    # @return [boolean]
+    # @return [Boolean]
     def external?
       crate.canonical_id.host != canonical_id.host
     end
@@ -226,6 +236,33 @@ module ROCrate
       @properties.has_type?(type)
     end
 
+    ##
+    # Gather a list of entities linked to this one through its properties.
+    # @param deep [Boolean] If false, only consider direct links, otherwise consider transitive links.
+    # @param linked [Hash{String => Entity}] Discovered entities, mapped by their ID, to avoid loops when recursing.
+    # @return [Array<Entity>]
+    def linked_entities(deep: false, linked: {})
+      properties.each do |key, value|
+        value = [value] if value.is_a?(JSONLDHash)
+
+        if value.is_a?(Array)
+          value.each do |v|
+            if v.is_a?(JSONLDHash) && !linked.key?(v['@id'])
+              entity = v.dereference
+              linked[entity.id] = entity if entity
+              if deep
+                entity.linked_entities(deep: true, linked: linked).each do |e|
+                  linked[e.id] = e
+                end
+              end
+            end
+          end
+        end
+      end
+
+      linked.values.compact
+    end
+
     private
 
     def default_properties

data/lib/ro_crate/model/entry.rb

@@ -14,10 +14,10 @@ module ROCrate
     end
 
     ##
-    # Write the source to the destination via a buffer.
+    # Write the entry's source to the destination via a buffer.
     #
     # @param dest [#write] An IO-like destination to write to.
-    def write(dest)
+    def write_to(dest)
       input = source
       input = input.open('rb') if input.is_a?(Pathname)
       while (buff = input.read(4096))

data/lib/ro_crate/model/file.rb

@@ -2,14 +2,12 @@ module ROCrate
   ##
   # A data entity that represents a single file.
   class File < DataEntity
-    properties(%w[name contentSize dateModified encodingFormat identifier sameAs])
-
     ##
     # Create a new ROCrate::File. PLEASE NOTE, the new file will not be added to the crate. To do this, call
     # Crate#add_data_entity, or just use Crate#add_file.
     #
     # @param crate [Crate] The RO-Crate that owns this file.
-    # @param source [String, Pathname, ::File, #read, URI, nil] The source on the disk (or on the internet if a URI) where this file will be read.
+    # @param source [String, Pathname, ::File, URI, nil, #read] The source on the disk (or on the internet if a URI) where this file will be read.
     # @param crate_path [String] The relative path within the RO-Crate where this file will be written.
     # @param properties [Hash{String => Object}] A hash of JSON-LD properties to associate with this file.
     def initialize(crate, source, crate_path = nil, properties = {})
@@ -58,7 +56,7 @@ module ROCrate
     # (for compatibility with Directory#entries)
     #
     # @return [Hash{String => Entry}>] The key is the location within the crate, and the value is an Entry.
-    def entries
+    def payload
       remote? ? {} : { filepath => source }
     end
 

data/lib/ro_crate/model/metadata.rb

@@ -17,7 +17,15 @@ module ROCrate
     # @return [String] The rendered JSON-LD as a "prettified" string.
     def generate
       graph = crate.entities.map(&:properties).reject(&:empty?)
-      JSON.pretty_generate('@context' => CONTEXT, '@graph' => graph)
+      JSON.pretty_generate('@context' => context, '@graph' => graph)
+    end
+
+    def context
+      @context || CONTEXT
+    end
+
+    def context= c
+      @context = c
     end
 
     private

data/lib/ro_crate/model/organization.rb

@@ -2,7 +2,7 @@ module ROCrate
   ##
   # A contextual entity that represents an organization.
   class Organization < ContextualEntity
-    properties(['name'])
+    properties(%w[name])
 
     private
 

data/lib/ro_crate/model/preview.rb

@@ -12,26 +12,14 @@ module ROCrate
     # @return [String]
     attr_accessor :template
 
-    def initialize(crate, properties = {})
+    def initialize(crate, source = nil, properties = {})
+      source ||= PreviewGenerator.new(self)
       @template = nil
-      super(crate, nil, IDENTIFIER, properties)
-    end
-
-    ##
-    # Generate the crate's `ro-crate-preview.html`.
-    # @return [String] The rendered HTML as a string.
-    def generate
-      b = crate.get_binding
-      renderer = ERB.new(template || ::File.read(DEFAULT_TEMPLATE))
-      renderer.result(b)
+      super(crate, source, IDENTIFIER, properties)
     end
 
     private
 
-    def source
-      Entry.new(StringIO.new(generate))
-    end
-
     def default_properties
       {
         '@id' => IDENTIFIER,

data/lib/ro_crate/model/preview_generator.rb

@@ -0,0 +1,40 @@
+require 'erb'
+
+module ROCrate
+  ##
+  # A class to handle generation of an RO-Crate's preview HTML in an IO-like way (to fit into an Entry).
+  class PreviewGenerator
+    ##
+    # @param preview [Preview] The RO-Crate preview object.
+    def initialize(preview)
+      @preview = preview
+    end
+
+    def read(*args)
+      io.read(*args)
+    end
+
+    ##
+    # Generate the crate's `ro-crate-preview.html`.
+    # @return [String] The rendered HTML as a string.
+    def generate
+      b = crate.get_binding
+      renderer = ERB.new(template)
+      renderer.result(b)
+    end
+
+    def template
+      @preview.template || ::File.read(Preview::DEFAULT_TEMPLATE)
+    end
+
+    def crate
+      @preview.crate
+    end
+
+    private
+
+    def io
+      @io ||= StringIO.new(generate)
+    end
+  end
+end

data/lib/ro_crate/model/remote_entry.rb

@@ -2,7 +2,7 @@ module ROCrate
   ##
   # A class to represent a reference within an RO-Crate, to a remote file held on the internet somewhere.
   # It handles the actual reading/writing of bytes.
-  class RemoteEntry
+  class RemoteEntry < Entry
     attr_reader :uri
 
     ##
@@ -13,17 +13,6 @@ module ROCrate
       @uri = uri
     end
 
-    def write(dest)
-      raise 'Cannot write to a remote entry!'
-    end
-
-    ##
-    # Read from the source.
-    #
-    def read
-      source.read
-    end
-
     ##
     # @return [IO] An IO object for the remote resource.
     #

data/lib/ro_crate/reader.rb

@@ -84,7 +84,10 @@ module ROCrate
     def self.read_zip(source, target_dir: Dir.mktmpdir)
       unzip_to(source, target_dir)
 
-      read_directory(target_dir)
+      # Traverse the unzipped directory to try and find the crate's root
+      root_dir = detect_root_directory(target_dir)
+
+      read_directory(root_dir)
     end
 
     ##
@@ -100,8 +103,12 @@ module ROCrate
           entry == ROCrate::Metadata::IDENTIFIER_1_0 }
 
       if metadata_file
-        entities = entities_from_metadata(::File.read(::File.join(source, metadata_file)))
-        build_crate(entities, source)
+        metadata_json = ::File.read(::File.join(source, metadata_file))
+        metadata = JSON.parse(metadata_json)
+        entities = entities_from_metadata(metadata)
+        context = metadata['@context']
+
+        build_crate(entities, source, context: context)
       else
         raise 'No metadata found!'
       end
@@ -110,10 +117,9 @@ module ROCrate
     ##
     # Extracts all the entities from the @graph of the RO-Crate Metadata.
     #
-    # @param metadata_json [String] A string containing the metadata JSON.
+    # @param metadata [Hash] A Hash containing the parsed metadata JSON.
     # @return [Hash{String => Hash}] A Hash of all the entities, mapped by their @id.
-    def self.entities_from_metadata(metadata_json)
-      metadata = JSON.parse(metadata_json)
+    def self.entities_from_metadata(metadata)
       graph = metadata['@graph']
 
       if graph
@@ -126,6 +132,7 @@ module ROCrate
         # Do some normalization...
         entities[ROCrate::Metadata::IDENTIFIER] = extract_metadata_entity(entities)
         raise "No metadata entity found in @graph!" unless entities[ROCrate::Metadata::IDENTIFIER]
+        entities[ROCrate::Preview::IDENTIFIER] = extract_preview_entity(entities)
         entities[ROCrate::Crate::IDENTIFIER] = extract_root_entity(entities)
         raise "No root entity (with @id: #{entities[ROCrate::Metadata::IDENTIFIER].dig('about', '@id')}) found in @graph!" unless entities[ROCrate::Crate::IDENTIFIER]
 
@@ -136,25 +143,50 @@ module ROCrate
     end
 
     ##
-    # Create a crate from the given set of entities.
+    # Create and populate crate from the given set of entities.
     #
     # @param entity_hash [Hash{String => Hash}] A Hash containing all the entities in the @graph, mapped by their @id.
     # @param source [String, ::File, Pathname] The location of the RO-Crate being read.
+    # @param crate_class [Class] The class to use to instantiate the crate,
+    #   useful if you have created a subclass of ROCrate::Crate that you want to use. (defaults to ROCrate::Crate).
+    # @param context [nil, String, Array, Hash] A custom JSON-LD @context (parsed), or nil to use default.
     # @return [Crate] The RO-Crate.
-    def self.build_crate(entity_hash, source)
-      ROCrate::Crate.new.tap do |crate|
+    def self.build_crate(entity_hash, source, crate_class: ROCrate::Crate, context:)
+      crate = initialize_crate(entity_hash, source, crate_class: crate_class, context: context)
+
+      extract_data_entities(crate, source, entity_hash).each do |entity|
+        crate.add_data_entity(entity)
+      end
+
+      # The remaining entities in the hash must be contextual.
+      extract_contextual_entities(crate, entity_hash).each do |entity|
+        crate.add_contextual_entity(entity)
+      end
+
+      crate
+    end
+
+    ##
+    # Initialize a crate from the given set of entities.
+    #
+    # @param entity_hash [Hash{String => Hash}] A Hash containing all the entities in the @graph, mapped by their @id.
+    # @param source [String, ::File, Pathname] The location of the RO-Crate being read.
+    # @param crate_class [Class] The class to use to instantiate the crate,
+    #   useful if you have created a subclass of ROCrate::Crate that you want to use. (defaults to ROCrate::Crate).
+    # @param context [nil, String, Array, Hash] A custom JSON-LD @context (parsed), or nil to use default.
+    # @return [Crate] The RO-Crate.
+    def self.initialize_crate(entity_hash, source, crate_class: ROCrate::Crate, context:)
+      crate_class.new.tap do |crate|
         crate.properties = entity_hash.delete(ROCrate::Crate::IDENTIFIER)
         crate.metadata.properties = entity_hash.delete(ROCrate::Metadata::IDENTIFIER)
+        crate.metadata.context = context
         preview_properties = entity_hash.delete(ROCrate::Preview::IDENTIFIER)
-        crate.preview.properties = preview_properties if preview_properties
-        crate.add_all(source, false)
-        extract_data_entities(crate, source, entity_hash).each do |entity|
-          crate.add_data_entity(entity)
-        end
-        # The remaining entities in the hash must be contextual.
-        extract_contextual_entities(crate, entity_hash).each do |entity|
-          crate.add_contextual_entity(entity)
+        preview_path = ::File.join(source, ROCrate::Preview::IDENTIFIER)
+        preview_path = ::File.exists?(preview_path) ? Pathname.new(preview_path) : nil
+        if preview_properties || preview_path
+          crate.preview = ROCrate::Preview.new(crate, preview_path, preview_properties || {})
         end
+        crate.add_all(source, false)
       end
     end
 
@@ -226,8 +258,8 @@ module ROCrate
     ##
     # Extract the metadata entity from the entity hash, according to the rules defined here:
     # https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#finding-the-root-data-entity
-    # @return [Hash{String => Hash}] A Hash containing (hopefully) one value, the metadata entity's properties,
-    # mapped by its @id.
+    # @return [nil, Hash{String => Hash}] A Hash containing (hopefully) one value, the metadata entity's properties
+    # mapped by its @id, or nil if nothing is found.
     def self.extract_metadata_entity(entities)
       key = entities.detect do |_, props|
         props.dig('conformsTo', '@id')&.start_with?(ROCrate::Metadata::RO_CRATE_BASE)
@@ -242,6 +274,13 @@ module ROCrate
           entities.delete(ROCrate::Metadata::IDENTIFIER_1_0))
     end
 
+    ##
+    # Extract the ro-crate-preview entity from the entity hash.
+    # @return [Hash{String => Hash}] A Hash containing the preview entity's properties mapped by its @id, or nil if nothing is found.
+    def self.extract_preview_entity(entities)
+      entities.delete("./#{ROCrate::Preview::IDENTIFIER}") || entities.delete(ROCrate::Preview::IDENTIFIER)
+    end
+
     ##
     # Extract the root entity from the entity hash, according to the rules defined here:
     # https://www.researchobject.org/ro-crate/1.1/root-data-entity.html#finding-the-root-data-entity
@@ -252,5 +291,23 @@ module ROCrate
       raise "Metadata entity does not reference any root entity" unless root_id
       entities.delete(root_id)
     end
+
+    ##
+    # Finds an RO-Crate's root directory (where `ro-crate-metdata.json` is located) within a given directory.
+    #
+    # @param source [String, ::File, Pathname] The location of the directory.
+    # @return [Pathname, nil] The path to the root, or nil if not found.
+    def self.detect_root_directory(source)
+      Pathname(source).find do |entry|
+        if entry.file?
+          name = entry.basename.to_s
+          if name == ROCrate::Metadata::IDENTIFIER || name == ROCrate::Metadata::IDENTIFIER_1_0
+            return entry.parent
+          end
+        end
+      end
+
+      nil
+    end
   end
 end