Flexible Metadata (v6.2)

Date posted: 07/28/2025

Last edited: Dec 4, 2025

Flexible metadata allows administrators to configure metadata schemas through the UI using an M3 (Machine-readable Metadata Modeling) profile. This feature is enabled by default in Hyku v6.2 and later.

Admins can define and manage metadata fields per Work Type with control over aspects such as the field label, whether it is required, searchable, etc. This reduces the need for developer involvement for basic changes and fully supports Hyku's multi-tenant architecture.

1 🗂️ Resources
2 ⚙️ User Guide: Metadata Terminology
3 🔍 User Guide: How Flexible Metadata Works
4 ✅ User Guide: Use Cases
5 🔄 User Guide: Schema Versioning
6 👤 User Guide: Managing Metadata Profiles
7 📄 User Guide: Creating a New Flexible Metadata Profile
8 🔄 User Guide: Works on Different Schema Versions
9 🗄️ User Guide: Contexts
10 👩‍💻 Developer Notes
11 🐣 Creating New Work Types
12 💬 Q & A
13 🗝️ Background
14 ⚠️ Continuing Work
15 ❓ Ongoing Community Questions and Comments

🗂️ Resources

Demo Video: Flexible metadata in Hyku
Default flexible metadata profile:

⚙️ User Guide: Metadata Terminology

This documentation is designed for users.

Term	Description	Example

Term	Description	Example
M3	Machine-readable Metadata Modeling	—
M3 Profile	YAML file that defines metadata per Work Type	`m3_profile.yaml`
Work Type	A content model representing a type of item	`Generic Work`, `ETD`
Property	A metadata field (fields and properties are often used interchangeably)	`title`, `creator`, `keyword`
Context	Allows varying metadata fields by Admin Set	(Optional)
Flexible metadata schema	A user-defined schema that can be uploaded and versioned	—
Basic metadata schema	The legacy, non-configurable schema	—
Dublin Core	Standard metadata vocabulary of 15 core terms	dublincore.org
RDF	A standard for describing data using triples	w3schools RDF intro
RDF mapping	Maps a property to a URI	`http://purl.org/dc/terms/title`
Allinson Flex	Ruby gem that inspired flexible metadata in Hyku	GitHub
Houndstooth	Validates metadata schemas	GitHub

🔍 User Guide: How Flexible Metadata Works

Flexible metadata is enabled by default in Hyku v6.2
- Flexible metadata can be disabled by developers via environment configuration HYRAX_FLEXIBLE=false
It controls deposit and edit forms, Solr indexing, work and collection show pages
All application will have a default profile that includes Hyrax core metadata, Hyku Work Types, and common metadata properties
- hyku/config/metadata_profiles/m3_profile.yaml
Admins can download and upload metadata profiles via the Hyku admin dashboard
Each uploaded profile becomes the current active version, replacing the previous one
The application builds dynamic forms and views from the current active profile while preserving views for works created with previous versions
Flexible metadata supports: Works, Collections, FileSets
- It does not currently support Admin Sets

✅ User Guide: Use Cases

Why Use Flexible Metadata?

Enables domain-specific metadata for different disciplines
Supports different schemas per tenant
Properties can be configured with contexts to have unique behavior per Work Type
Metadata profiles allow configurable per-property settings such as:
- Display label
- Required/optional status
- Searchability
- Indexing
- RDF and Dublin Core mapping
No need for developers to implement code changes when metadata fields change
Metadata profiles can be versioned, imported, and exported
Schema changes allow older works to exist under previous versions until the older work is edited

Limitations

Flexible metadata is a configuration layer and as such cannot create new Work Types, new Dublin Core terms, or new Solr index categories; a developer must generate and configure them
Flexible metadata can customize Works, Collections, and FileSets, but cannot make changes to the Admin Sets themselves
When flexible metadata is enabled it is applied to all Work Types
Flexible metadata is enabled application-wide and is not currently tenant-specific

🔄 User Guide: Schema Versioning

Uploading a new profile creates a new active schema
Profiles cannot be deleted
Profiles cannot be restored, but downloading an older profile and re-uploading would work
If a property is removed, it disappears from the form for all new works
- It will still display on existing records until they are edited
If a property is added, it appears on all new forms

👤 User Guide: Managing Metadata Profiles

Accessing Metadata Profiles

Go to Dashboard → Configuration → Metadata Profiles
Download the Hyku Initial Profile (YAML)
Edit or add new properties in a text editor
Import the new version
The new profile becomes the active schema

