Overview and Problem Statement

Many users are currently frustrated by Hyrax and Hyku’s lack of standard ability to support ordering and hierarchy of authors, contributors, or generally “agents” associated with a given work or collection. This has trickle-down (up?) effects in our collective ability to support ORCiD profiles for authors. It has forced a number of institutions to implement custom solutions to address their individual needs.

This set of features would address those limitations, and lessen the amount of fragmentation of implemented solutions to address those shortcomings.

“Pitch”

Frustrated by not being able to retain or define the order of Authors on a work? What about contributor vs creator, and nesting these metadata fields? One of the many problems we seek to solve here is to enable metadata librarians and administrators proper control and flexibility so that nested or hierarchical metadata fields can be displayed in a clear and consistent way to researchers and patrons, while providing proper attributions to actors associated with the respective work.

A foundation for hierarchical metadata has been added to Hyrax and is now available for expansion via additional development efforts.

Other references

Related Issue on GWU libraries github: https://github.com/gwu-libraries/scholarspace-5-test/issues/77

Example of difficult hierarchical metadata structures: collection of folk musichttps://folkmusic.lib.wvu.edu/?search_field=all_fields&q=

ORCiD Metadata: https://info.orcid.org/documentation/integration-guide/orcid-record/

SMIG Meetings discussing this topic: Metadata Call 2026-05-26 Metadata Call 2025-01-28 Metadata Call 2024-08-27

PALNI/PALCI ticket: https://github.com/notch8/palni-palci/issues/401. Per LaRita, this orders the creator term only, and if you want the ability to order other terms it would need to be added to the model for those terms. This isn’t something that can be done just via the m3 profile.

It’s done in Hyku by adding a like like this to the model for the term: https://github.com/samvera/hyku/blob/main/app/models/generic_work_resource.rb#L23

In a knapsack app that has its own models added, it’s a bit more cumbersome:
https://github.com/notch8/hykuup_knapsack/blob/594632c82b33229b391e8e1ea2acfcd0b2bb3407/app/models/mobius_work.rb#L6-L22

Notes on Project Surfliner Implementation

At Project Surfliner, we have (partially) implemented this using Valkyrie + M3. Here are some notes on our implementation, for reference, in case it is helpful:

• We use the Postgres backend for Valkyrie, which preserves order implicitly, so we don’t do anything special for it.

• In the M3, we use the range property to indicate nested properties. If the range is rdf:Literal, it is a normal property; if it is a reference to an M3 class, it is a “complex” property and the referenced class gives the nested properties. Classes which are referenced in the range property are not treated as top‐level object types (they are not Hyrax/PCDM works); they can only be used in the ranges of other properties.

• We use Dry Schema for validation, which can handle the nested metadata fine. You can see how we generate this from the M3 here: https://gitlab.com/surfliner/surfliner/-/blob/02361c76f1109dfc83b6d5e5582615afb8ff5347/gems/surfliner_schema/lib/surfliner_schema/reader.rb#L131 . Dry Schema is better and more powerful than Reform for form handling and validation, and it is mostly cross‐compatible, but it does take a little hacking to get things to work, which you can see here: https://gitlab.com/surfliner/surfliner/-/blob/02361c76f1109dfc83b6d5e5582615afb8ff5347/gems/surfliner_schema/lib/surfliner_schema/form_fields.rb#L64

• In Bulkrax, we use a syntax of property@order.subproperty@order to specify properties and their order in the flat structure of a CSV. So you might have contributor@1.name, contributor@1.role@1, and contributor@1.role@2 for a first contributor with a name and two roles. We haven’t ever tried nesting metadata more than one level and don’t currently have any usecase for it.

• What we haven’t figured out: How to handle this in the edit UI. Right now we just suppress properties with “complex” (nested) values from the Edit Object page and mandate that if you want to edit them, you have to use Bulkrax. This is not ideal and we would love if the Samvera community could come up with a solution that makes nested metadata in edit pages feasible.

ꟛ— Margaret Kibi, UCSB

Use case

Louisville has custom fields called creator_role and contributor_role that ideally would be linked to an ordered entry in creator and contributor. If linking is not possible, we would at least want the order to remain consistent - if the photographer’s name appears first in the creator field, the word “photographer” should appear first in the creator_role field (the order within the CSV should be maintained). See https://library.louisville.edu/hyku_cookbook/creator_role and https://library.louisville.edu/hyku_cookbook/contributor_role for our descriptions of how to create metadata for these fields, and https://digital.library.louisville.edu/concern/images/ulpa_1984_001_099?locale=en for an example of when the order was not retained (Caufield & Shook is the photographer, Joseph & Joseph the architect).

– Rachel Howard, University of Louisville (copied from comment)

Design references

Blacklight

We need to go out to the blacklight team at Stanford to see how they are handling hierarchical metadata, per @Mark Bussey

ArchiveSpace

Open

Thanks to @Nic Don Stanton-Roark