inconsistency in relation/use/type

[elrayle]

Descriptive summary

Code for processing and understanding relation/use/type is spread through the code and led to some inconsistency in processing. The terms relation, use, and type are used interchangeably to describe the relationship between a FileSet and a File.

Inconsistencies

---

Defined as String, Symbol, or RDF::URI

Prerequisite

May want to address inconsistency Parameter name as relation, use, or type in conjunction with this inconsistency.

Background:

The relation parameter is identified as being a String, Symbol, or RDF::URI in the various places it is used. Sometimes in combinations of these, but not consistently.

The relationship between FileSet and File for ActiveFedora is defined in Hydra::Works::ContainedFiles with directly_contains_one using symbols :original_file, :extracted_text, :thumbnail. When Hydra::Works::AddFileToFileSet is passed type (aka relation) as one of these symbols, it sets the FileSet association based on the type.

Valkyrization:

As we move to Valkyrie, the relationship is no longer maintained using these symbols. The custom query find_many_file_metadata_by_use(resource: file_set, use: [RDF::URI]) is used to find files of a particular type.

Action:

• Pass relation/use/type as a RDF::URI everywhere. (applies minimally to FileSetActor, FileActor, JobIoWrapper, and possibly other places)

Prerequisite for

• complete in conjunction with
  • Parameter name as relation, use, or type
• complete before
  • :extracted_file vs. :extracted_text, :thumbnail_file vs. :thumbnail.

---

Parameter name as relation, use, or type

Prerequisite

Address inconsistency Defined as String, Symbol, or RDF::URI first or in conjunction with this inconsistency.

Background:

Hyrax up until the valkyrization process mostly referred to this as relation, while Hydra::Works refers to it as type.

Valkyrization:

As relation is also used in many other ways, it was more accurate to refer to this as the use of the file in the file_set. There was also precedence in figgy's FileMetadata class. So the initial implementation of FileMetadata in Hyrax created a use attribute as a replacement for type.

It was later decided to revert the name of the attribute back to type becuase type in AF includes more than just the use and it would be difficult to know which RDF::URI stored in AF type is the one that represents the use of the file. And since the other RDF::URIs stored in the AF type do not represent the use of the file, it seems clearer to represent the attribute as type.

Action:

Based on @no-reply comments below, the following actions should be taken...

• deprecate usage of named parameter relation: recommending to pass RDF::URI to named parameter use: instead.
• add named parameter use: that receives RDF::URI to any method with named parameter relation:
• rename any non-named parameter or variables from relation to use

NOTE: use: expects to be a RDF::URI; relation: might be String, Symbol, or RDF::URI. It is recommended that inconsistency Defined as String, Symbol, or RDF::URI be addressed first or in conjunction with this inconsistency.

NOTE: type will be used in places not directly passing the use of the file (e.g. http://pcdm.org/use#original_file, http://pcdm.org/use#extracted_text, etc.). The most notable place for type over use is in Hyrax::FileMetadata (in models) that has a type attribute. This attributes holds all types for the file, some of which may not have anything to do with the use of the file (e.g. http://www.w3.org/ns/ldp#RDFSource).

The basic decision points are:

• use if passing only the use of the file
• type if passing use and potentially other types
• relation should NOT be used for files

---

:extracted_file vs. :extracted_text, :thumbnail_file vs. :thumbnail

Prerequsite

Address inconsistency Defined as String, Symbol, or RDF::URI first.

Background

ActiveFedora uses Symbols to add a file to a file set using one of the 3 pre-defined associations (i.e. :original_file, :extracted_text, :thumbnail. These are determined by the directly_contains_one definitions in Hydra::Works::ContainedFiles.

Valkryization

In Hyrax::FileActor (under actors/hyrax/actors), there are methods #normalize_relation_for_active_fedora to transform from RDF::URI to Symbol and #normalize_relation_for_valkyrie to transform from RDF::URI to Symbol. These have the symbols as :extracted_file and :thumbnail_file. The transformation methods were added in PR #3746 and used the wrong symbols.

Action

Minimal change:

• Replace :extracted_file with :extracted_text
• Replace :thumbnail_file with :thumbnail

Once inconsistency Defined as String, Symbol, or RDF::URI is addressed, meaning that relation/use/type is now passed around in Hyrax as RDF::URIs only, #normalize_relation_for_valkyrie transition is no longer needed. #normalize_relation_for_active_fedora is only needed in one place where files are added to file sets for the Wings adapter.

• Move #normalize_relation_for_active_fedora to Wings::Works:: AddFileToFileSet to transform the RDF::URI to the Symbol before calling Hydra::Works::AddFileToFileSet
• Rename #normalize_relation_for_active_fedora to #normalize_use_for_active_fedora

NOTE: Depending on the outcome of inconsistency Defined as String, Symbol, or RDF::URI, both transformation methods may be required to support the deprecation of passing a String/Symbol. If that is the case, the following actions are recommended...

• Move #normalize_relation_for_active_fedora to Hyrax::FileMetadata::Use module
• Move #normalize_relation_for_valkyrie to Hyrax::FileMetadata::Use module
• Rename #normalize_relation_for_active_fedora to #normalize_use_for_active_fedora
• Rename #normalize_relation_for_valkyrie to #normalize_use_for_valkyrie
• Update all methods with named parameter relation: to use these methods to do the transformation

---

:extracted_file? vs. :extracted_text?, :thumbnail_file? vs. :thumbnail?

Valkryization

In Hyrax::FileMetadata (under models/hyrax), there are methods #extracted_file? and #thumbnail_file? . These names were selected based on precedence in figgy.

Action

In all other places, these are referred to as extracted_text and thumbnail. It is recommended that these methods be renamed as #extracted_text? and #thumbnail?.

Related work

PR #4225 - defines use constants in Hyrax::FileSet
PR #4215 - moves use constants to Hydra::FileMetadata
PR #3746 - valkyrize file_actor adding file_node to hold metadata_node values from active fedora

[no-reply]

Determine how best to use the terms use, type, relation and update method names and parameter names as needed for consistency.

at-a-glance, the approach that seems attractive to me is to use type for the attribute name, reserving "use" to describe the PCDM Use Vocabulary itself.

"relation" i think should just be dropped as we rework models. it's terribly ambiguous and may lead people to incorrectly infer a connection to ActiveRecord relations, or to dcterms:relation

[no-reply]

@elrayle apart from the open question i've taken an attempt at answering above, i think your proposed actions are great. if we can start to deprecate the symbol based interfaces, i think that would be productive.

[no-reply]

i think the established pattern in Hyrax::FileMetadata is to use :type as the property name and maintain URIs as the values. Hyrax::FileMetadata::Use offers translation from Symbol keys, and there are some convenience methods on FileMetadata to check for common PCDM Use terminology.

i think this one might not need any further attention at this point.