Required Metadata

This is an example profile that contains only the required metadata fields with annotations to note which values can be modified. All of the YAML keys in this example must be included in the metadata file. This represents the minimum attributes that can successfully create works using a flexible metadata profile. Omitting these attributes would result in not to be able to upload a new profile.

This example includes the Hyrax core metadata that is required for all profiles.

---
m3_version: 1.0.beta2 # Do not modify
profile:
  date_modified: '2025-07-22' # Can be modified for user's content tracking
  responsibility: https://test.com # Can modify value
classes:
  AdminSetResource: # Do not modify
    display_label: Admin Set # Can modify value for user's preference
  CollectionResource: # Do not modify
    display_label: PCDM Collection # Can modify value for user's preference
  Hyrax::FileSet: # Do not modify
    display_label: File Set # Can modify value for user's preference
  GenericWorkResource: # At least one Work Type is required; Only Work Types that exist in the application can be used
    display_label: Generic Work # Can modify value for user's preference
properties:
  title:
    available_on:
      class:
      - AdminSetResource # Do not modify
      - Hyrax::FileSet # Do not modify
      - CollectionResource # Do not modify
      - GenericWorkResource # Must match an existing Work Type class name
    cardinality:
      minimum: 1 # Do not modify
    data_type: array # Required for title, not required for other properties
    display_label:
      default: Title # Can modify value for user's preference
    indexing:
    - title_sim # Solr indexing, used for faceting
    - title_tesim # Solr indexing, used for searching
    form:
      required: true # Removing this means the title input doesn't exist on the form, a work can be created but there is no way to add a title
      primary: true # Removing this means the title input is only visible after selecting "Additional fields"
    property_uri: http://purl.org/dc/terms/title # Do not modify
    range: http://www.w3.org/2001/XMLSchema#string # Do not modify
  date_modified:
    available_on:
      class:
      - AdminSetResource # Do not modify
      - Hyrax::FileSet # Do not modify
      - CollectionResource # Do not modify
      - GenericWorkResource # Must match Work Type class name
    display_label:
      default: Date Modified # Can modify value for user's preference
    range: http://www.w3.org/2001/XMLSchema#dateTime
    property_uri: http://purl.org/dc/terms/modified
  date_uploaded:
    available_on:
      class:
      - AdminSetResource # Do not modify
      - Hyrax::FileSet # Do not modify
      - CollectionResource # Do not modify
      - GenericWorkResource # Must match Work Type class name
    display_label:
      default: Date Uploaded # Can modify value for user's preference
    range: http://www.w3.org/2001/XMLSchema#dateTime
    property_uri: http://purl.org/dc/terms/dateSubmitted
  depositor:
    available_on:
      class:
      - AdminSetResource # Do not modify
      - Hyrax::FileSet # Do not modify
      - CollectionResource # Do not modify
      - GenericWorkResource # Must match Work Type class name
    display_label:
      default: Depositor # Can modify value for user's preference
    indexing:
      - depositor_ssim # Solr indexing, used for faceting
      - depositor_tesim # Solr indexing, used for searching
    range: http://www.w3.org/2001/XMLSchema#string # Do not modify
    property_uri: http://id.loc.gov/vocabulary/relators/dpt # Do not modify
  creator:
    available_on:
      class:
      - AdminSetResource # Do not modify
      - Hyrax::FileSet # Do not modify
      - CollectionResource # Do not modify
      - GenericWorkResource # Must match Work Type class name
    indexing:
      - creator_sim # Solr indexing, used for faceting
      - creator_tesim # Solr indexing, used for searching
    data_type: array # Do not modify
    display_label:
      default: Creator # Can modify value for user's preference
    range: http://www.w3.org/2001/XMLSchema#string # Do not modify
    property_uri: http://purl.org/dc/elements/1.1/creator # Do not modify
  label:
    available_on:
      class:
      - Hyrax::FileSet # Do not modify; FileSet is the only class required for the label property
    display_label:
      default: Label # Can modify value for user's preference
    range: http://www.w3.org/2001/XMLSchema#string # Do not modify

📄 User Guide: Creating a New Flexible Metadata Profile

Top Level Attributes

Key Name	Purpose	Required?	Can be modified?

Key Name	Purpose	Required?	Can be modified?
`m3_version`	Specifies M3 schema version; lets M3-compatible tools validate profile format; `1.0.beta2`	✅ Yes	❌ No
`profile`	Metadata about the profile itself	✅ Yes	✅ Yes
`classes`	Definition of the Work Types or models used in the profile; Only Work Types that exist in the application can be used	✅ Yes	✅ Yes
`properties`	Metadata fields/attributes for Work Types	✅ Yes	✅ Yes
`contexts`	Admin Set or collection-level configurations	Optional	✅ Yes
`mappings`	How metadata properties are mapped to specific external systems or contexts	Optional	✅ Yes

Profile Attributes

Key Name	Purpose	Formatting	Required?

Key Name	Purpose	Formatting	Required?
`date_modified`	Date the profile was modified; for user tracking; not used by the application	Must be `YYYY-MM-DD` format wrapped in quotes	✅ Yes
`responsibility`	URI of owner or maintainer	Must be valid URI format	✅ Yes
`responsibility_statement`	Definition of the Work Types or models used in the profile	Text	Optional
`type`	Name displayed on `Profile Type` of the Metadata Profile dashboard	Text	Optional
`version`	Version of the profile for user tracking; not used as versioning by the application	Number	Optional

Profile Example in YAML

m3_version: 1.0.beta2
profile:
  date_modified: '2025-07-23'
  responsibility: https://samvera.org
  responsibility_statement: Hyku Initial Profile
  type: Hyku Profile
  version: 1

Classes Attributes

There are four default work types in Hyku: Generic Work, Image, ETD, OER
- To remove unused Work Types do not include them in the flexible profile
- Adding additional Work Types must be configured by a developer, see below for details
Class names are pattern matched from the existing model in the application

Key Name	Purpose	Required?

Key Name	Purpose	Required?
`AdminSetResource`	Declares the collection; must have a `display_label` subtag	✅ Yes
`CollectionResource`	Declares the collection; must have a `display_label` subtag	✅ Yes
`Hyrax::FileSet`	Declares the collection; must have a `display_label` subtag	✅ Yes
`GenericWorkResource`	Declares the Generic Work Type; must have a `display_label` subtag	✅ At least one work type is required to create works
`ImageResource`	Declares the Image Work Type; must have a `display_label` subtag	Optional
`OerResource`	Declares the Open Educational Resources Work Type; must have a `display_label` subtag	Optional
`EtdResource`	Declares the Electronic Theses and Dissertations Work Type; must have a `display_label` subtag	Optional
`display_label`	Nested attribute; human readable label	✅ Yes

Classes Example in YAML

m3_version: 1.0.beta2
profile:
	...
classes:
  AdminSetResource:
    display_label: Admin Set
  CollectionResource:
    display_label: PCDM Collection
  Hyrax::FileSet:
    display_label: File Set
  GenericWorkResource:
    display_label: Generic Work
  ImageResource:
    display_label: Image
  OerResource:
    display_label: OER
  EtdResource:
    display_label: ETD

Properties Attributes

Key Name	Purpose	Data Type	Required?

Key Name	Purpose	Data Type	Required?
`title`	Primary title of the work	Array	✅ Yes
`date_modified`	Date the work was last updated (system generated)	DateTime string, auto-populated	✅ Yes
`date_uploaded`	Date the work was first created (system generated)	DateTime string, auto-populated	✅ Yes
`depositor`	User who uploaded the work	String, system-generated	✅ Yes
`creator`	Author(s) or creator(s) of the work	Array	✅ Yes
`label`	Internal label for file or object The only class required is `Hyrax::FileSet`	String	✅ Yes
`license`	Usage license of the work	Array	Optional
`abstract`	Summary or abstract of the work	Array	Optional
`access_right`	Conditions for accessing the work	Array	Optional
`alternative_title`	Alternate or translated title(s)	Array	Optional
`arkivo_checksum`	Checksum for Zotero/Arkivo integration	String	Optional
`based_near`	Geographic location of the work	Array (GeoNames)	Optional
`bibliographic_citation`	Citation string	Array	Optional
`contributor`	Additional contributors	Array	Optional
`date_created`	Original creation date of the work	Array	Optional
`description`	Detailed description	Array, String	Optional
`identifier`	Unique identifier(s)	Array	Optional
`import_url`	URL of imported item	URI string	Optional
`keyword`	Tags or keywords	Array	Optional
`language`	Language(s) of the work	Array	Optional
`publisher`	Entity that published the work	Array	Optional
`related_url`	Link to related resource	Array	Optional
`relative_path`	Path within imported package	URI string	Optional
`resource_type`	Type of resource (e.g., Article, Dataset)	Array	Optional
`rights_notes`	Additional notes about rights	Array	Optional
`rights_statement`	Rights statement URI