From f8521e444346742bb3660526f3f29940e26b2c98 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 15:25:22 -0400
Subject: [PATCH 01/32] Add compound metadata schema reader and flag

Hyrax can read compound (hierarchical) metadata declarations off a
resource's schema, returning each compound's sub-fields, groups, and
display mode in both flexible and non-flexible modes.

This is the read-only foundation the compound form, indexer, and show
renderer build on; the compound_metadata_enabled? config flag (default
on) gates whether the rest of the feature activates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app/services/hyrax/compound_schema.rb       | 187 ++++++++++++++++++++
 lib/hyrax/configuration.rb                  |  11 ++
 spec/services/hyrax/compound_schema_spec.rb | 164 +++++++++++++++++
 3 files changed, 362 insertions(+)
 create mode 100644 app/services/hyrax/compound_schema.rb
 create mode 100644 spec/services/hyrax/compound_schema_spec.rb

diff --git a/app/services/hyrax/compound_schema.rb b/app/services/hyrax/compound_schema.rb
new file mode 100644
index 0000000000..ec04b1bc5c
--- /dev/null
+++ b/app/services/hyrax/compound_schema.rb
@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Hyrax
+  ##
+  # @api public
+  #
+  # Reads the compound metadata declarations off a resource's schema. A compound
+  # is a `type: hash, multiple: true` attribute carrying a `subfields:` map; the
+  # declaration drives the generic form, indexer, and renderer so a hierarchical
+  # field can be defined in YAML alone. See documentation/forms/compound_fields.md.
+  #
+  # Declarations are read from each attribute's Dry type `meta`, which both
+  # schema loaders populate identically, so the result is the same in both flex
+  # modes.
+  class CompoundSchema
+    ##
+    # Build a CompoundSchema for a resource instance or class.
+    #
+    # @param [Valkyrie::Resource, Class] resource a resource instance, or a
+    #   class (used by class-level callers that only see class-declared
+    #   compounds — i.e. non-flex).
+    def self.for(resource)
+      new(*schema_sources_for(resource))
+    end
+
+    # For a class, its own schema. For an instance, both the class schema
+    # (non-flexible) and the singleton schema (flexible: the m3 attributes are
+    # applied to the singleton at load time). Unioning both makes {.for} work in
+    # both flex modes.
+    def self.schema_sources_for(resource)
+      if resource.is_a?(Class)
+        [(resource.schema if resource.respond_to?(:schema))]
+      else
+        sources = []
+        sources << resource.class.schema if resource.class.respond_to?(:schema)
+        sources << resource.singleton_class.schema if resource.respond_to?(:singleton_class) && resource.singleton_class.respond_to?(:schema)
+        sources
+      end.compact
+    end
+    private_class_method :schema_sources_for
+
+    attr_reader :schema_sources
+
+    # @param [Array<#each>] schema_sources one or more Dry schemas (each a
+    #   collection of property types responding to `name` and `meta`).
+    def initialize(*schema_sources)
+      @schema_sources = schema_sources.flatten.compact
+    end
+
+    ##
+    # @return [Boolean] whether the given attribute is a compound (declares
+    #   `subfields:`)
+    def compound?(attribute_name)
+      definitions.key?(attribute_name.to_sym)
+    end
+
+    ##
+    # @return [Array<Symbol>] the names of every compound attribute on the
+    #   resource
+    def compound_names
+      definitions.keys
+    end
+
+    ##
+    # @return [Array<Symbol>] compounds displayed inline in the metadata list
+    #   (the default)
+    def inline_compound_names
+      definitions.reject { |_name, d| d[:display_mode] == :card }.keys
+    end
+
+    ##
+    # @return [Array<Symbol>] compounds displayed as their own card on show
+    #   pages (`view: { display: card }`)
+    def card_compound_names
+      definitions.select { |_name, d| d[:display_mode] == :card }.keys
+    end
+
+    ##
+    # @return [Boolean] whether the compound displays as a card
+    def card?(attribute_name)
+      definition_for(attribute_name)&.dig(:display_mode) == :card
+    end
+
+    ##
+    # @param [#to_sym] attribute_name
+    #
+    # @return [Hash{Symbol => Object}, nil] the compound's declaration:
+    #   `{ subfields:, groups:, index_subfields: }`, or nil when the attribute
+    #   is not a compound.
+    def definition_for(attribute_name)
+      definitions[attribute_name.to_sym]
+    end
+
+    ##
+    # @param [#to_sym] attribute_name
+    #
+    # @return [Array<String>] the ordered sub-field keys declared for the
+    #   compound (empty when not a compound).
+    def subfield_keys(attribute_name)
+      definition = definition_for(attribute_name)
+      return [] unless definition
+      definition[:subfields].keys
+    end
+
+    ##
+    # @return [Hash{Symbol => Hash}] a map from compound attribute name to its
+    #   normalized declaration. Memoized per instance.
+    def definitions
+      @definitions ||= build_definitions
+    end
+
+    private
+
+    def build_definitions
+      schema_sources.each_with_object({}) do |schema, memo|
+        next unless schema.respond_to?(:each)
+
+        schema.each do |property|
+          meta = property.respond_to?(:meta) ? property.meta : nil
+          next if meta.nil?
+
+          name = property.name.to_sym
+          next if memo.key?(name)
+
+          config = meta.with_indifferent_access
+          subfields = config['subfields']
+          next if subfields.blank?
+
+          memo[name] = normalize(config, subfields)
+        end
+      end
+    end
+
+    # Normalizes the raw declaration into the symbol-keyed shape the form,
+    # indexer, and renderer consume. See documentation/forms/compound_fields.md
+    # for the meaning of each sub-field key.
+    def normalize(config, subfields)
+      sub = subfields.each_with_object({}) do |(key, opts), memo|
+        opts = (opts.is_a?(Hash) ? opts : {}).with_indifferent_access
+        memo[key.to_s] = { type: (opts['type'] || 'string').to_s,
+                           authority: opts['authority']&.to_s,
+                           values: normalize_values(opts['values']),
+                           index_keys: normalize_index_keys(opts),
+                           display: opts.fetch('display', true) != false }
+      end
+
+      view = config['view']
+      display_mode = view.is_a?(Hash) && view['display'].to_s == 'card' ? :card : :inline
+
+      { subfields: sub, groups: normalize_groups(config['groups'], sub.keys), display_mode: display_mode }
+    end
+
+    # Reads `index_keys:` (non-flexible) or `indexing:` (flexible), filtering the
+    # non-field control tokens, mirroring AttributeDefinition#index_keys.
+    INDEX_CONTROL_TOKENS = %w[facetable stored_searchable admin_only editor_only].freeze
+    def normalize_index_keys(opts)
+      raw = opts['indexing'] || opts['index_keys'] || []
+      Array(raw).reject { |k| INDEX_CONTROL_TOKENS.include?(k.to_s) }.map(&:to_s)
+    end
+
+    # Normalizes an inline option list into `[[label, id], ...]`; nil when none.
+    def normalize_values(values)
+      return nil if values.blank?
+
+      Array(values).map do |entry|
+        if entry.is_a?(Hash)
+          h = entry.with_indifferent_access
+          id = (h['id'] || h['value'] || h['label']).to_s
+          [(h['label'] || id).to_s, id]
+        else
+          [entry.to_s, entry.to_s]
+        end
+      end
+    end
+
+    def normalize_groups(groups, all_keys)
+      return [{ label: nil, cols: 6, fields: all_keys }] if groups.blank?
+
+      Array(groups).map do |group|
+        group = group.with_indifferent_access
+        { label: group['label'],
+          cols: (group['cols'] || 6).to_i,
+          fields: Array(group['fields']).map(&:to_s) }
+      end
+    end
+  end
+end
diff --git a/lib/hyrax/configuration.rb b/lib/hyrax/configuration.rb
index 510edafd47..c6e74dd23d 100644
--- a/lib/hyrax/configuration.rb
+++ b/lib/hyrax/configuration.rb
@@ -350,6 +350,17 @@ def redirects_enabled?
     end
     alias redirects_enabled redirects_enabled?
 
+    # Whether the sample compound metadata schema ships on works and collections
+    # by default. Defaults to true; respects +HYRAX_COMPOUND_METADATA_ENABLED+.
+    #
+    # @see documentation/forms/compound_fields.md
+    attr_writer :compound_metadata_enabled
+    def compound_metadata_enabled?
+      return @compound_metadata_enabled if defined?(@compound_metadata_enabled) && !@compound_metadata_enabled.nil?
+      @compound_metadata_enabled = ActiveModel::Type::Boolean.new.cast(ENV.fetch('HYRAX_COMPOUND_METADATA_ENABLED', true))
+    end
+    alias compound_metadata_enabled compound_metadata_enabled?
+
     # @return [Boolean] true when both feature gates are open. Single
     #   source of truth for "is the redirects feature actively in use
     #   right now?". Short-circuits on the config so the Flipflop call
diff --git a/spec/services/hyrax/compound_schema_spec.rb b/spec/services/hyrax/compound_schema_spec.rb
new file mode 100644
index 0000000000..5cf9e9052f
--- /dev/null
+++ b/spec/services/hyrax/compound_schema_spec.rb
@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::CompoundSchema do
+  let(:resource_class) do
+    Class.new(Hyrax::Resource) do
+      def self.name
+        'TestResourceWithCompounds'
+      end
+
+      attribute :title, Valkyrie::Types::Array.of(Valkyrie::Types::String)
+      attribute :contributors,
+                Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
+                  subfields: {
+                    'given_name' => { 'type' => 'string', 'index_keys' => %w[contributors_given_name_sim contributors_given_name_tesim] },
+                    'family_name' => { 'type' => 'string', 'index_keys' => %w[contributors_family_name_tesim] },
+                    'role_label' => { 'type' => 'controlled', 'authority' => 'contributor_role', 'display' => false }
+                  },
+                  groups: [
+                    { 'label' => 'Identity', 'cols' => 6, 'fields' => %w[given_name family_name] },
+                    { 'label' => 'Role', 'cols' => 6, 'fields' => %w[role_label] }
+                  ]
+                )
+      attribute :identifiers,
+                Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
+                  subfields: {
+                    'value' => { 'type' => 'string' },
+                    'identifier_type' => { 'type' => 'controlled', 'authority' => 'identifier_type' }
+                  }
+                )
+      attribute :agent,
+                Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
+                  subfields: {
+                    'agent_name' => { 'type' => 'string' },
+                    'agent_role' => { 'type' => 'controlled', 'values' => ['Author', { 'id' => 'ed', 'label' => 'Editor' }] }
+                  }
+                )
+      attribute :relationships,
+                Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
+                  subfields: {
+                    'related_item' => { 'type' => 'work_or_url' },
+                    'relationship_type' => { 'type' => 'controlled', 'authority' => 'relationship_type' }
+                  },
+                  view: { 'display' => 'card' }
+                )
+    end
+  end
+
+  subject(:schema) { described_class.for(resource_class) }
+
+  describe '#compound_names' do
+    it 'returns only the attributes that declare subfields' do
+      expect(schema.compound_names).to contain_exactly(:contributors, :identifiers, :agent, :relationships)
+    end
+
+    it 'does not treat a plain scalar attribute as a compound' do
+      expect(schema.compound_names).not_to include(:title)
+    end
+  end
+
+  describe 'display mode (view: { display: card })' do
+    describe '#inline_compound_names' do
+      it 'excludes compounds declared as cards' do
+        expect(schema.inline_compound_names).to contain_exactly(:contributors, :identifiers, :agent)
+      end
+    end
+
+    describe '#card_compound_names' do
+      it 'returns only compounds declared as cards' do
+        expect(schema.card_compound_names).to contain_exactly(:relationships)
+      end
+    end
+
+    describe '#card?' do
+      it 'is true for a compound declared view: { display: card }' do
+        expect(schema.card?(:relationships)).to be true
+        expect(schema.card?('relationships')).to be true
+      end
+
+      it 'is false for an inline (default) compound' do
+        expect(schema.card?(:contributors)).to be false
+      end
+
+      it 'is false for a non-compound attribute' do
+        expect(schema.card?(:title)).to be false
+      end
+    end
+
+    it 'records the display_mode on the definition' do
+      expect(schema.definition_for(:relationships)[:display_mode]).to eq(:card)
+      expect(schema.definition_for(:contributors)[:display_mode]).to eq(:inline)
+    end
+  end
+
+  describe '#compound?' do
+    it 'is true for a declared compound' do
+      expect(schema.compound?(:contributors)).to be true
+      expect(schema.compound?('contributors')).to be true
+    end
+
+    it 'is false for a non-compound attribute' do
+      expect(schema.compound?(:title)).to be false
+    end
+  end
+
+  describe '#subfield_keys' do
+    it 'returns the ordered sub-field keys' do
+      expect(schema.subfield_keys(:contributors)).to eq(%w[given_name family_name role_label])
+    end
+
+    it 'is empty for a non-compound' do
+      expect(schema.subfield_keys(:title)).to eq([])
+    end
+  end
+
+  describe '#definition_for' do
+    it 'normalizes subfields with type, authority, index_keys and display' do
+      definition = schema.definition_for(:contributors)
+      expect(definition[:subfields]['role_label'])
+        .to eq(type: 'controlled', authority: 'contributor_role', values: nil, index_keys: [], display: false)
+      expect(definition[:subfields]['given_name'])
+        .to eq(type: 'string', authority: nil, values: nil,
+               index_keys: %w[contributors_given_name_sim contributors_given_name_tesim], display: true)
+    end
+
+    it 'reads per-sub-field index_keys (literal Solr field names)' do
+      expect(schema.definition_for(:contributors)[:subfields]['family_name'][:index_keys])
+        .to eq(%w[contributors_family_name_tesim])
+    end
+
+    it 'defaults a sub-field with no index declaration to no index_keys' do
+      expect(schema.definition_for(:agent)[:subfields]['agent_name'][:index_keys]).to eq([])
+    end
+
+    it 'defaults display to true and honors display: false' do
+      expect(schema.definition_for(:contributors)[:subfields]['given_name'][:display]).to be true
+      expect(schema.definition_for(:contributors)[:subfields]['role_label'][:display]).to be false
+    end
+
+    it 'normalizes an inline controlled-vocabulary values list to [label, id] pairs' do
+      values = schema.definition_for(:agent)[:subfields]['agent_role'][:values]
+      expect(values).to eq([%w[Author Author], %w[Editor ed]])
+    end
+
+    it 'carries the declared groups' do
+      groups = schema.definition_for(:contributors)[:groups]
+      expect(groups).to eq([
+                             { label: 'Identity', cols: 6, fields: %w[given_name family_name] },
+                             { label: 'Role', cols: 6, fields: %w[role_label] }
+                           ])
+    end
+
+    it 'defaults groups to a single all-fields group when none declared' do
+      groups = schema.definition_for(:identifiers)[:groups]
+      expect(groups).to eq([{ label: nil, cols: 6, fields: %w[value identifier_type] }])
+    end
+  end
+
+  describe '.for' do
+    it 'builds from a resource instance' do
+      expect(described_class.for(resource_class.new).compound_names)
+        .to contain_exactly(:contributors, :identifiers, :agent, :relationships)
+    end
+  end
+end

From f8e1f04c23272555253ac9e73509359d029de46d Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 15:30:58 -0400
Subject: [PATCH 02/32] Render compound metadata fields on forms

Resource edit forms render a repeatable, schema-driven section per
compound attribute, with add/remove-row controls and a generic
populator that converts the nested-attributes payload to the persisted
array-of-hashes shape. Each sub-field renders by its declared type
(text, controlled select, url, or a work-or-url picker).

Compounds are kept out of the primary/secondary scalar terms so they
render only through the compound section. The wiring is a no-op until a
schema declares a compound, in both flexible and non-flexible modes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app/assets/javascripts/hyrax.js               |   1 +
 .../javascripts/hyrax/compound_metadata.js    |  98 +++++++++++++
 .../concerns/hyrax/compound_field_behavior.rb |  92 ++++++++++++
 app/forms/hyrax/forms.rb                      |   7 +
 app/forms/hyrax/forms/pcdm_collection_form.rb |   6 +
 app/forms/hyrax/forms/resource_form.rb        |  21 ++-
 app/helpers/hyrax/compound_fields_helper.rb   | 134 ++++++++++++++++++
 app/helpers/hyrax/hyrax_helper_behavior.rb    |   1 +
 app/views/hyrax/base/_form_metadata.html.erb  |   5 +
 .../hyrax/compounds/_compound_row.html.erb    |  82 +++++++++++
 .../compounds/_compound_section.html.erb      |  59 ++++++++
 .../dashboard/collections/_form.html.erb      |   6 +
 config/locales/hyrax.en.yml                   |   4 +
 lib/hyrax/form_fields.rb                      |  23 +++
 .../hyrax/compound_field_behavior_spec.rb     | 110 ++++++++++++++
 .../hyrax/compound_fields_helper_spec.rb      | 134 ++++++++++++++++++
 16 files changed, 781 insertions(+), 2 deletions(-)
 create mode 100644 app/assets/javascripts/hyrax/compound_metadata.js
 create mode 100644 app/forms/concerns/hyrax/compound_field_behavior.rb
 create mode 100644 app/helpers/hyrax/compound_fields_helper.rb
 create mode 100644 app/views/hyrax/compounds/_compound_row.html.erb
 create mode 100644 app/views/hyrax/compounds/_compound_section.html.erb
 create mode 100644 spec/forms/concerns/hyrax/compound_field_behavior_spec.rb
 create mode 100644 spec/helpers/hyrax/compound_fields_helper_spec.rb

diff --git a/app/assets/javascripts/hyrax.js b/app/assets/javascripts/hyrax.js
index cb70a7135d..f76be1a0e6 100644
--- a/app/assets/javascripts/hyrax.js
+++ b/app/assets/javascripts/hyrax.js
@@ -46,6 +46,7 @@
 //= require hyrax/single_use_links_manager
 //= require hyrax/copy_permalink_button
 //= require hyrax/redirects
+//= require hyrax/compound_metadata
 //= require hyrax/dashboard_actions
 //= require hyrax/batch
 //= require hyrax/flot_stats
diff --git a/app/assets/javascripts/hyrax/compound_metadata.js b/app/assets/javascripts/hyrax/compound_metadata.js
new file mode 100644
index 0000000000..b5a7099de2
--- /dev/null
+++ b/app/assets/javascripts/hyrax/compound_metadata.js
@@ -0,0 +1,98 @@
+// Behavior for compound metadata fields on resource edit forms (add/remove row,
+// work_or_url select2). Event-delegated so dynamically-added rows need no
+// rebinding. The sentinel guards against the IIFE running twice (Turbolinks
+// re-evaluates module scripts on some navigation paths), which would stack
+// duplicate listeners. Mirrors hyrax/redirects.js.
+(function() {
+    if (document.hyraxCompoundsBound) return;
+    document.hyraxCompoundsBound = true;
+
+    // Bind select2 to a `work_or_url` sub-field. The v3 API (Hyrax bundles
+    // select2-rails 3.x) binds to a hidden input; createSearchChoice lets a
+    // typed external URL be selected as-is.
+    function bindWorkOrUrlInputs(root) {
+        if (typeof jQuery === 'undefined' || !jQuery.fn.select2) return;
+        jQuery(root).find('[data-hyrax-compound-work-input]').each(function() {
+            var $el = jQuery(this);
+            if ($el.hasClass('select2-offscreen') || $el.data('select2')) return; // already bound
+            $el.select2({
+                width: '100%',
+                allowClear: true,
+                placeholder: 'Search for a work or enter a URL',
+                minimumInputLength: 2,
+                // Let a typed value (e.g. an external URL) be selected as-is.
+                createSearchChoice: function(term) {
+                    return { id: term, text: term };
+                },
+                // Render the current value's label (work title or the URL) on load.
+                initSelection: function(element, callback) {
+                    var val = element.val();
+                    if (!val) return;
+                    callback({ id: val, text: element.data('label') || val });
+                },
+                ajax: {
+                    url: $el.data('autocomplete-url'),
+                    dataType: 'json',
+                    quietMillis: 250,
+                    data: function(term, page) { return { q: term }; },
+                    results: function(data, page) {
+                        return {
+                            results: data.map(function(obj) {
+                                return { id: obj.id, text: [].concat(obj.label)[0] };
+                            })
+                        };
+                    }
+                }
+            });
+        });
+    }
+
+    // Bind saved rows once the DOM is ready (at script-eval time the form
+    // inputs don't exist yet, so the select2 would never attach). Covers both a
+    // fresh load and Turbolinks navigation.
+    function bindAll() { bindWorkOrUrlInputs(document); }
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', bindAll);
+    } else {
+        bindAll();
+    }
+    document.addEventListener('turbolinks:load', bindAll);
+
+    document.addEventListener('click', function(event) {
+        var removeButton = event.target.closest('[data-hyrax-compound-remove-row]');
+        if (removeButton) {
+            var row = removeButton.closest('[data-hyrax-compound-row]');
+            if (!row) return;
+            var destroyFlag = row.querySelector('[data-hyrax-compound-destroy-flag]');
+            if (destroyFlag && destroyFlag.value !== undefined) {
+                // Persisted rows: flip the _destroy flag and hide so the
+                // populator drops the row server-side.
+                destroyFlag.value = '1';
+                row.style.display = 'none';
+            } else {
+                row.parentNode.removeChild(row);
+            }
+            return;
+        }
+
+        var addButton = event.target.closest('[data-hyrax-compound-add-row]');
+        if (!addButton) return;
+        var section = addButton.closest('[data-hyrax-compound]');
+        if (!section) return;
+        var template = section.querySelector('[data-hyrax-compound-row-template]');
+        var rowsHost = section.querySelector('[data-hyrax-compound-rows]');
+        if (!template || !rowsHost) return;
+
+        // Monotonic counter on the section; never recycle an index after a
+        // row is removed. Fallback to row count when the attribute is missing.
+        var nextIndex = parseInt(section.dataset.nextIndex, 10);
+        if (isNaN(nextIndex)) {
+            nextIndex = rowsHost.querySelectorAll('[data-hyrax-compound-row]').length;
+        }
+        var html = template.innerHTML.replace(/__INDEX__/g, nextIndex);
+        rowsHost.insertAdjacentHTML('beforeend', html);
+        // Bind select2 on any work_or_url inputs in the row just added.
+        bindWorkOrUrlInputs(rowsHost.lastElementChild || rowsHost);
+        section.dataset.nextIndex = String(nextIndex + 1);
+    });
+})();
diff --git a/app/forms/concerns/hyrax/compound_field_behavior.rb b/app/forms/concerns/hyrax/compound_field_behavior.rb
new file mode 100644
index 0000000000..f5ca4bf3c0
--- /dev/null
+++ b/app/forms/concerns/hyrax/compound_field_behavior.rb
@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Hyrax
+  ##
+  # Generic, schema-driven form handling for compound metadata fields (see
+  # {Hyrax::CompoundSchema}). The generic equivalent of the hand-written
+  # {Hyrax::RedirectsFieldBehavior}: it discovers every compound on the form's
+  # model and wires each one's virtual `<name>_attributes` property and
+  # populator from the schema, in both flex modes.
+  module CompoundFieldBehavior
+    # Register the virtual `<name>_attributes` populator properties on the
+    # singleton class for every compound on the resource. Must run before Reform
+    # builds the deserialization schema; the flexible-mode init path calls this,
+    # while non-flexible mode wires the same properties at class load via
+    # {Hyrax::FormFields}.
+    #
+    # @param [Valkyrie::Resource] resource the form's resource (the form's own
+    #   `model` may not be set yet when this runs).
+    def register_compound_fields!(resource)
+      Hyrax::CompoundSchema.for(resource).compound_names.each do |name|
+        next if singleton_class.method_defined?(:"#{name}_attributes=")
+
+        singleton_class.property :"#{name}_attributes",
+                                 virtual: true,
+                                 populator: :compound_attributes_populator
+      end
+    rescue StandardError => e
+      Hyrax.logger.debug("CompoundFieldBehavior: register failed for #{self.class}: #{e.message}")
+    end
+
+    # Strip each compound's renamed bare key so the `<name>_attributes`
+    # populator is the single write entry point (the Field Behavior contract;
+    # see documentation/forms/field_behaviors.md).
+    def deserialize!(params)
+      result = super
+      return result unless result.respond_to?(:delete)
+
+      compound_field_names.each do |name|
+        result.delete(name.to_s)
+        result.delete(name.to_sym)
+      end
+      result
+    end
+
+    private
+
+    def compound_field_names
+      return [] unless respond_to?(:model) && model
+      Hyrax::CompoundSchema.for(model).compound_names
+    rescue StandardError => e
+      Hyrax.logger.debug("CompoundFieldBehavior: could not read compounds for #{self.class}: #{e.message}")
+      []
+    end
+
+    # One populator serves every compound (Reform passes the property name as
+    # `as:`). Builds the replacement array of plain hashes — declared sub-field
+    # keys only, dropping `_destroy` and all-blank rows.
+    def compound_attributes_populator(fragment:, as:, **_options)
+      name = as.to_s.delete_suffix('_attributes')
+      return unless respond_to?(name)
+
+      allowed = Hyrax::CompoundSchema.for(model).subfield_keys(name)
+      public_send(:"#{name}=", build_compound_rows(fragment, allowed))
+    end
+
+    def build_compound_rows(fragment, allowed_keys)
+      compound_fragment_pairs(fragment)
+        .sort_by { |key, _row| key.to_i }
+        .map { |_key, row| compound_row_from(row, allowed_keys) }
+        .compact
+    end
+
+    def compound_fragment_pairs(fragment)
+      return {} if fragment.nil?
+      fragment.respond_to?(:to_unsafe_h) ? fragment.to_unsafe_h : fragment.to_h
+    end
+
+    # Returns nil for a row marked for destruction or whose declared sub-fields
+    # are all blank, otherwise the persisted hash for that row.
+    def compound_row_from(row, allowed_keys)
+      row = row.respond_to?(:to_unsafe_h) ? row.to_unsafe_h : row.to_h
+      return nil if %w[true 1].include?(row['_destroy'].to_s)
+
+      entry = allowed_keys.each_with_object({}) do |key, memo|
+        value = row[key]
+        memo[key] = value.is_a?(String) ? value.strip : value
+      end
+      return nil if entry.values.all?(&:blank?)
+      entry
+    end
+  end
+end
diff --git a/app/forms/hyrax/forms.rb b/app/forms/hyrax/forms.rb
index 10575e9c21..3794bcc8d3 100644
--- a/app/forms/hyrax/forms.rb
+++ b/app/forms/hyrax/forms.rb
@@ -14,6 +14,13 @@ def self.PcdmObjectForm(work_class) # rubocop:disable Naming/MethodName
       Class.new(Hyrax::Forms::PcdmObjectForm) do
         self.model_class = work_class
         include Hyrax::FormFields(:core_metadata) if work_class.ancestors.detect { |k| k.inspect == "Hyrax::Schema(core_metadata)" }
+        # Wire the compound form properties only for works whose model includes
+        # the compound_metadata schema (non-flexible mode); the m3 loader
+        # supplies them at init in flexible mode.
+        if Hyrax.config.compound_metadata_enabled? && !Hyrax.config.flexible? &&
+           work_class.ancestors.detect { |k| k.inspect == "Hyrax::Schema(compound_metadata)" }
+          include Hyrax::FormFields(:compound_metadata)
+        end
 
         ##
         # @return [String]
diff --git a/app/forms/hyrax/forms/pcdm_collection_form.rb b/app/forms/hyrax/forms/pcdm_collection_form.rb
index 542829651d..a007bc3807 100644
--- a/app/forms/hyrax/forms/pcdm_collection_form.rb
+++ b/app/forms/hyrax/forms/pcdm_collection_form.rb
@@ -7,6 +7,12 @@ module Forms
     # @see https://github.com/samvera/valkyrie/wiki/ChangeSets-and-Dirty-Tracking
     class PcdmCollectionForm < Hyrax::Forms::ResourceForm # rubocop:disable Metrics/ClassLength
       include Hyrax::FormFields(:core_metadata) if Hyrax.config.collection_include_metadata?
+      # Wire the compound form properties (non-flexible mode), mirroring the
+      # work-side wiring in the PcdmObjectForm factory.
+      if Hyrax.config.compound_metadata_enabled? && !Hyrax.config.flexible? &&
+         Hyrax::PcdmCollection.ancestors.detect { |k| k.inspect == "Hyrax::Schema(compound_metadata)" }
+        include Hyrax::FormFields(:compound_metadata)
+      end
       check_if_flexible(Hyrax::PcdmCollection)
 
       BannerInfoPrepopulator = lambda do |**_options|
diff --git a/app/forms/hyrax/forms/resource_form.rb b/app/forms/hyrax/forms/resource_form.rb
index 386764d2a8..28c6108182 100644
--- a/app/forms/hyrax/forms/resource_form.rb
+++ b/app/forms/hyrax/forms/resource_form.rb
@@ -28,6 +28,7 @@ class ResourceForm < Hyrax::ChangeSet # rubocop:disable Metrics/ClassLength
 
       include BasedNearFieldBehavior
       include RedirectsFieldBehavior
+      include CompoundFieldBehavior
       include Hyrax::FormFields(:redirects) if Hyrax.config.redirects_enabled? && Hyrax.config.work_include_metadata?
       class_attribute :model_class
 
@@ -79,6 +80,10 @@ def initialize(deprecated_resource = nil, resource: nil)
           current_schema_fields.each do |field_name, options|
             singleton_class.property field_name.to_sym, options.merge(display: options.fetch(:display, true), default: [])
           end
+          # Register the virtual `<compound>_attributes` populators on the
+          # singleton before `super`, so they are part of Reform's schema for
+          # this instance (non-flexible mode wires them at class load).
+          register_compound_fields!(r) if respond_to?(:register_compound_fields!)
         end
 
         if resource.nil?
@@ -122,6 +127,7 @@ def inherited(subclass)
           # subclass's model.
           subclass.prepend(BasedNearFieldBehavior)
           subclass.prepend(RedirectsFieldBehavior)
+          subclass.prepend(CompoundFieldBehavior)
           super
         end
 
@@ -226,7 +232,7 @@ def model_class # rubocop:disable Rails/Delegate
       def primary_terms
         terms = _form_field_definitions
                 .select { |_, definition| definition[:primary] }
-                .keys.map(&:to_sym)
+                .keys.map(&:to_sym) - compound_terms
 
         terms = [:schema_version, :contexts] + terms if model.flexible?
         terms
@@ -237,7 +243,18 @@ def primary_terms
       def secondary_terms
         _form_field_definitions
           .select { |_, definition| definition[:display] && !definition[:primary] }
-          .keys.map(&:to_sym)
+          .keys.map(&:to_sym) - compound_terms
+      end
+
+      ##
+      # @return [Array<Symbol>] compound attribute terms, rendered by the
+      #   compound form partials rather than as scalar fields (and so excluded
+      #   from {#primary_terms} / {#secondary_terms}).
+      def compound_terms
+        return [] unless respond_to?(:model) && model
+        Hyrax::CompoundSchema.for(model).compound_names
+      rescue StandardError
+        []
       end
 
       ##
diff --git a/app/helpers/hyrax/compound_fields_helper.rb b/app/helpers/hyrax/compound_fields_helper.rb
new file mode 100644
index 0000000000..a1a80ec7db
--- /dev/null
+++ b/app/helpers/hyrax/compound_fields_helper.rb
@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Hyrax
+  # View helpers for rendering compound (hierarchical) metadata fields on forms
+  # and show pages. See documentation/forms/compound_fields.md.
+  module CompoundFieldsHelper
+    ##
+    # Renders one compound section (a repeatable stack of sub-field rows) for the
+    # given attribute via the `hyrax/compounds/*` partials.
+    #
+    # @return [String, nil] rendered HTML, or nil when the attribute is not a
+    #   declared compound on the model.
+    def render_compound_field(f, compound_name)
+      schema = Hyrax::CompoundSchema.for(f.object.model)
+      definition = schema.definition_for(compound_name)
+      return nil if definition.nil?
+
+      render 'hyrax/compounds/compound_section',
+             f: f,
+             compound_name: compound_name.to_sym,
+             definition: definition,
+             display_label: compound_field_label(compound_name)
+    end
+
+    ##
+    # @return [Boolean] whether the field is a card-display compound
+    #   (`view: { display: card }`). Show views use this to skip card compounds
+    #   in the inline metadata list.
+    def compound_card_field?(presenter, field)
+      klass = compound_resource_class_for(presenter)
+      return false unless klass
+      Hyrax::CompoundSchema.for(klass).card?(field)
+    rescue StandardError
+      false
+    end
+
+    ##
+    # Render every card-display compound that has a value as its own titled card
+    # (matching the relationships/items cards).
+    #
+    # @param [Object] presenter a work or collection show presenter
+    # @return [ActiveSupport::SafeBuffer]
+    def render_compound_cards(presenter)
+      klass = compound_resource_class_for(presenter)
+      return ''.html_safe unless klass
+
+      safe_join(Hyrax::CompoundSchema.for(klass).card_compound_names.map do |name|
+        next ''.html_safe unless presenter.respond_to?(name) && presenter.public_send(name).present?
+
+        render 'hyrax/compounds/compound_card', presenter: presenter, field: name
+      end)
+    rescue StandardError => e
+      Hyrax.logger.debug("render_compound_cards: #{e.message}")
+      ''.html_safe
+    end
+
+    # The resource class for a show presenter, to read its compound schema.
+    # Works and collections resolve it differently.
+    def compound_resource_class_for(presenter)
+      if presenter.respond_to?(:solr_document) && presenter.solr_document.respond_to?(:hydra_model)
+        presenter.solr_document.hydra_model
+      elsif presenter.is_a?(Hyrax::CollectionPresenter)
+        Hyrax.config.collection_class
+      end
+    end
+
+    ##
+    # Options for a `controlled` sub-field's `<select>`: an inline `values:`
+    # list when present, otherwise the named QA authority. A stored value not
+    # among the options is appended so it still renders (`include_current_value`).
+    #
+    # @return [Array<Array(String, String)>] `[[label, id], ...]`
+    def compound_subfield_options(spec, current_value = nil)
+      options = spec[:values].presence || authority_options(spec[:authority])
+      ensure_current_value(options, current_value)
+    end
+
+    ##
+    # @return [Boolean] whether +current_value+ is present but not among the
+    #   sub-field's offered options — i.e. a forced/stale value. The select
+    #   gets the +force-select+ class in that case, matching the ordinary
+    #   controlled-field convention.
+    def compound_subfield_forced?(spec, current_value = nil)
+      return false if current_value.blank?
+      base = spec[:values].presence || authority_options(spec[:authority])
+      base.none? { |(_label, id)| id.to_s == current_value.to_s }
+    end
+
+    ##
+    # The pre-selected `[label, value]` option for a `work_or_url` sub-field's
+    # select2, or nil when empty. An internal work id resolves to its title; an
+    # external URL is shown as-is.
+    #
+    # @return [Array(String, String), nil]
+    def compound_work_or_url_option(value)
+      return nil if value.blank?
+      return [value.to_s, value.to_s] if Hyrax::CompoundWorkResolver.url?(value)
+
+      title, = Hyrax::CompoundWorkResolver.title_and_path(value)
+      [title, value.to_s]
+    end
+
+    def compound_field_label(compound_name)
+      t("hyrax.compound_fields.#{compound_name}.label",
+        default: compound_name.to_s.humanize)
+    end
+
+    def compound_subfield_label(compound_name, sub_field)
+      t("hyrax.compound_fields.#{compound_name}.#{sub_field}",
+        default: sub_field.to_s.humanize)
+    end
+
+    private
+
+    # Options from a QA local authority. Uses {Hyrax::TolerantSelectService} so
+    # an authority file that omits `active:` treats its terms as active rather
+    # than raising, matching ordinary controlled fields.
+    def authority_options(authority_name)
+      return [] if authority_name.blank?
+      Hyrax::TolerantSelectService.new(authority_name).select_active_options
+    rescue StandardError => e
+      Hyrax.logger.debug("compound_subfield_options: #{authority_name}: #{e.message}")
+      []
+    end
+
+    # Append the stored value as its own option when it is not already present,
+    # so a value no longer offered by the authority/list still renders.
+    def ensure_current_value(options, current_value)
+      return options if current_value.blank?
+      return options if options.any? { |(_label, id)| id.to_s == current_value.to_s }
+      options + [[current_value.to_s, current_value.to_s]]
+    end
+  end
+end
diff --git a/app/helpers/hyrax/hyrax_helper_behavior.rb b/app/helpers/hyrax/hyrax_helper_behavior.rb
index f5c862eb32..b0ab09c30c 100644
--- a/app/helpers/hyrax/hyrax_helper_behavior.rb
+++ b/app/helpers/hyrax/hyrax_helper_behavior.rb
@@ -20,6 +20,7 @@ module HyraxHelperBehavior
     include Hyrax::WorkflowsHelper
     include Hyrax::FacetsHelper
     include Hyrax::AttributesHelper
+    include Hyrax::CompoundFieldsHelper
     include Hyrax::PermalinkHelper
     include Hyrax::WorksHelper
     include Hyrax::FileSetFormHelper
diff --git a/app/views/hyrax/base/_form_metadata.html.erb b/app/views/hyrax/base/_form_metadata.html.erb
index 3807268642..acd80ce473 100644
--- a/app/views/hyrax/base/_form_metadata.html.erb
+++ b/app/views/hyrax/base/_form_metadata.html.erb
@@ -3,6 +3,11 @@
             <%= render_edit_field_partial(term, f: f) %>
           <% end %>
         </div>
+        <% if f.object.respond_to?(:compound_terms) %>
+          <% f.object.compound_terms.each do |term| %>
+            <%= render_compound_field(f, term) %>
+          <% end %>
+        <% end %>
         <% if f.object.display_additional_fields? %>
           <%= link_to t('hyrax.works.form.additional_fields'),
                       '#extended-terms',
diff --git a/app/views/hyrax/compounds/_compound_row.html.erb b/app/views/hyrax/compounds/_compound_row.html.erb
new file mode 100644
index 0000000000..d9dee8d6f4
--- /dev/null
+++ b/app/views/hyrax/compounds/_compound_row.html.erb
@@ -0,0 +1,82 @@
+<%# Single card for one compound-attribute row.
+
+    Locals:
+      f                  - form builder for the parent resource
+      compound_name      - Symbol, e.g. :contributors
+      definition         - Hash{ subfields:, groups:, index_subfields: }
+      row                - Hash of persisted values, or nil for a new row
+      index              - Integer position, or the literal "__INDEX__"
+                           placeholder when rendered inside the JS template
+      row_label_singular - "Contributor", "License", etc.
+
+    Each sub-field renders according to its declared `type:` (string,
+    controlled, url, work_or_url). db_table / geocode are future types; the
+    `else` branch is the extension seam.
+%>
+<% subfields = definition[:subfields] %>
+<% groups = definition[:groups] %>
+<% row_position = index.is_a?(String) ? '' : (index.to_i + 1).to_s %>
+<% row_value = ->(key) { row.is_a?(Hash) ? (row[key] || row[key.to_sym]) : nil } %>
+
+<div class="card mb-3 hyrax-compound-row" data-hyrax-compound-row role="group" aria-label="<%= row_label_singular %> <%= row_position %>">
+  <div class="card-header bg-light d-flex justify-content-between align-items-center py-2 h6 mb-0">
+    <span><%= row_label_singular %> <%= row_position %></span>
+    <button type="button"
+            class="close py-0 px-2"
+            aria-label="<%= t('hyrax.compound_fields.remove_row_with_label', label: row_label_singular, default: t('hyrax.compound_fields.remove_row')) %>"
+            data-hyrax-compound-remove-row>
+      <span aria-hidden="true">&times;</span>
+    </button>
+  </div>
+  <div class="card-body">
+    <% groups.each do |group| %>
+      <% if group[:label].present? %>
+        <h4 class="h6 text-muted text-uppercase mt-1 mb-2"><%= group[:label] %></h4>
+      <% end %>
+      <div class="form-row">
+        <% group[:fields].each do |sub_field| %>
+          <% spec = subfields[sub_field] || { type: 'string' } %>
+          <% input_id = "#{f.object_name}_#{compound_name}_attributes_#{index}_#{sub_field}" %>
+          <% input_name = "#{f.object_name}[#{compound_name}_attributes][#{index}][#{sub_field}]" %>
+          <% value = row_value.call(sub_field) %>
+          <div class="form-group col-md-<%= group.fetch(:cols, 6) %>">
+            <%= label_tag input_id, compound_subfield_label(compound_name, sub_field), class: 'form-label small text-muted' %>
+            <% case spec[:type] %>
+            <% when 'controlled' %>
+              <% select_classes = ['form-control', 'form-control-sm'] %>
+              <% select_classes << 'force-select' if compound_subfield_forced?(spec, value) %>
+              <%= select_tag input_name,
+                             options_for_select(compound_subfield_options(spec, value), value),
+                             id: input_id,
+                             include_blank: true,
+                             class: select_classes.join(' ') %>
+            <% when 'url' %>
+              <%= url_field_tag input_name, value,
+                                id: input_id,
+                                class: 'form-control form-control-sm' %>
+            <% when 'work_or_url' %>
+              <%# select2 v3 (bound in compound_metadata.js) binds to this
+                  hidden input; `data-label` pre-seeds the displayed text. %>
+              <% current_option = compound_work_or_url_option(value) %>
+              <%= hidden_field_tag input_name, value,
+                                   id: input_id,
+                                   class: 'form-control form-control-sm',
+                                   data: { 'hyrax-compound-work-input': true,
+                                           'label': current_option&.first,
+                                           'autocomplete-url': "#{Rails.application.routes.url_helpers.qa_path}/search/compound_works" } %>
+            <% else %>
+              <%# string (default); db_table / geocode slot in here later. %>
+              <%= text_field_tag input_name, value,
+                                 id: input_id,
+                                 class: 'form-control form-control-sm' %>
+            <% end %>
+          </div>
+        <% end %>
+      </div>
+    <% end %>
+
+    <%= hidden_field_tag "#{f.object_name}[#{compound_name}_attributes][#{index}][_destroy]", '0',
+                         id: "#{f.object_name}_#{compound_name}_attributes_#{index}__destroy",
+                         data: { 'hyrax-compound-destroy-flag': true } %>
+  </div>
+</div>
diff --git a/app/views/hyrax/compounds/_compound_section.html.erb b/app/views/hyrax/compounds/_compound_section.html.erb
new file mode 100644
index 0000000000..8272ddc9a9
--- /dev/null
+++ b/app/views/hyrax/compounds/_compound_section.html.erb
@@ -0,0 +1,59 @@
+<%# Renders one compound-attribute section: a repeatable stack of cards, one
+    per entry. Schema-driven via the `definition` local. See
+    documentation/forms/compound_fields.md.
+
+    Locals:
+      f             - form builder for the parent resource
+      compound_name - Symbol, e.g. :contributors
+      definition    - Hash{ subfields:, groups: } from CompoundSchema#definition_for
+      display_label - String shown as the section heading
+
+    Form params: <obj>[<compound>_attributes][<index>][<sub_field>]
+%>
+<%# Read rows from the form when it exposes the compound reader, else the model. %>
+<% source = f.object.respond_to?(compound_name) ? f.object : f.object.model %>
+<% rows = Array(source.public_send(compound_name)) %>
+<% row_label_singular = display_label.to_s.sub(/s\z/, '').presence || display_label.to_s %>
+<% compound_id = "#{f.object_name}-#{compound_name}".parameterize %>
+
+<section class="hyrax-compound mb-4" data-hyrax-compound data-next-index="<%= rows.length %>" id="<%= compound_id %>">
+  <%# A label element, not a heading, so it matches the form's field labels
+      rather than inheriting Bootstrap's h1–h6 sizing. role=heading for a11y. %>
+  <label class="control-label d-block mb-2" role="heading" aria-level="3"><%= display_label %></label>
+
+  <%# Always-submitted marker so the populator runs even when every row is
+      removed from the DOM. The populator drops the `_marker` row. %>
+  <%= hidden_field_tag "#{f.object_name}[#{compound_name}_attributes][_marker][_destroy]", '1' %>
+
+  <div data-hyrax-compound-rows>
+    <% rows.each_with_index do |row, index| %>
+      <%= render 'hyrax/compounds/compound_row',
+                 f: f,
+                 compound_name: compound_name,
+                 definition: definition,
+                 row: row,
+                 index: index,
+                 row_label_singular: row_label_singular %>
+    <% end %>
+  </div>
+
+  <p class="mt-2">
+    <button type="button" class="btn btn-outline-secondary btn-sm" data-hyrax-compound-add-row>
+      <%= t('hyrax.compound_fields.add_row', label: row_label_singular) %>
+    </button>
+  </p>
+
+  <%# Template cloned by JS on Add; __INDEX__ is replaced with a row counter. %>
+  <template data-hyrax-compound-row-template>
+    <%= render 'hyrax/compounds/compound_row',
+               f: f,
+               compound_name: compound_name,
+               definition: definition,
+               row: nil,
+               index: '__INDEX__',
+               row_label_singular: row_label_singular %>
+  </template>
+</section>
+
+<%# Add/remove-row behavior lives in the engine asset
+    app/assets/javascripts/hyrax/compound_metadata.js (required via hyrax.js). %>
diff --git a/app/views/hyrax/dashboard/collections/_form.html.erb b/app/views/hyrax/dashboard/collections/_form.html.erb
index a19ee698b0..7b6b2c1488 100644
--- a/app/views/hyrax/dashboard/collections/_form.html.erb
+++ b/app/views/hyrax/dashboard/collections/_form.html.erb
@@ -49,6 +49,12 @@
                 <%= render_edit_field_partial(term, f: f) %>
               <% end %>
 
+              <% if f.object.respond_to?(:compound_terms) %>
+                <% f.object.compound_terms.each do |term| %>
+                  <%= render_compound_field(f, term) %>
+                <% end %>
+              <% end %>
+
               <% # TODO: Remove check for PcdmCollection when Issue #5286 is resolved. %>
               <% if f.object.persisted? && !(Hyrax.config.collection_class < Valkyrie::Resource) %>
                 <%# we're loading these values dynamically to speed page load %>
diff --git a/config/locales/hyrax.en.yml b/config/locales/hyrax.en.yml
index 1454a98a98..dc4eb004c2 100644
--- a/config/locales/hyrax.en.yml
+++ b/config/locales/hyrax.en.yml
@@ -858,6 +858,10 @@ en:
       create_service:
         admin_set_description: An aggregation of works that is intended to help with administrative control. Admin Sets provide a way of defining behaviors and policies around a set of works.
         default_description: A User Collection can be created by any user to organize their works.
+    compound_fields:
+      add_row: Add %{label}
+      remove_row: Remove
+      remove_row_with_label: Remove %{label}
     contact_form:
       button_label: Send
       email_label: Your Email
diff --git a/lib/hyrax/form_fields.rb b/lib/hyrax/form_fields.rb
index 037184a505..3e26c0c075 100644
--- a/lib/hyrax/form_fields.rb
+++ b/lib/hyrax/form_fields.rb
@@ -46,13 +46,36 @@ def inspect
 
     private
 
+    # Full attribute config per field — carries keys beyond `form:` (e.g.
+    # `subfields:`), unlike form_field_definitions.
+    def attribute_configs
+      @definition_loader.attributes_for(schema: name, version:, contexts:)
+    end
+
+    # @return [Boolean] whether the named field declares `subfields:`.
+    def compound_field?(configs, field_name)
+      type = configs[field_name.to_sym] || configs[field_name.to_s]
+      meta = type.respond_to?(:meta) ? type.meta : {}
+      meta.with_indifferent_access['subfields'].present?
+    rescue StandardError
+      false
+    end
+
     # rubocop:disable Metrics/MethodLength
     def included(descendant)
       super
       return if @definition_loader.is_a?(Hyrax::M3SchemaLoader)
+      configs = attribute_configs
       form_field_definitions.each do |field_name, options|
         descendant.property field_name.to_sym, options.merge(display: options.fetch(:display, true), default: [])
         descendant.validates field_name.to_sym, presence: true if options.fetch(:required, false)
+        # A compound also needs a virtual `<field>_attributes` populator
+        # property, registered here so it is part of Reform's schema before
+        # `validate` runs (cf. Hyrax::RedirectsFieldBehavior).
+        next unless compound_field?(configs, field_name)
+        descendant.property :"#{field_name}_attributes",
+                            virtual: true,
+                            populator: :compound_attributes_populator
       end
       # Auto include any matching FormFieldBehaviors
       schema_name = name.to_s.camelcase
diff --git a/spec/forms/concerns/hyrax/compound_field_behavior_spec.rb b/spec/forms/concerns/hyrax/compound_field_behavior_spec.rb
new file mode 100644
index 0000000000..a416d935fd
--- /dev/null
+++ b/spec/forms/concerns/hyrax/compound_field_behavior_spec.rb
@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::CompoundFieldBehavior do
+  let(:resource_class) do
+    Class.new(Hyrax::Resource) do
+      def self.name
+        'TestCompoundResource'
+      end
+
+      attribute :contributors,
+                Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
+                  subfields: {
+                    'given_name' => { 'type' => 'string' },
+                    'family_name' => { 'type' => 'string' }
+                  }
+                )
+    end
+  end
+
+  let(:model) { resource_class.new }
+
+  # A minimal form stand-in that includes the behavior and exposes the model
+  # and a settable compound accessor, mirroring the redirects behavior spec.
+  let(:form_class) do
+    Class.new do
+      attr_accessor :contributors
+
+      def self.property(*); end
+
+      def initialize(model)
+        @model = model
+      end
+
+      attr_reader :model
+
+      def respond_to_missing?(name, *)
+        %i[contributors contributors=].include?(name) || super
+      end
+
+      def from_hash(params)
+        params
+      end
+
+      def deserialize!(params)
+        from_hash(params)
+      end
+
+      # Prepend (not include) so the module's `deserialize!` lands above the
+      # class's own on the ancestor chain — mirroring how
+      # `Hyrax::Forms::ResourceForm.inherited` wires the behavior.
+      prepend Hyrax::CompoundFieldBehavior
+    end
+  end
+
+  subject(:form) { form_class.new(model) }
+
+  describe '#compound_attributes_populator' do
+    it 'builds plain string-keyed hashes with only declared sub-fields' do
+      fragment = {
+        '0' => { 'given_name' => 'Ada', 'family_name' => 'Lovelace', 'unknown' => 'drop me' },
+        '1' => { 'given_name' => 'Alan', 'family_name' => 'Turing' }
+      }
+      form.send(:compound_attributes_populator, fragment: fragment, as: :contributors_attributes)
+
+      expect(form.contributors).to eq([
+                                        { 'given_name' => 'Ada', 'family_name' => 'Lovelace' },
+                                        { 'given_name' => 'Alan', 'family_name' => 'Turing' }
+                                      ])
+    end
+
+    it 'drops rows marked for destruction' do
+      fragment = {
+        '0' => { 'given_name' => 'Ada', 'family_name' => 'Lovelace' },
+        '1' => { 'given_name' => 'Gone', 'family_name' => 'Away', '_destroy' => 'true' }
+      }
+      form.send(:compound_attributes_populator, fragment: fragment, as: :contributors_attributes)
+
+      expect(form.contributors).to eq([{ 'given_name' => 'Ada', 'family_name' => 'Lovelace' }])
+    end
+
+    it 'drops the always-submitted marker and all-blank rows' do
+      fragment = {
+        '_marker' => { '_destroy' => '1' },
+        '0' => { 'given_name' => '', 'family_name' => '  ' },
+        '1' => { 'given_name' => 'Grace', 'family_name' => 'Hopper' }
+      }
+      form.send(:compound_attributes_populator, fragment: fragment, as: :contributors_attributes)
+
+      expect(form.contributors).to eq([{ 'given_name' => 'Grace', 'family_name' => 'Hopper' }])
+    end
+
+    it 'orders rows by their numeric key' do
+      fragment = {
+        '2' => { 'given_name' => 'Third' },
+        '0' => { 'given_name' => 'First' },
+        '1' => { 'given_name' => 'Second' }
+      }
+      form.send(:compound_attributes_populator, fragment: fragment, as: :contributors_attributes)
+
+      expect(form.contributors.map { |r| r['given_name'] }).to eq(%w[First Second Third])
+    end
+  end
+
+  describe '#deserialize!' do
+    it 'strips the renamed bare compound key so the populator owns the write' do
+      result = form.deserialize!('contributors' => [{ 'given_name' => 'leaked' }], 'other' => 'keep')
+      expect(result).to eq('other' => 'keep')
+    end
+  end
+end
diff --git a/spec/helpers/hyrax/compound_fields_helper_spec.rb b/spec/helpers/hyrax/compound_fields_helper_spec.rb
new file mode 100644
index 0000000000..1febbe5cbe
--- /dev/null
+++ b/spec/helpers/hyrax/compound_fields_helper_spec.rb
@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::CompoundFieldsHelper, type: :helper do
+  describe '#compound_subfield_options' do
+    let(:spec) { { type: 'controlled', authority: nil, values: [%w[Author Author], %w[Editor ed]] } }
+
+    it 'returns the inline values list' do
+      expect(helper.compound_subfield_options(spec)).to eq([%w[Author Author], %w[Editor ed]])
+    end
+
+    it 'leaves the list unchanged when the current value is already offered' do
+      expect(helper.compound_subfield_options(spec, 'ed')).to eq([%w[Author Author], %w[Editor ed]])
+    end
+
+    it 'appends a stored value that is not among the offered options' do
+      expect(helper.compound_subfield_options(spec, 'Legacy'))
+        .to eq([%w[Author Author], %w[Editor ed], %w[Legacy Legacy]])
+    end
+
+    it 'returns an empty list for a controlled sub-field with neither values nor authority' do
+      expect(helper.compound_subfield_options({ type: 'controlled', authority: nil, values: nil })).to eq([])
+    end
+  end
+
+  describe '#compound_subfield_forced?' do
+    let(:spec) { { type: 'controlled', authority: nil, values: [%w[Author Author]] } }
+
+    it 'is false when the value is blank' do
+      expect(helper.compound_subfield_forced?(spec, '')).to be false
+    end
+
+    it 'is false when the value is among the offered options' do
+      expect(helper.compound_subfield_forced?(spec, 'Author')).to be false
+    end
+
+    it 'is true when the value is not among the offered options' do
+      expect(helper.compound_subfield_forced?(spec, 'Legacy')).to be true
+    end
+  end
+
+  describe '#compound_subfield_label' do
+    it 'falls back to a humanized sub-field key when no translation exists' do
+      expect(helper.compound_subfield_label(:nonexistent_compound, :some_field)).to eq('Some field')
+    end
+  end
+
+  describe 'card display' do
+    # A schema whose only card compound is :relationships.
+    let(:schema) do
+      instance_double(Hyrax::CompoundSchema,
+                      card?: false,
+                      card_compound_names: [:relationships])
+    end
+
+    before do
+      allow(Hyrax::CompoundSchema).to receive(:for).and_return(schema)
+      allow(schema).to receive(:card?).with(:relationships).and_return(true)
+      allow(schema).to receive(:card?).with(:contributors).and_return(false)
+    end
+
+    describe '#compound_resource_class_for' do
+      it 'uses the work hydra_model for a work presenter' do
+        solr_document = instance_double(SolrDocument, hydra_model: GenericWork)
+        presenter = instance_double(Hyrax::WorkShowPresenter, solr_document: solr_document)
+        allow(presenter).to receive(:respond_to?).with(:solr_document).and_return(true)
+        expect(helper.compound_resource_class_for(presenter)).to eq(GenericWork)
+      end
+
+      it 'uses the configured collection class for a collection presenter' do
+        presenter = Hyrax::CollectionPresenter.allocate
+        expect(helper.compound_resource_class_for(presenter)).to eq(Hyrax.config.collection_class)
+      end
+    end
+
+    describe '#compound_card_field?' do
+      let(:solr_document) { instance_double(SolrDocument, hydra_model: GenericWork) }
+      let(:presenter) do
+        pres = instance_double(Hyrax::WorkShowPresenter, solr_document: solr_document)
+        allow(pres).to receive(:respond_to?).with(:solr_document).and_return(true)
+        pres
+      end
+
+      it 'is true for a card-display compound' do
+        expect(helper.compound_card_field?(presenter, :relationships)).to be true
+      end
+
+      it 'is false for an inline compound' do
+        expect(helper.compound_card_field?(presenter, :contributors)).to be false
+      end
+
+      it 'is false (not raising) when the resource class cannot be resolved' do
+        expect(helper.compound_card_field?(Object.new, :relationships)).to be false
+      end
+    end
+
+    describe '#render_compound_cards' do
+      let(:solr_document) { instance_double(SolrDocument, hydra_model: GenericWork) }
+
+      # A presenter test object that responds to `solr_document` and the
+      # compound reader. A plain instance_double can't `and_call_original` on
+      # `respond_to?`, and `render_compound_cards` probes the presenter with
+      # `respond_to?(name)`, so build a small stand-in that answers honestly.
+      def work_presenter(relationships:)
+        Class.new do
+          attr_reader :solr_document, :relationships
+          def initialize(solr_document, relationships)
+            @solr_document = solr_document
+            @relationships = relationships
+          end
+        end.new(solr_document, relationships)
+      end
+
+      it 'renders a card for each card compound with a present value' do
+        presenter = work_presenter(relationships: [{ 'related_item' => 'x' }])
+        allow(helper).to receive(:render).and_return('<div class="card"></div>'.html_safe)
+
+        expect(helper).to receive(:render)
+          .with('hyrax/compounds/compound_card', presenter: presenter, field: :relationships)
+        helper.render_compound_cards(presenter)
+      end
+
+      it 'skips a card compound with no value' do
+        presenter = work_presenter(relationships: [])
+
+        expect(helper).not_to receive(:render)
+        expect(helper.render_compound_cards(presenter)).to eq(''.html_safe)
+      end
+
+      it 'returns an empty safe string when the class cannot be resolved' do
+        expect(helper.render_compound_cards(Object.new)).to eq(''.html_safe)
+      end
+    end
+  end
+end

From 9f7d3498581d0fff4133f40ef92affec0747c622 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 15:35:48 -0400
Subject: [PATCH 03/32] Index and reload compound metadata fields

Compound metadata round-trips through storage: a read-path concern
guards against Valkyrie's single-element-array key-splay on reload, and
an indexer mixin writes each sub-field's declared Solr fields plus a
JSON display blob the show page reads from.

A SolrDocument compound_attribute declarer parses that blob back into an
array of hashes. The indexer mixin is included on the base work and
collection indexers but is a no-op until a schema declares a compound.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../hyrax/indexers/compound_indexer.rb        | 69 ++++++++++++++
 .../hyrax/indexers/pcdm_collection_indexer.rb |  3 +
 .../hyrax/indexers/pcdm_object_indexer.rb     |  3 +
 .../concerns/hyrax/compound_normalization.rb  | 93 +++++++++++++++++++
 .../concerns/hyrax/solr_document/metadata.rb  | 26 ++++++
 .../hyrax/indexers/compound_indexer_spec.rb   | 87 +++++++++++++++++
 .../hyrax/compound_normalization_spec.rb      | 59 ++++++++++++
 7 files changed, 340 insertions(+)
 create mode 100644 app/indexers/hyrax/indexers/compound_indexer.rb
 create mode 100644 app/models/concerns/hyrax/compound_normalization.rb
 create mode 100644 spec/indexers/hyrax/indexers/compound_indexer_spec.rb
 create mode 100644 spec/models/concerns/hyrax/compound_normalization_spec.rb

diff --git a/app/indexers/hyrax/indexers/compound_indexer.rb b/app/indexers/hyrax/indexers/compound_indexer.rb
new file mode 100644
index 0000000000..3983166396
--- /dev/null
+++ b/app/indexers/hyrax/indexers/compound_indexer.rb
@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Hyrax
+  module Indexers
+    ##
+    # Indexer mixin that projects compound metadata sub-fields into Solr. For
+    # every compound on the resource (see {Hyrax::CompoundSchema}), it writes
+    # each sub-field's declared `index_keys:`/`indexing:` Solr fields and stores
+    # the displayable rows as a `<compound>_json_ss` blob the show page renders
+    # from. See documentation/forms/compound_fields.md.
+    #
+    # @example
+    #   class WorkIndexer < Hyrax::Indexers::PcdmObjectIndexer
+    #     include Hyrax::Indexers::CompoundIndexer
+    #   end
+    module CompoundIndexer
+      def to_solr(*args)
+        super.tap do |document|
+          compound_schema.definitions.each do |compound_name, definition|
+            next unless resource.respond_to?(compound_name)
+            index_compound(document, compound_name, definition)
+          end
+        end
+      end
+
+      private
+
+      def compound_schema
+        @compound_schema ||= Hyrax::CompoundSchema.for(resource)
+      end
+
+      def index_compound(document, compound_name, definition)
+        rows = Array(resource.public_send(compound_name))
+        index_searchable_subfields(document, definition, rows)
+        index_display_blob(document, compound_name, definition, rows)
+      end
+
+      def index_searchable_subfields(document, definition, rows)
+        definition[:subfields].each do |sub_field, spec|
+          next if spec[:index_keys].blank?
+
+          values = rows.map { |row| compound_entry_value(row, sub_field) }.reject(&:blank?)
+          next if values.empty?
+
+          spec[:index_keys].each { |index_key| document[index_key] = values }
+        end
+      end
+
+      def index_display_blob(document, compound_name, definition, rows)
+        display_keys = definition[:subfields].select { |_k, spec| spec[:display] }.keys
+        normalized = rows.map { |row| display_entry(row, display_keys) }.reject(&:empty?)
+        document["#{compound_name}_json_ss"] = normalized.to_json unless normalized.empty?
+      end
+
+      def display_entry(row, display_keys)
+        return {} unless row.respond_to?(:each_pair) || row.is_a?(::Hash)
+        display_keys.each_with_object({}) do |key, memo|
+          value = compound_entry_value(row, key)
+          memo[key] = value if value.present?
+        end
+      end
+
+      def compound_entry_value(row, sub_field)
+        return nil unless row.respond_to?(:[])
+        row[sub_field] || row[sub_field.to_sym]
+      end
+    end
+  end
+end
diff --git a/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb b/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
index d6fd2b070a..d356fdb934 100644
--- a/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
+++ b/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
@@ -11,6 +11,9 @@ class PcdmCollectionIndexer < Hyrax::Indexers::ResourceIndexer
       include Hyrax::ThumbnailIndexer
       include Hyrax::Indexer(:core_metadata) if Hyrax.config.collection_include_metadata?
       include Hyrax::Indexers::RedirectsIndexer if Hyrax.config.redirects_enabled?
+      # Flatten compound (hierarchical) metadata sub-fields into Solr. No-op for
+      # collections without compounds. See documentation/forms/compound_fields.md.
+      include Hyrax::Indexers::CompoundIndexer if Hyrax.config.compound_metadata_enabled?
       check_if_flexible(Hyrax::PcdmCollection)
 
       self.thumbnail_path_service = CollectionThumbnailPathService
diff --git a/app/indexers/hyrax/indexers/pcdm_object_indexer.rb b/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
index b6f5a7b175..58100c64bb 100644
--- a/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
+++ b/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
@@ -11,6 +11,9 @@ class PcdmObjectIndexer < Hyrax::Indexers::ResourceIndexer
       include Hyrax::ThumbnailIndexer
       include Hyrax::WorkflowIndexer
       include Hyrax::Indexers::RedirectsIndexer if Hyrax.config.redirects_enabled?
+      # Flatten compound (hierarchical) metadata sub-fields into Solr. No-op for
+      # resources without compounds. See documentation/forms/compound_fields.md.
+      include Hyrax::Indexers::CompoundIndexer if Hyrax.config.compound_metadata_enabled?
 
       def to_solr # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
         super.tap do |solr_doc|
diff --git a/app/models/concerns/hyrax/compound_normalization.rb b/app/models/concerns/hyrax/compound_normalization.rb
new file mode 100644
index 0000000000..62f7fdf5af
--- /dev/null
+++ b/app/models/concerns/hyrax/compound_normalization.rb
@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Hyrax
+  ##
+  # Defends compound attributes (`type: hash, multiple: true` with `subfields:` —
+  # see {Hyrax::CompoundSchema}) against a read-path quirk in Valkyrie's Postgres
+  # orm_converter: `JSONValueMapper` unwraps a single-element array to its first
+  # element and re-symbolizes the Hash's keys, then dry-struct's `Array.of(Hash)`
+  # coercion calls `Array(hash)`, splaying it into pairs. Net effect: a saved
+  # `[{a: 1, b: 2}]` reads back as `[[:a, 1], [:b, 2]]`.
+  #
+  # The compound list comes from the effective schema, so the defense works in
+  # both flex modes. Include this on a resource whose schema declares compounds.
+  module CompoundNormalization
+    extend ActiveSupport::Concern
+
+    # Prepended onto the host class's singleton so it pre-normalizes compound
+    # attrs before dry-struct's strict coercion runs. (In flex mode `.new` routes
+    # through Hyrax::Flexibility#load; the instance write path covers that.)
+    module ClassOverrides
+      def new(attrs = {}, *args)
+        names = (respond_to?(:compound_attribute_names) ? compound_attribute_names : [])
+        attrs = Hyrax::CompoundNormalization.normalize_attrs(attrs, names) if attrs.is_a?(::Hash) && names.any?
+        super
+      end
+    end
+
+    included do
+      singleton_class.prepend(ClassOverrides)
+    end
+
+    class_methods do
+      def compound_attribute_names
+        @compound_attribute_names ||= Hyrax::CompoundSchema.for(self).compound_names
+      rescue StandardError
+        []
+      end
+    end
+
+    def compound_attribute_names
+      @compound_attribute_names ||= Hyrax::CompoundSchema.for(self).compound_names
+    rescue StandardError
+      []
+    end
+
+    def set_value(key, value)
+      value = Hyrax::CompoundNormalization.normalize_compound(value) if compound_attribute_names.include?(key.to_sym)
+      super(key, value)
+    end
+
+    # @api private
+    def self.normalize_attrs(attrs, compound_names)
+      attrs = attrs.dup
+      compound_names.each do |key|
+        [key, key.to_s].each do |k|
+          attrs[k] = normalize_compound(attrs[k]) if attrs.key?(k)
+        end
+      end
+      attrs
+    end
+
+    # @api private
+    def self.normalize_compound(value)
+      return value if value.nil?
+      arr = value.is_a?(::Array) ? value : [value]
+      arr = collapse_pair_array(arr) || collapse_flat_pair(arr) || arr
+      arr.map { |entry| entry.is_a?(::Hash) ? entry.transform_keys(&:to_s) : entry }
+    end
+
+    # Multi-key splay: `[[:a, 1], [:b, 2]]` -> `[{a: 1, b: 2}]`. Returns nil
+    # if the input doesn't look like a pair array.
+    def self.collapse_pair_array(arr)
+      return nil if arr.empty?
+      return nil unless arr.all? { |e| pair?(e) }
+      [::Hash[arr]]
+    end
+
+    # Single-key collapse: `["a", 1]` -> `[{"a" => 1}]`. Returns nil if the
+    # input doesn't look like a single flat pair.
+    def self.collapse_flat_pair(arr)
+      return nil unless arr.length == 2
+      return nil unless arr.first.is_a?(::Symbol) || arr.first.is_a?(::String)
+      return nil if arr.last.is_a?(::Hash) || arr.last.is_a?(::Array)
+      [::Hash[[arr]]]
+    end
+
+    def self.pair?(element)
+      element.is_a?(::Array) &&
+        element.length == 2 &&
+        (element.first.is_a?(::Symbol) || element.first.is_a?(::String))
+    end
+  end
+end
diff --git a/app/models/concerns/hyrax/solr_document/metadata.rb b/app/models/concerns/hyrax/solr_document/metadata.rb
index 7e793d29fd..9e8078da79 100644
--- a/app/models/concerns/hyrax/solr_document/metadata.rb
+++ b/app/models/concerns/hyrax/solr_document/metadata.rb
@@ -9,6 +9,15 @@ def attribute(name, type, field)
             type.coerce(self[field])
           end
         end
+
+        # Declare a reader for a compound attribute, parsing the rows the
+        # indexer stored in `<name>_json_ss`. See
+        # documentation/forms/compound_fields.md.
+        def compound_attribute(name)
+          define_method name do
+            Solr::CompoundEntries.coerce(self["#{name}_json_ss"])
+          end
+        end
       end
 
       module Solr
@@ -19,6 +28,23 @@ def self.coerce(input)
           end
         end
 
+        # Parses a `<compound>_json_ss` field back into an Array of Hashes.
+        class CompoundEntries
+          # @return [Array<Hash>]
+          def self.coerce(input)
+            raw = ::Array.wrap(input).first
+            return [] if raw.blank?
+            parsed = raw.is_a?(::String) ? parse(raw) : raw
+            ::Array.wrap(parsed).select { |e| e.is_a?(::Hash) }
+          end
+
+          def self.parse(raw)
+            JSON.parse(raw)
+          rescue JSON::ParserError
+            []
+          end
+        end
+
         class String
           # @return [String]
           def self.coerce(input)
diff --git a/spec/indexers/hyrax/indexers/compound_indexer_spec.rb b/spec/indexers/hyrax/indexers/compound_indexer_spec.rb
new file mode 100644
index 0000000000..da6bfbfc9c
--- /dev/null
+++ b/spec/indexers/hyrax/indexers/compound_indexer_spec.rb
@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::Indexers::CompoundIndexer do
+  let(:resource_class) do
+    Class.new(Hyrax::Resource) do
+      def self.name
+        'TestIndexedCompoundResource'
+      end
+
+      attribute :contributors,
+                Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
+                  subfields: {
+                    # searchable + facetable, via the literal field names the
+                    # sub-field declares
+                    'given_name' => { 'type' => 'string',
+                                      'index_keys' => %w[contributors_given_name_tesim contributors_given_name_sim] },
+                    # searchable only
+                    'family_name' => { 'type' => 'string',
+                                       'index_keys' => %w[contributors_family_name_tesim] },
+                    # display-only: no index_keys, so no own Solr field, but in the blob
+                    'role_label' => { 'type' => 'controlled', 'authority' => 'contributor_role' },
+                    # searchable but excluded from the display blob
+                    'note' => { 'type' => 'string', 'index_keys' => %w[contributors_note_tesim], 'display' => false }
+                  }
+                )
+    end
+  end
+
+  let(:host_indexer_class) do
+    Class.new(Hyrax::Indexers::ResourceIndexer) do
+      include Hyrax::Indexers::CompoundIndexer
+    end
+  end
+
+  let(:indexer) { host_indexer_class.new(resource: resource) }
+
+  context 'for a resource with compound entries' do
+    let(:resource) do
+      resource_class.new(contributors: [
+                           { 'given_name' => 'Ada', 'family_name' => 'Lovelace', 'role_label' => 'author', 'note' => 'n1' },
+                           { 'given_name' => 'Alan', 'family_name' => 'Turing', 'role_label' => 'author', 'note' => 'n2' }
+                         ])
+    end
+
+    it 'writes each sub-field value to the literal Solr field names it declares' do
+      doc = indexer.to_solr
+      expect(doc['contributors_given_name_tesim']).to contain_exactly('Ada', 'Alan')
+      expect(doc['contributors_given_name_sim']).to contain_exactly('Ada', 'Alan')
+      expect(doc['contributors_family_name_tesim']).to contain_exactly('Lovelace', 'Turing')
+    end
+
+    it 'does not write a Solr field for a sub-field with no index_keys' do
+      # role_label declares no index_keys; it has no field of its own.
+      expect(indexer.to_solr.keys.grep(/role_label/)).to be_empty
+    end
+
+    it 'accepts symbol-keyed entries (JSONValueMapper reload shape)' do
+      resource.contributors = [{ given_name: 'Grace', family_name: 'Hopper' }]
+      doc = indexer.to_solr
+      expect(doc['contributors_given_name_tesim']).to contain_exactly('Grace')
+    end
+
+    it 'stores the displayable sub-fields as a JSON blob for the show page' do
+      parsed = JSON.parse(indexer.to_solr['contributors_json_ss'])
+      # role_label (display-only) is included; note (display: false) is omitted.
+      expect(parsed).to eq([
+                             { 'given_name' => 'Ada', 'family_name' => 'Lovelace', 'role_label' => 'author' },
+                             { 'given_name' => 'Alan', 'family_name' => 'Turing', 'role_label' => 'author' }
+                           ])
+    end
+
+    it 'omits display: false sub-fields from the blob even though they are indexed' do
+      parsed = JSON.parse(indexer.to_solr['contributors_json_ss'])
+      expect(parsed.first).not_to have_key('note')
+      # ...but `note` is still written to its own searchable field
+      expect(indexer.to_solr['contributors_note_tesim']).to contain_exactly('n1', 'n2')
+    end
+  end
+
+  context 'for a resource with no compound entries' do
+    let(:resource) { resource_class.new(contributors: []) }
+
+    it 'emits no compound Solr fields' do
+      expect(indexer.to_solr.keys).not_to include('contributors_given_name_tesim', 'contributors_json_ss')
+    end
+  end
+end
diff --git a/spec/models/concerns/hyrax/compound_normalization_spec.rb b/spec/models/concerns/hyrax/compound_normalization_spec.rb
new file mode 100644
index 0000000000..6afdb157b6
--- /dev/null
+++ b/spec/models/concerns/hyrax/compound_normalization_spec.rb
@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::CompoundNormalization do
+  let(:resource_class) do
+    Class.new(Hyrax::Resource) do
+      def self.name
+        'TestNormalizedCompoundResource'
+      end
+
+      attribute :contributors,
+                Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
+                  subfields: { 'given_name' => { 'type' => 'string' } }
+                )
+
+      include Hyrax::CompoundNormalization
+    end
+  end
+
+  describe '.compound_attribute_names' do
+    it 'derives the compound list from the schema' do
+      expect(resource_class.compound_attribute_names).to contain_exactly(:contributors)
+    end
+  end
+
+  describe 'read-path normalization' do
+    it 'collapses a multi-key splayed pair array back into a hash' do
+      # This is the shape JSONValueMapper produces on reload of a single entry:
+      # the persisted [{given_name:, family:}] is unwrapped and splayed to pairs.
+      expect(Hyrax::CompoundNormalization.normalize_compound([[:given_name, 'Ada'], [:family, 'Lovelace']]))
+        .to eq([{ 'given_name' => 'Ada', 'family' => 'Lovelace' }])
+    end
+
+    it 'leaves a well-formed array of hashes unchanged (stringifying keys)' do
+      expect(Hyrax::CompoundNormalization.normalize_compound([{ given_name: 'Ada' }]))
+        .to eq([{ 'given_name' => 'Ada' }])
+    end
+
+    it 'returns nil unchanged' do
+      expect(Hyrax::CompoundNormalization.normalize_compound(nil)).to be_nil
+    end
+
+    it 'wraps a single hash in an array' do
+      expect(Hyrax::CompoundNormalization.normalize_compound({ 'given_name' => 'Ada' }))
+        .to eq([{ 'given_name' => 'Ada' }])
+    end
+  end
+
+  describe 'round-trip through the class constructor' do
+    it 'normalizes splayed compound input passed to .new' do
+      resource = resource_class.new(contributors: [[:given_name, 'Ada']])
+      expect(resource.contributors).to eq([{ 'given_name' => 'Ada' }])
+    end
+
+    it 'normalizes well-formed compound input passed to .new' do
+      resource = resource_class.new(contributors: [{ 'given_name' => 'Grace' }])
+      expect(resource.contributors).to eq([{ 'given_name' => 'Grace' }])
+    end
+  end
+end

From c5c86378aee15356cb9c86d35dd12cb6d95f659e Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 15:37:37 -0400
Subject: [PATCH 04/32] Render compound metadata on show pages

Show pages render compound metadata through a generic renderer: each
entry's populated sub-fields display as a labeled block, controlled
sub-fields show their term rather than the stored id, urls are linked,
and a work-or-url value links to the internal work or the external URL.

A compound can render inline in the metadata list or, with
view: { display: card }, as its own card on works and collections. The
work-or-url picker searches readable works by any indexed term or a
partial title.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .rubocop.yml                                  |   1 +
 .../stylesheets/hyrax/_compound_metadata.scss |  52 +++++++
 app/assets/stylesheets/hyrax/_hyrax.scss      |   2 +-
 .../qa/authorities/compound_works.rb          |  43 ++++++
 app/helpers/hyrax/collections_helper.rb       |  13 ++
 app/presenters/hyrax/collection_presenter.rb  |  39 +++++-
 app/presenters/hyrax/presents_attributes.rb   |  14 ++
 .../renderers/compound_attribute_renderer.rb  | 113 +++++++++++++++
 .../hyrax/compound_work_picker_builder.rb     |  62 ++++++++
 .../hyrax/compound_subfield_labeler.rb        |  43 ++++++
 app/services/hyrax/compound_work_resolver.rb  |  42 ++++++
 app/views/hyrax/base/_attribute_rows.html.erb |   1 +
 app/views/hyrax/base/show.html.erb            |   4 +
 app/views/hyrax/collections/show.html.erb     |   4 +
 .../hyrax/compounds/_compound_card.html.erb   |  20 +++
 .../hyrax/dashboard/collections/show.html.erb |   2 +
 .../qa/authorities/compound_works_spec.rb     |  43 ++++++
 .../compound_attribute_renderer_spec.rb       | 132 ++++++++++++++++++
 .../compound_work_picker_builder_spec.rb      |  74 ++++++++++
 .../hyrax/compound_subfield_labeler_spec.rb   |  50 +++++++
 .../hyrax/compound_work_resolver_spec.rb      |  45 ++++++
 21 files changed, 797 insertions(+), 2 deletions(-)
 create mode 100644 app/assets/stylesheets/hyrax/_compound_metadata.scss
 create mode 100644 app/authorities/qa/authorities/compound_works.rb
 create mode 100644 app/renderers/hyrax/renderers/compound_attribute_renderer.rb
 create mode 100644 app/search_builders/hyrax/compound_work_picker_builder.rb
 create mode 100644 app/services/hyrax/compound_subfield_labeler.rb
 create mode 100644 app/services/hyrax/compound_work_resolver.rb
 create mode 100644 app/views/hyrax/compounds/_compound_card.html.erb
 create mode 100644 spec/authorities/qa/authorities/compound_works_spec.rb
 create mode 100644 spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
 create mode 100644 spec/search_builders/hyrax/compound_work_picker_builder_spec.rb
 create mode 100644 spec/services/hyrax/compound_subfield_labeler_spec.rb
 create mode 100644 spec/services/hyrax/compound_work_resolver_spec.rb

diff --git a/.rubocop.yml b/.rubocop.yml
index 6cb6d839a4..3442a3b2e4 100644
--- a/.rubocop.yml
+++ b/.rubocop.yml
@@ -95,6 +95,7 @@ Rails/OutputSafety:
     - 'app/presenters/hyrax/fixity_status_presenter.rb'
     - 'app/presenters/hyrax/presents_attributes.rb'
     - 'app/renderers/hyrax/renderers/attribute_renderer.rb'
+    - 'app/renderers/hyrax/renderers/compound_attribute_renderer.rb'
     - 'spec/views/hyrax/my/works/_list_works.html.erb_spec.rb'
 
 RSpec/DescribeClass:
diff --git a/app/assets/stylesheets/hyrax/_compound_metadata.scss b/app/assets/stylesheets/hyrax/_compound_metadata.scss
new file mode 100644
index 0000000000..d162a87976
--- /dev/null
+++ b/app/assets/stylesheets/hyrax/_compound_metadata.scss
@@ -0,0 +1,52 @@
+// Compound metadata display on work and collection show pages.
+// See documentation/forms/compound_fields.md.
+//
+// `!important` throughout: the collection metadata area styles nested divs with
+// a descendant selector (`.hyc-metadata div { display: flex; border-bottom }`
+// in _collections.scss) that would otherwise turn each entry into a bordered
+// flex row. These rules override it regardless of source order.
+.hyrax-compound-values {
+  display: block !important;
+  flex-direction: column;
+  border: 0 !important;
+  // Indent to align with scalar metadata values (their `ul.tabular` keeps the
+  // browser default ~40px list padding).
+  padding: 0 0 0 40px !important;
+  max-width: 100%;
+
+  // Force block flow on the entries/sub-fields; the label/value spans stay
+  // inline so each sub-field reads as "Label: value" on one wrapping line.
+  .hyrax-compound-entry,
+  .hyrax-compound-subfield {
+    display: block !important;
+  }
+
+  .hyrax-compound-entry,
+  .hyrax-compound-subfield,
+  .hyrax-compound-subfield-label,
+  .hyrax-compound-subfield-value {
+    border: 0 !important;
+    padding: 0 !important;
+    margin: 0;
+    background: none;
+  }
+
+  // A light divider between entries.
+  .hyrax-compound-entry + .hyrax-compound-entry {
+    margin-top: 0.5rem;
+    padding-top: 0.5rem !important;
+    border-top: 1px solid $gray-200 !important;
+  }
+
+  .hyrax-compound-subfield {
+    display: block;
+    line-height: 1.4;
+    overflow-wrap: break-word;
+    word-break: break-word;
+  }
+
+  .hyrax-compound-subfield-label {
+    font-weight: 600;
+    margin-right: 0.25rem;
+  }
+}
diff --git a/app/assets/stylesheets/hyrax/_hyrax.scss b/app/assets/stylesheets/hyrax/_hyrax.scss
index 18076b42f9..c4a1fc55d7 100644
--- a/app/assets/stylesheets/hyrax/_hyrax.scss
+++ b/app/assets/stylesheets/hyrax/_hyrax.scss
@@ -10,7 +10,7 @@
   "hyrax/select_work_type", "hyrax/users", "hyrax/dashboard", "hyrax/sidebar",
   "hyrax/controlled_vocabulary", "hyrax/accessibility", "hyrax/recent",
   "hyrax/viewer", "hyrax/breadcrumbs", "hyrax/facets", "hyrax/card",
-  "hyrax/badge";
+  "hyrax/badge", "hyrax/compound_metadata";
 @import "hydra-editor/multi_value_fields";
 @import "typeahead";
 @import "sharing_buttons";
diff --git a/app/authorities/qa/authorities/compound_works.rb b/app/authorities/qa/authorities/compound_works.rb
new file mode 100644
index 0000000000..66e70cba84
--- /dev/null
+++ b/app/authorities/qa/authorities/compound_works.rb
@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Qa::Authorities
+  ##
+  # Autocomplete authority for the compound `work_or_url` sub-field's work
+  # picker, mounted at `/authorities/search/compound_works`. Returns readable
+  # works matched by {Hyrax::CompoundWorkPickerBuilder}.
+  class CompoundWorks < Qa::Authorities::Base
+    class_attribute :search_builder_class
+    self.search_builder_class = Hyrax::CompoundWorkPickerBuilder
+
+    def search(_q, controller)
+      return [] unless controller.current_user
+
+      response, _docs = search_response(controller)
+      response.documents.map do |doc|
+        { id: doc.id, label: Array(doc.title).first || doc.id, value: doc.id }
+      end
+    end
+
+    private
+
+    def search_service(controller)
+      @search_service ||= Hyrax::SearchService.new(
+        config: controller.blacklight_config,
+        user_params: controller.params,
+        search_builder_class: search_builder_class,
+        scope: controller,
+        current_ability: controller.current_ability
+      )
+    end
+
+    def search_response(controller)
+      access = controller.params[:access] || 'read'
+
+      search_service(controller).search_results do |builder|
+        builder.with({ q: controller.params[:q] })
+               .with_access(access)
+               .rows(20)
+      end
+    end
+  end
+end
diff --git a/app/helpers/hyrax/collections_helper.rb b/app/helpers/hyrax/collections_helper.rb
index 09374db983..31786029a9 100644
--- a/app/helpers/hyrax/collections_helper.rb
+++ b/app/helpers/hyrax/collections_helper.rb
@@ -37,6 +37,19 @@ def collection_metadata_label(collection, field)
     # @since 3.0.0
     # @return [#to_s]
     def collection_metadata_value(collection, field)
+      # Compounds render through the shared CompoundAttributeRenderer. The show
+      # partials already wrap label/value in <dt>/<dd>, so render only the entry
+      # rows; pass the sub-field specs so controlled ids display as their term.
+      # See documentation/forms/compound_fields.md.
+      if collection.respond_to?(:compound_term?) && collection.compound_term?(field)
+        definition = Hyrax::CompoundSchema.for(Hyrax.config.collection_class).definition_for(field)
+        return Hyrax::Renderers::CompoundAttributeRenderer
+               .new(field, collection[field],
+                    label: collection_metadata_label(collection, field),
+                    subfields: definition&.fetch(:subfields, nil))
+               .render_value
+      end
+
       Hyrax::PresenterRenderer.new(collection, self).value(field)
     end
 
diff --git a/app/presenters/hyrax/collection_presenter.rb b/app/presenters/hyrax/collection_presenter.rb
index a4a567f301..cf1046a0fc 100644
--- a/app/presenters/hyrax/collection_presenter.rb
+++ b/app/presenters/hyrax/collection_presenter.rb
@@ -44,13 +44,50 @@ def collection_type
     # app/views/collections/_show_descriptions.html.erb
     def self.terms
       [:total_items, :alternative_title, :size, :resource_type, :creator, :contributor, :keyword, :license, :publisher, :date_created, :subject,
-       :language, :identifier, :based_near, :related_url]
+       :language, :identifier, :based_near, :related_url] + compound_terms
+    end
+
+    # Compound terms that render inline in the collection metadata list. Card
+    # compounds are excluded (they render via `render_compound_cards`). See
+    # documentation/forms/compound_fields.md.
+    def self.compound_terms
+      return [] unless Hyrax.config.compound_metadata_enabled?
+      Hyrax::CompoundSchema.for(Hyrax.config.collection_class).inline_compound_names
+    rescue StandardError
+      []
     end
 
     def terms_with_values
       self.class.terms.select { |t| self[t].present? }
     end
 
+    def compound_terms
+      self.class.compound_terms
+    end
+
+    def compound_term?(term)
+      compound_terms.include?(term.to_sym)
+    end
+
+    def self.all_compound_names
+      return [] unless Hyrax.config.compound_metadata_enabled?
+      Hyrax::CompoundSchema.for(Hyrax.config.collection_class).compound_names
+    rescue StandardError
+      []
+    end
+
+    # Delegate compound readers to the solr document so the card display
+    # resolves on a collection as on a work. Via method_missing because the
+    # compound set is schema-driven, not known at class-definition time.
+    def respond_to_missing?(name, include_private = false)
+      self.class.all_compound_names.include?(name.to_sym) || super
+    end
+
+    def method_missing(name, *args, &block)
+      return solr_document.send(name, *args, &block) if self.class.all_compound_names.include?(name.to_sym)
+      super
+    end
+
     ##
     # @param [Symbol] key
     # @return [Object]
diff --git a/app/presenters/hyrax/presents_attributes.rb b/app/presenters/hyrax/presents_attributes.rb
index 2b074eba3e..ed165b8e38 100644
--- a/app/presenters/hyrax/presents_attributes.rb
+++ b/app/presenters/hyrax/presents_attributes.rb
@@ -19,6 +19,8 @@ def attribute_to_html(field, options = {})
         return
       end
 
+      options = options.merge(subfields: compound_subfields_for(field)) if options[:render_as].to_s == 'compound'
+
       if options[:html_dl]
         renderer_for(field, options).new(field, send(field), options).render_dl_row
       else
@@ -46,6 +48,18 @@ def microdata_type_to_html
 
     private
 
+    # Normalized sub-field specs for a compound, so the renderer can translate
+    # controlled ids to their terms; nil if the resource class can't be
+    # resolved (the renderer then renders raw values).
+    def compound_subfields_for(field)
+      klass = solr_document.try(:hydra_model) if respond_to?(:solr_document)
+      return nil unless klass
+      Hyrax::CompoundSchema.for(klass).definition_for(field)&.fetch(:subfields, nil)
+    rescue StandardError => e
+      Hyrax.logger.debug("compound_subfields_for(#{field}): #{e.message}")
+      nil
+    end
+
     def find_renderer_class(name)
       renderer = nil
       ['Renderer', 'AttributeRenderer'].each do |suffix|
diff --git a/app/renderers/hyrax/renderers/compound_attribute_renderer.rb b/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
new file mode 100644
index 0000000000..cdbc8718e3
--- /dev/null
+++ b/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Hyrax
+  module Renderers
+    ##
+    # Renders a compound metadata attribute on a show page (selected via
+    # `view: { render_as: compound }`). Each value is one entry — a hash of
+    # sub-fields produced by the SolrDocument `compound_attribute` reader — and
+    # renders as a block of its populated sub-fields. Sub-field labels come from
+    # the `hyrax.compound_fields.<compound>.<subfield>` i18n keys.
+    class CompoundAttributeRenderer < AttributeRenderer
+      def render
+        return '' if blank_values? && !options[:include_empty]
+
+        %(<tr><th>#{label}</th>\n<td>#{entries_markup}</td></tr>).html_safe
+      end
+
+      def render_dl_row
+        return '' if blank_values? && !options[:include_empty]
+
+        %(<dt>#{label}</dt>\n<dd>#{entries_markup}</dd>).html_safe
+      end
+
+      # Just the entry rows, without a surrounding label/row wrapper. Used by
+      # views that supply their own `<dt>`/`<dd>` (e.g. the collection show
+      # descriptions), so the markup isn't double-nested.
+      def render_value
+        return '' if blank_values? && !options[:include_empty]
+
+        entries_markup.html_safe
+      end
+
+      private
+
+      def blank_values?
+        Array(values).reject { |entry| entry_to_pairs(entry).empty? }.empty?
+      end
+
+      def entries_markup
+        rows = Array(values).map { |entry| entry_markup(entry) }.reject(&:blank?)
+        # Plain <div>s (not <dl>/<dt>/<dd>) so entries don't inherit the metadata
+        # list's divider/border styling, which would draw stray lines.
+        %(<div class="hyrax-compound-values">#{rows.join}</div>)
+      end
+
+      def entry_markup(entry)
+        pairs = entry_to_pairs(entry)
+        return '' if pairs.empty?
+
+        items = pairs.map { |sub_field, value| subfield_markup(sub_field, value) }.join
+        %(<div class="hyrax-compound-entry">#{items}</div>)
+      end
+
+      def subfield_markup(sub_field, value)
+        label_html = ERB::Util.h(sub_field_label(sub_field))
+        %(<div class="hyrax-compound-subfield">) +
+          %(<span class="hyrax-compound-subfield-label">#{label_html}:</span> ) +
+          %(<span class="hyrax-compound-subfield-value">#{value_markup(sub_field, value)}</span>) +
+          %(</div>)
+      end
+
+      # Display markup for one sub-field value, by sub-field type: `url` and
+      # `work_or_url` are linked; otherwise escaped text with controlled ids
+      # translated to their term.
+      def value_markup(sub_field, value)
+        return ERB::Util.h(display_value(sub_field, value)) if value.blank?
+
+        case subfield_spec(sub_field)&.dig(:type).to_s
+        when 'url'
+          auto_link(ERB::Util.h(value.to_s))
+        when 'work_or_url'
+          work_or_url_markup(value)
+        else
+          ERB::Util.h(display_value(sub_field, value))
+        end
+      end
+
+      def work_or_url_markup(value)
+        if Hyrax::CompoundWorkResolver.url?(value)
+          auto_link(ERB::Util.h(value.to_s))
+        else
+          title, path = Hyrax::CompoundWorkResolver.title_and_path(value)
+          link_to(ERB::Util.h(title), path)
+        end
+      end
+
+      def display_value(sub_field, value)
+        Hyrax::CompoundSubfieldLabeler.label_for(subfield_spec(sub_field), value)
+      end
+
+      # The normalized sub-field spec, supplied by the caller via
+      # `options[:subfields]`.
+      def subfield_spec(sub_field)
+        specs = options[:subfields]
+        return nil unless specs.is_a?(Hash)
+        specs[sub_field] || specs[sub_field.to_sym]
+      end
+
+      # Populated [sub_field, value] pairs for one entry; blanks dropped.
+      def entry_to_pairs(entry)
+        return [] unless entry.respond_to?(:each_pair) || entry.is_a?(::Hash)
+        entry.to_h.each_with_object([]) do |(key, value), memo|
+          next if value.blank?
+          memo << [key.to_s, value]
+        end
+      end
+
+      def sub_field_label(sub_field)
+        I18n.t("hyrax.compound_fields.#{field}.#{sub_field}", default: sub_field.to_s.humanize)
+      end
+    end
+  end
+end
diff --git a/app/search_builders/hyrax/compound_work_picker_builder.rb b/app/search_builders/hyrax/compound_work_picker_builder.rb
new file mode 100644
index 0000000000..78299d3f50
--- /dev/null
+++ b/app/search_builders/hyrax/compound_work_picker_builder.rb
@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Hyrax
+  ##
+  # Search builder for the compound `work_or_url` sub-field's work picker. Finds
+  # works the current user can read (it subclasses {Hyrax::SearchBuilder}, so
+  # permission filtering is retained), matching any indexed query term OR a
+  # partial/prefix title.
+  class CompoundWorkPickerBuilder < Hyrax::SearchBuilder
+    include Hyrax::FilterByType
+
+    self.default_processor_chain += [:filter_on_any_term_or_partial_title]
+
+    def initialize(context)
+      super(context)
+      @q = context.params[:q]
+    end
+
+    def only_works?
+      true
+    end
+
+    # ORs a multi-field term match with a prefix-wildcard title match. The rest
+    # of the processor chain still applies the permission and type filters.
+    def filter_on_any_term_or_partial_title(solr_parameters)
+      return if @q.blank?
+
+      term = @q.to_s.strip
+      solr_parameters[:q] = "#{multi_field_clause(term)} OR #{prefix_title_clause(term)}"
+      solr_parameters[:defType] = 'lucene'
+    end
+
+    private
+
+    def multi_field_clause(term)
+      escaped = escape(term)
+      QUERY_FIELDS.map { |field| "#{field}:(#{escaped})" }.join(' OR ')
+    end
+
+    # Prefix-wildcard on each whitespace-separated token of the title, e.g.
+    # "jour stud" -> title_tesim:(jour* AND stud*).
+    def prefix_title_clause(term)
+      tokens = term.split(/\s+/).reject(&:empty?).map { |t| "#{escape_token(t)}*" }
+      return '' if tokens.empty?
+      "title_tesim:(#{tokens.join(' AND ')})"
+    end
+
+    QUERY_FIELDS = %w[title_tesim description_tesim creator_tesim keyword_tesim].freeze
+
+    # Escape Solr/Lucene special characters in a phrase (wildcards included —
+    # the multi-field clause is not a prefix search).
+    def escape(value)
+      value.to_s.gsub(%r{([+\-&|!(){}\[\]^"~*?:\\/])}, '\\\\\1')
+    end
+
+    # Escape special characters in a single token but keep it usable as a
+    # prefix (the trailing `*` is added by the caller, not escaped here).
+    def escape_token(value)
+      value.to_s.gsub(%r{([+\-&|!(){}\[\]^"~?:\\/])}, '\\\\\1')
+    end
+  end
+end
diff --git a/app/services/hyrax/compound_subfield_labeler.rb b/app/services/hyrax/compound_subfield_labeler.rb
new file mode 100644
index 0000000000..4d0e2d4663
--- /dev/null
+++ b/app/services/hyrax/compound_subfield_labeler.rb
@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Hyrax
+  ##
+  # @api public
+  #
+  # Resolves a `controlled` compound sub-field's stored id to its display term
+  # (via inline `values:` or a QA `authority:`). Non-controlled sub-fields and
+  # ids with no matching term fall back to the value itself.
+  class CompoundSubfieldLabeler
+    ##
+    # @param spec [Hash, nil] the normalized sub-field spec
+    #   (`{ type:, authority:, values: }`) from {Hyrax::CompoundSchema}
+    # @param value [Object] the stored value (id for controlled sub-fields)
+    #
+    # @return [String] the term to display
+    def self.label_for(spec, value)
+      return value.to_s if spec.nil? || spec[:type].to_s != 'controlled' || value.blank?
+
+      if spec[:values].present?
+        label_from_values(spec[:values], value)
+      elsif spec[:authority].present?
+        label_from_authority(spec[:authority], value)
+      else
+        value.to_s
+      end
+    end
+
+    def self.label_from_values(values, value)
+      pair = Array(values).find { |(_label, id)| id.to_s == value.to_s }
+      pair ? pair.first.to_s : value.to_s
+    end
+    private_class_method :label_from_values
+
+    def self.label_from_authority(authority_name, value)
+      Hyrax::TolerantSelectService.new(authority_name).label(value.to_s) { value.to_s }
+    rescue StandardError => e
+      Hyrax.logger.debug("CompoundSubfieldLabeler: #{authority_name}: #{e.message}")
+      value.to_s
+    end
+    private_class_method :label_from_authority
+  end
+end
diff --git a/app/services/hyrax/compound_work_resolver.rb b/app/services/hyrax/compound_work_resolver.rb
new file mode 100644
index 0000000000..519e82c3df
--- /dev/null
+++ b/app/services/hyrax/compound_work_resolver.rb
@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Hyrax
+  ##
+  # @api public
+  #
+  # Helpers for the `work_or_url` compound sub-field, whose stored value is
+  # either an external URL or an internal work id. Distinguishes the two and
+  # resolves an internal work id to a display title (from Solr) and a show path.
+  class CompoundWorkResolver
+    # A value is an external URL when it has an http(s) scheme; Valkyrie ids
+    # never do.
+    def self.url?(value)
+      value.to_s.match?(%r{\Ahttps?://}i)
+    end
+
+    ##
+    # @param id [String] an internal work id
+    # @return [Array(String, String)] the work's title (falling back to the id)
+    #   and its show path
+    def self.title_and_path(id)
+      [title_for(id), path_for(id)]
+    end
+
+    def self.title_for(id)
+      doc = Hyrax::SolrService.query("{!field f=id}#{id}", fl: 'title_tesim', rows: 1).first
+      Array(doc&.fetch('title_tesim', nil)).first.presence || id.to_s
+    rescue StandardError => e
+      Hyrax.logger.debug("CompoundWorkResolver.title_for(#{id}): #{e.message}")
+      id.to_s
+    end
+
+    # The model-agnostic Blacklight show route (`/catalog/:id`) links any
+    # indexed work without knowing its class.
+    def self.path_for(id)
+      Rails.application.routes.url_helpers.solr_document_path(id)
+    rescue StandardError => e
+      Hyrax.logger.debug("CompoundWorkResolver.path_for(#{id}): #{e.message}")
+      "/catalog/#{id}"
+    end
+  end
+end
diff --git a/app/views/hyrax/base/_attribute_rows.html.erb b/app/views/hyrax/base/_attribute_rows.html.erb
index cee841ff19..9baa1098d4 100644
--- a/app/views/hyrax/base/_attribute_rows.html.erb
+++ b/app/views/hyrax/base/_attribute_rows.html.erb
@@ -1,4 +1,5 @@
 <% view_options_for(presenter).each do |field, options| %>
+  <% next if compound_card_field?(presenter, field) # rendered as its own card, not inline %>
   <% view_options = conform_options(field, options) %>
   <%= presenter.attribute_to_html(conform_field(field, options), view_options) if field_visible?(view_options, presenter) %>
 <% end %>
diff --git a/app/views/hyrax/base/show.html.erb b/app/views/hyrax/base/show.html.erb
index 6f0d84372a..818ab1f47f 100644
--- a/app/views/hyrax/base/show.html.erb
+++ b/app/views/hyrax/base/show.html.erb
@@ -34,6 +34,10 @@
       </div>
     </div><!-- /.card -->
 
+    <%# Compounds declared `view: { display: card }` render as their own cards,
+        above the Relationships and Items cards. %>
+    <%= render_compound_cards(@presenter) %>
+
     <div class="card">
       <div class="card-header">
         <h2 class="card-title"><%= t('hyrax.base.show.relationships') %></h2>
diff --git a/app/views/hyrax/collections/show.html.erb b/app/views/hyrax/collections/show.html.erb
index 0b9f273e84..d6dee07ef4 100644
--- a/app/views/hyrax/collections/show.html.erb
+++ b/app/views/hyrax/collections/show.html.erb
@@ -99,6 +99,10 @@
     </div>
   </div>
 
+  <%# Compounds declared `view: { display: card }` render as their own cards,
+      after the search-within-collection bar and before the works list. %>
+  <%= render_compound_cards(@presenter) %>
+
   <!-- Subcollections -->
   <% if @presenter.collection_type_is_nestable? && @subcollection_count > 0 %>
       <div class="hyc-blacklight hyc-bl-title">
diff --git a/app/views/hyrax/compounds/_compound_card.html.erb b/app/views/hyrax/compounds/_compound_card.html.erb
new file mode 100644
index 0000000000..05ad41c465
--- /dev/null
+++ b/app/views/hyrax/compounds/_compound_card.html.erb
@@ -0,0 +1,20 @@
+<%# Renders one compound attribute as its own titled card on a show page,
+    matching the relationships/items cards. Opted in via the schema's
+    `view: { display: card }`. The card body reuses the standard compound
+    rendering (CompoundAttributeRenderer) via attribute_to_html.
+
+    Locals:
+      presenter - a work or collection show presenter
+      field     - the compound attribute name (Symbol)
+%>
+<div class="card hyrax-compound-card">
+  <div class="card-header">
+    <h2 class="card-title"><%= compound_field_label(field) %></h2>
+  </div>
+  <div class="card-body">
+    <dl class="work-show">
+      <%= presenter.attribute_to_html(field.to_sym, render_as: :compound, html_dl: true,
+                                      label: compound_field_label(field)) %>
+    </dl>
+  </div>
+</div>
diff --git a/app/views/hyrax/dashboard/collections/show.html.erb b/app/views/hyrax/dashboard/collections/show.html.erb
index bb3f9c91c6..a3b32e16a4 100644
--- a/app/views/hyrax/dashboard/collections/show.html.erb
+++ b/app/views/hyrax/dashboard/collections/show.html.erb
@@ -33,6 +33,8 @@
 
             <% unless collection_search_parameters? %>
               <%= render 'show_descriptions' %>
+              <%# Compounds declared `view: { display: card }` render as their own cards. %>
+              <%= render_compound_cards(@presenter) %>
             <% end %>
           </div>
         </div>
diff --git a/spec/authorities/qa/authorities/compound_works_spec.rb b/spec/authorities/qa/authorities/compound_works_spec.rb
new file mode 100644
index 0000000000..238d08ed73
--- /dev/null
+++ b/spec/authorities/qa/authorities/compound_works_spec.rb
@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+RSpec.describe Qa::Authorities::CompoundWorks, :clean_repo do
+  let(:controller) { Qa::TermsController.new }
+  let(:user) { create(:user) }
+  let(:ability) { instance_double(Ability, admin?: false, user_groups: ['public', 'registered'], current_user: user) }
+  let(:q) { "journal" }
+  let(:params) do
+    ActionController::Parameters.new(q: q, user: user.user_key,
+                                     controller: "qa/terms", action: "search", vocab: "compound_works")
+  end
+  let(:service) { described_class.new }
+  let!(:journal) { valkyrie_create(:monograph, :public, title: ['Journal of Practice Research']) }
+  let!(:other)   { valkyrie_create(:monograph, :public, title: ['Unrelated Book']) }
+
+  before do
+    allow(controller).to receive(:params).and_return(params)
+    allow(controller).to receive(:current_ability).and_return(ability)
+  end
+
+  subject { service.search(q, controller) }
+
+  describe '#search' do
+    before { allow(controller).to receive(:current_user).and_return(user) }
+
+    it 'returns readable works matched by a partial title' do
+      expect(subject.map { |result| result[:id] }).to include(journal.id)
+      expect(subject.map { |result| result[:id] }).not_to include(other.id)
+    end
+
+    it 'shapes each result as { id:, label:, value: }' do
+      result = subject.find { |r| r[:id] == journal.id }
+      expect(result).to include(id: journal.id, label: 'Journal of Practice Research', value: journal.id)
+    end
+  end
+
+  describe '#search without a current user' do
+    before { allow(controller).to receive(:current_user).and_return(nil) }
+
+    it 'returns an empty list' do
+      expect(subject).to eq([])
+    end
+  end
+end
diff --git a/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb b/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
new file mode 100644
index 0000000000..f2b04e88e9
--- /dev/null
+++ b/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::Renderers::CompoundAttributeRenderer do
+  let(:values) do
+    [{ 'title' => 'Dr', 'agent_name' => 'Ada Lovelace', 'agent_role' => 'Author' },
+     { 'agent_name' => 'Alan Turing' }]
+  end
+  let(:renderer) { described_class.new(:agent, values, label: 'Agent', html_dl: true) }
+
+  describe '#render_dl_row' do
+    subject(:markup) { renderer.render_dl_row }
+
+    it 'renders the field label' do
+      expect(markup).to include('<dt>Agent</dt>')
+    end
+
+    it 'renders one entry block per value' do
+      expect(markup.scan('class="hyrax-compound-entry"').count).to eq(2)
+    end
+
+    it 'renders each populated sub-field as a labeled value' do
+      expect(markup).to include('Ada Lovelace').and include('Author')
+      expect(markup).to include('Alan Turing')
+    end
+
+    it 'uses the i18n sub-field labels (humanized fallback)' do
+      # `title` has no compound_fields.agent.title key in the engine locale by
+      # default for an arbitrary compound, so it humanizes; agent_name maps to
+      # the shipped label "Name".
+      expect(markup).to include('Dr')
+    end
+
+    it 'does not use <dl>/<dt>/<dd> for entries (avoids inheriting metadata dividers)' do
+      entries = markup.split('hyrax-compound-values').last
+      expect(entries).not_to include('<dt')
+      expect(entries).not_to include('<dd')
+    end
+
+    it 'omits blank sub-fields' do
+      # The second entry has only agent_name; it should not emit empty subfield blocks.
+      second_entry = markup.split('hyrax-compound-entry').last
+      expect(second_entry.scan('hyrax-compound-subfield"').count).to eq(1)
+    end
+  end
+
+  describe 'empty handling' do
+    it 'renders nothing for all-blank entries without include_empty' do
+      r = described_class.new(:agent, [{ 'agent_name' => '' }], label: 'Agent', html_dl: true)
+      expect(r.render_dl_row).to eq('')
+    end
+  end
+
+  describe '#render (table row)' do
+    it 'renders a table row with the label and entries' do
+      markup = described_class.new(:agent, values, label: 'Agent').render
+      expect(markup).to include('<th>Agent</th>')
+      expect(markup).to include('Ada Lovelace')
+    end
+  end
+
+  describe 'controlled sub-field term translation' do
+    let(:values) { [{ 'role' => 'ed', 'name' => 'Ada' }] }
+    let(:subfields) do
+      { 'role' => { type: 'controlled', authority: nil, values: [%w[Author author], %w[Editor ed]] },
+        'name' => { type: 'string', authority: nil, values: nil } }
+    end
+    let(:renderer) { described_class.new(:agent, values, label: 'Agent', html_dl: true, subfields: subfields) }
+
+    it 'displays the controlled term, not the stored id' do
+      markup = renderer.render_dl_row
+      expect(markup).to include('Editor')
+      expect(markup).not_to match(/>ed</)
+    end
+
+    it 'leaves non-controlled sub-fields unchanged' do
+      expect(renderer.render_dl_row).to include('Ada')
+    end
+
+    it 'renders the raw id when no subfields specs are provided' do
+      markup = described_class.new(:agent, values, label: 'Agent', html_dl: true).render_dl_row
+      expect(markup).to include('ed')
+    end
+  end
+
+  describe 'url sub-field auto-linking' do
+    let(:values) { [{ 'related_item_url' => 'https://example.org/item/42', 'note' => 'see also' }] }
+    let(:subfields) do
+      { 'related_item_url' => { type: 'url', authority: nil, values: nil },
+        'note' => { type: 'string', authority: nil, values: nil } }
+    end
+    let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subfields: subfields) }
+
+    it 'renders a url sub-field as an anchor' do
+      expect(renderer.render_dl_row).to include('<a href="https://example.org/item/42"')
+    end
+
+    it 'leaves non-url sub-fields as plain escaped text' do
+      markup = renderer.render_dl_row
+      expect(markup).to include('see also')
+      expect(markup).not_to include('<a href="see also"')
+    end
+  end
+
+  describe 'work_or_url sub-field' do
+    let(:subfields) { { 'related_item' => { type: 'work_or_url', authority: nil, values: nil } } }
+
+    context 'when the value is an external URL' do
+      let(:values) { [{ 'related_item' => 'https://example.org/x' }] }
+      let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subfields: subfields) }
+
+      it 'auto-links the URL' do
+        expect(renderer.render_dl_row).to include('<a href="https://example.org/x"')
+      end
+    end
+
+    context 'when the value is an internal work id' do
+      let(:values) { [{ 'related_item' => 'work-123' }] }
+      let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subfields: subfields) }
+
+      before do
+        allow(Hyrax::CompoundWorkResolver).to receive(:title_and_path)
+          .with('work-123').and_return(['Linked Work', '/catalog/work-123'])
+      end
+
+      it 'links to the work show path with its title' do
+        markup = renderer.render_dl_row
+        expect(markup).to include('href="/catalog/work-123"')
+        expect(markup).to include('Linked Work')
+      end
+    end
+  end
+end
diff --git a/spec/search_builders/hyrax/compound_work_picker_builder_spec.rb b/spec/search_builders/hyrax/compound_work_picker_builder_spec.rb
new file mode 100644
index 0000000000..e200ed4f23
--- /dev/null
+++ b/spec/search_builders/hyrax/compound_work_picker_builder_spec.rb
@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+RSpec.describe Hyrax::CompoundWorkPickerBuilder do
+  let(:user) { create(:user) }
+  let(:ability) { instance_double(Ability, admin?: false, user_groups: [], current_user: user) }
+  let(:params) do
+    ActionController::Parameters.new(q: q, user: user.email,
+                                     controller: "qa/terms", action: "search", vocab: "compound_works")
+  end
+  let(:context) do
+    FakeSearchBuilderScope.new(current_ability: ability, current_user: user, params: params)
+  end
+  let(:builder) { described_class.new(context) }
+  let(:solr_params) { Blacklight::Solr::Request.new }
+
+  describe "::default_processor_chain" do
+    it "appends the broad-term/partial-title filter" do
+      expect(described_class.default_processor_chain).to include(:filter_on_any_term_or_partial_title)
+    end
+  end
+
+  describe "#only_works?" do
+    let(:q) { "foo" }
+
+    it "restricts to works" do
+      expect(builder.only_works?).to be true
+    end
+  end
+
+  describe "#filter_on_any_term_or_partial_title" do
+    subject { builder.filter_on_any_term_or_partial_title(solr_params) }
+
+    context "with a single-token term" do
+      let(:q) { "journal" }
+
+      it "ORs a multi-field match with a prefix-title match and uses the lucene parser" do
+        subject
+        expect(solr_params[:q]).to eq(
+          "title_tesim:(journal) OR description_tesim:(journal) OR " \
+          "creator_tesim:(journal) OR keyword_tesim:(journal) OR " \
+          "title_tesim:(journal*)"
+        )
+        expect(solr_params[:defType]).to eq("lucene")
+      end
+    end
+
+    context "with a multi-token term" do
+      let(:q) { "journal studies" }
+
+      it "ANDs prefix wildcards across the title tokens" do
+        subject
+        expect(solr_params[:q]).to end_with("title_tesim:(journal* AND studies*)")
+      end
+    end
+
+    context "with a blank term" do
+      let(:q) { "" }
+
+      it "leaves the solr parameters untouched" do
+        subject
+        expect(solr_params[:q]).to be_nil
+        expect(solr_params[:defType]).to be_nil
+      end
+    end
+
+    context "with Solr special characters in the term" do
+      let(:q) { "a:b" }
+
+      it "escapes the special characters" do
+        subject
+        expect(solr_params[:q]).to include('title_tesim:(a\\:b)')
+      end
+    end
+  end
+end
diff --git a/spec/services/hyrax/compound_subfield_labeler_spec.rb b/spec/services/hyrax/compound_subfield_labeler_spec.rb
new file mode 100644
index 0000000000..ed5af5ade2
--- /dev/null
+++ b/spec/services/hyrax/compound_subfield_labeler_spec.rb
@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::CompoundSubfieldLabeler do
+  describe '.label_for' do
+    it 'returns the value unchanged for a non-controlled sub-field' do
+      spec = { type: 'string', authority: nil, values: nil }
+      expect(described_class.label_for(spec, 'plain text')).to eq('plain text')
+    end
+
+    it 'returns the value unchanged when spec is nil' do
+      expect(described_class.label_for(nil, 'whatever')).to eq('whatever')
+    end
+
+    it 'returns blank values unchanged' do
+      spec = { type: 'controlled', authority: 'x', values: nil }
+      expect(described_class.label_for(spec, '')).to eq('')
+    end
+
+    context 'with an inline values list' do
+      let(:spec) { { type: 'controlled', authority: nil, values: [%w[Author author], %w[Editor ed]] } }
+
+      it 'translates the stored id to its label' do
+        expect(described_class.label_for(spec, 'ed')).to eq('Editor')
+      end
+
+      it 'falls back to the id when no matching option exists' do
+        expect(described_class.label_for(spec, 'unknown')).to eq('unknown')
+      end
+    end
+
+    context 'with a QA authority' do
+      let(:spec) { { type: 'controlled', authority: 'rights_statements', values: nil } }
+      let(:service) { instance_double(Hyrax::TolerantSelectService) }
+
+      before do
+        allow(Hyrax::TolerantSelectService).to receive(:new).with('rights_statements').and_return(service)
+      end
+
+      it 'translates the stored id to the authority term' do
+        allow(service).to receive(:label).and_return('In Copyright')
+        expect(described_class.label_for(spec, 'http://rightsstatements.org/vocab/InC/1.0/')).to eq('In Copyright')
+      end
+
+      it 'falls back to the id on lookup error' do
+        allow(service).to receive(:label).and_raise(StandardError)
+        expect(described_class.label_for(spec, 'http://example.org/x')).to eq('http://example.org/x')
+      end
+    end
+  end
+end
diff --git a/spec/services/hyrax/compound_work_resolver_spec.rb b/spec/services/hyrax/compound_work_resolver_spec.rb
new file mode 100644
index 0000000000..e19deeb543
--- /dev/null
+++ b/spec/services/hyrax/compound_work_resolver_spec.rb
@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::CompoundWorkResolver do
+  describe '.url?' do
+    it 'is true for http(s) URLs' do
+      expect(described_class.url?('https://example.org/x')).to be true
+      expect(described_class.url?('http://example.org')).to be true
+    end
+
+    it 'is false for a work id (UUID/noid)' do
+      expect(described_class.url?('691b0622-3f77-48ad-a00f-00c254b83165')).to be false
+      expect(described_class.url?('abc123')).to be false
+    end
+
+    it 'is false for blank' do
+      expect(described_class.url?('')).to be false
+      expect(described_class.url?(nil)).to be false
+    end
+  end
+
+  describe '.title_and_path' do
+    let(:id) { 'work-123' }
+
+    it 'resolves the title from Solr and the model-agnostic show path' do
+      allow(Hyrax::SolrService).to receive(:query)
+        .and_return([{ 'title_tesim' => ['Resolved Title'] }])
+
+      title, path = described_class.title_and_path(id)
+      expect(title).to eq('Resolved Title')
+      expect(path).to eq('/catalog/work-123')
+    end
+
+    it 'falls back to the id when no title is indexed' do
+      allow(Hyrax::SolrService).to receive(:query).and_return([])
+      title, = described_class.title_and_path(id)
+      expect(title).to eq('work-123')
+    end
+
+    it 'falls back to the id when the Solr lookup raises' do
+      allow(Hyrax::SolrService).to receive(:query).and_raise(StandardError)
+      title, = described_class.title_and_path(id)
+      expect(title).to eq('work-123')
+    end
+  end
+end

From 9f360778ab96048c681ded34313c9366b293b279 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 15:42:08 -0400
Subject: [PATCH 05/32] Ship sample compound metadata on Hyrax
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Hyrax ships four sample compounds (agent, identifiers, compound_rights,
relationships) on works and collections, demonstrating every sub-field
type. They are declared once in the schema — compound_metadata.yaml in
non-flexible mode and the m3 profile in flexible mode — and wired onto
the base work, collection, and their SolrDocument readers.

This turns the feature on (gated by compound_metadata_enabled?, default
true). A flexible-mode validator rejects a misconfigured compound when
an m3 profile is saved.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../config/metadata_profiles/m3_profile.yaml  | 108 ++++++++++++++-
 .../concerns/hyrax/solr_document/metadata.rb  |   5 +
 app/models/hyrax/pcdm_collection.rb           |   8 ++
 app/models/hyrax/work.rb                      |   8 ++
 .../flexible_schema_validator_service.rb      |  10 ++
 .../compound_validator.rb                     |  73 ++++++++++
 config/locales/hyrax.en.yml                   |  24 ++++
 config/metadata/compound_metadata.yaml        | 108 +++++++++++++++
 config/metadata_profiles/m3_profile.yaml      | 112 ++++++++++++++-
 .../forms/compound_metadata_form_spec.rb      | 122 ++++++++++++++++
 .../hyrax/collection_presenter_spec.rb        |  59 +++++++-
 .../compound_validator_spec.rb                | 131 ++++++++++++++++++
 12 files changed, 761 insertions(+), 7 deletions(-)
 create mode 100644 app/services/hyrax/flexible_schema_validators/compound_validator.rb
 create mode 100644 config/metadata/compound_metadata.yaml
 create mode 100644 spec/forms/hyrax/forms/compound_metadata_form_spec.rb
 create mode 100644 spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb

diff --git a/.koppie/config/metadata_profiles/m3_profile.yaml b/.koppie/config/metadata_profiles/m3_profile.yaml
index 2f33e63022..db5d29193b 100644
--- a/.koppie/config/metadata_profiles/m3_profile.yaml
+++ b/.koppie/config/metadata_profiles/m3_profile.yaml
@@ -927,4 +927,110 @@ properties:
       display: true
       primary: false
     range: http://www.w3.org/2001/XMLSchema#string
-    property_uri: http://vocabulary.samvera.org/ns#transcriptIds
\ No newline at end of file
+    property_uri: http://vocabulary.samvera.org/ns#transcriptIds
+  # Sample compound (hierarchical) metadata, demonstrating the Hyrax compound
+  # foundation in flexible mode. See documentation/forms/compound_fields.md.
+  agent:
+    available_on:
+      class:
+        - GenericWork
+        - CollectionResource
+    data_type: array
+    type: hash
+    range: http://www.w3.org/2001/XMLSchema#string
+    display_label:
+      default: Agent
+    form:
+      primary: false
+    property_uri: http://id.loc.gov/vocabulary/relators/asn
+    subfields:
+      title: { type: string }
+      agent_name:
+        type: string
+        indexing: [agent_name_sim, agent_name_tesim]
+      agent_role:
+        type: controlled
+        values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
+        indexing: [agent_role_sim, agent_role_tesim]
+    groups:
+      - { label: ~, cols: 4, fields: [title, agent_name, agent_role] }
+    view:
+      render_as: compound
+      html_dl: true
+  identifiers:
+    available_on:
+      class:
+        - GenericWork
+        - CollectionResource
+    data_type: array
+    type: hash
+    range: http://www.w3.org/2001/XMLSchema#string
+    display_label:
+      default: Identifiers
+    form:
+      primary: false
+    property_uri: http://purl.org/dc/terms/identifier
+    subfields:
+      identifier:
+        type: string
+        indexing: [identifier_value_sim, identifier_value_tesim]
+      identifier_type:
+        type: controlled
+        values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
+        indexing: [identifier_type_sim]
+    view:
+      render_as: compound
+      html_dl: true
+  compound_rights:
+    available_on:
+      class:
+        - GenericWork
+        - CollectionResource
+    data_type: array
+    type: hash
+    range: http://www.w3.org/2001/XMLSchema#string
+    display_label:
+      default: Rights
+    form:
+      primary: false
+    property_uri: http://purl.org/dc/terms/rights
+    subfields:
+      rights_statement:
+        type: controlled
+        authority: rights_statements
+        indexing: [compound_rights_statement_sim, compound_rights_statement_tesim]
+      license:
+        type: controlled
+        authority: licenses
+        indexing: [compound_rights_license_sim, compound_rights_license_tesim]
+      rights_notes:
+        type: string
+        indexing: [compound_rights_notes_tesim]
+    view:
+      render_as: compound
+      html_dl: true
+  relationships:
+    available_on:
+      class:
+        - GenericWork
+        - CollectionResource
+    data_type: array
+    type: hash
+    range: http://www.w3.org/2001/XMLSchema#string
+    display_label:
+      default: Relationships
+    form:
+      primary: false
+    property_uri: http://purl.org/dc/terms/relation
+    subfields:
+      related_item:
+        type: work_or_url
+        indexing: [relationships_item_ssim]
+      relationship_type:
+        type: controlled
+        values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
+        indexing: [relationships_type_sim]
+    view:
+      render_as: compound
+      html_dl: true
+      display: card
\ No newline at end of file
diff --git a/app/models/concerns/hyrax/solr_document/metadata.rb b/app/models/concerns/hyrax/solr_document/metadata.rb
index 9e8078da79..3d9f6e8d15 100644
--- a/app/models/concerns/hyrax/solr_document/metadata.rb
+++ b/app/models/concerns/hyrax/solr_document/metadata.rb
@@ -124,6 +124,11 @@ def alt_text_for_view
         attribute :modified_date, Solr::Date, "system_modified_dtsi"
         attribute :embargo_release_date, Solr::Date, Hydra.config.permissions.embargo.release_date
         attribute :lease_expiration_date, Solr::Date, Hydra.config.permissions.lease.expiration_date
+        # Sample compound attributes shipped with Hyrax.
+        compound_attribute :agent
+        compound_attribute :identifiers
+        compound_attribute :compound_rights
+        compound_attribute :relationships
       end
     end
   end
diff --git a/app/models/hyrax/pcdm_collection.rb b/app/models/hyrax/pcdm_collection.rb
index b83fb8bfa8..52ce21ff91 100644
--- a/app/models/hyrax/pcdm_collection.rb
+++ b/app/models/hyrax/pcdm_collection.rb
@@ -45,6 +45,14 @@ class PcdmCollection < Hyrax::Resource
     include Hyrax::Schema(:redirects) if Hyrax.config.collection_include_metadata? && Hyrax.config.redirects_enabled?
     include Hyrax::RedirectsNormalization if Hyrax.config.redirects_enabled?
 
+    # Sample compound metadata, mirroring Hyrax::Work. In flexible mode the
+    # compounds come from the m3 profile, so only the read-path normalization is
+    # included here. See documentation/forms/compound_fields.md.
+    if Hyrax.config.compound_metadata_enabled?
+      include Hyrax::Schema(:compound_metadata) unless Hyrax.config.flexible?
+      include Hyrax::CompoundNormalization
+    end
+
     attribute :collection_type_gid, Valkyrie::Types::String
     attribute :member_ids, Valkyrie::Types::Array.of(Valkyrie::Types::ID).meta(ordered: true)
     attribute :member_of_collection_ids, Valkyrie::Types::Set.of(Valkyrie::Types::ID)
diff --git a/app/models/hyrax/work.rb b/app/models/hyrax/work.rb
index bd833ed10a..d300fcd722 100644
--- a/app/models/hyrax/work.rb
+++ b/app/models/hyrax/work.rb
@@ -99,6 +99,14 @@ class Work < Hyrax::Resource
     include Hyrax::Schema(:redirects) if Hyrax.config.work_default_metadata && Hyrax.config.redirects_enabled?
     include Hyrax::RedirectsNormalization if Hyrax.config.redirects_enabled?
 
+    # Sample compound metadata. In flexible mode the compounds come from the m3
+    # profile, so only the read-path normalization is included here. See
+    # documentation/forms/compound_fields.md.
+    if Hyrax.config.compound_metadata_enabled?
+      include Hyrax::Schema(:compound_metadata) unless Hyrax.config.flexible?
+      include Hyrax::CompoundNormalization
+    end
+
     attribute :admin_set_id,             Valkyrie::Types::ID
     attribute :member_ids,               Valkyrie::Types::Array.of(Valkyrie::Types::ID).meta(ordered: true)
     attribute :member_of_collection_ids, Valkyrie::Types::Set.of(Valkyrie::Types::ID)
diff --git a/app/services/hyrax/flexible_schema_validator_service.rb b/app/services/hyrax/flexible_schema_validator_service.rb
index 205c6818ff..45db289b9c 100644
--- a/app/services/hyrax/flexible_schema_validator_service.rb
+++ b/app/services/hyrax/flexible_schema_validator_service.rb
@@ -39,6 +39,7 @@ def validate!
       validate_core_metadata
       validate_sort_properties
       validate_redirects
+      validate_compound
     end
 
     # The default JSON schema used when no custom schema is provided.
@@ -132,6 +133,15 @@ def validate_redirects
       ).validate!
     end
 
+    # Validates compound (hierarchical) metadata properties — those declaring
+    # `subfields:` — for well-formed sub-fields and correct (per-sub-field)
+    # indexing declaration.
+    #
+    # @return [void]
+    def validate_compound
+      FlexibleSchemaValidators::CompoundValidator.new(profile: profile, errors: @errors).validate!
+    end
+
     # Validates that a `label` property exists and that it is available on
     # `Hyrax.config.file_set_model`.
     #
diff --git a/app/services/hyrax/flexible_schema_validators/compound_validator.rb b/app/services/hyrax/flexible_schema_validators/compound_validator.rb
new file mode 100644
index 0000000000..e2bda68a32
--- /dev/null
+++ b/app/services/hyrax/flexible_schema_validators/compound_validator.rb
@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Hyrax
+  module FlexibleSchemaValidators
+    ##
+    # @api private
+    #
+    # Validates compound metadata properties (a `type: hash` property declaring
+    # `subfields:` — see {Hyrax::CompoundSchema}) in an m3 profile at save time,
+    # so a misconfiguration fails with a clear message instead of producing dead
+    # Solr fields or unrenderable values. See
+    # documentation/forms/compound_fields.md for the rules.
+    class CompoundValidator
+      ##
+      # @param profile [Hash] the flexible metadata profile
+      # @param errors [Array<String>] an array to append errors to
+      def initialize(profile:, errors:)
+        @profile = profile
+        @errors = errors
+      end
+
+      # @return [void]
+      def validate!
+        compound_properties.each do |name, config|
+          validate_subfields(name, config['subfields'])
+          validate_no_top_level_indexing(name, config)
+        end
+      end
+
+      private
+
+      # Compounds are detected by `subfields:` presence (not `type`), so other
+      # hash fields like redirects stay out of scope.
+      def compound_properties
+        (@profile&.dig('properties') || {}).select do |_name, config|
+          config.is_a?(Hash) && config['subfields'].present?
+        end
+      end
+
+      def validate_subfields(name, subfields)
+        unless subfields.is_a?(Hash)
+          @errors << t('subfields_not_hash', property: name)
+          return
+        end
+
+        subfields.each { |sub_name, sub_config| validate_subfield(name, sub_name, sub_config) }
+      end
+
+      def validate_subfield(name, sub_name, sub_config)
+        unless sub_config.is_a?(Hash)
+          @errors << t('subfield_not_hash', property: name, subfield: sub_name, actual: sub_config.class.to_s)
+          return
+        end
+
+        return unless sub_config['type'].to_s == 'controlled'
+        return if sub_config['authority'].present? || sub_config['values'].present?
+
+        @errors << t('controlled_without_source', property: name, subfield: sub_name)
+      end
+
+      # A top-level `indexing:` would point the catalog at a `<compound>_tesim`
+      # field the indexer never writes; indexing is per sub-field.
+      def validate_no_top_level_indexing(name, config)
+        return if config['indexing'].blank?
+        @errors << t('top_level_indexing', property: name)
+      end
+
+      def t(key, **opts)
+        I18n.t("hyrax.flexible_schema_validators.compound_validator.errors.#{key}", **opts)
+      end
+    end
+  end
+end
diff --git a/config/locales/hyrax.en.yml b/config/locales/hyrax.en.yml
index dc4eb004c2..442ee89515 100644
--- a/config/locales/hyrax.en.yml
+++ b/config/locales/hyrax.en.yml
@@ -862,6 +862,24 @@ en:
       add_row: Add %{label}
       remove_row: Remove
       remove_row_with_label: Remove %{label}
+      agent:
+        label: Agents
+        title: Title
+        agent_name: Name
+        agent_role: Role
+      identifiers:
+        label: Identifiers
+        identifier: Identifier
+        identifier_type: Type
+      compound_rights:
+        label: Rights
+        rights_statement: Rights statement
+        license: License
+        rights_notes: Notes
+      relationships:
+        label: Relationships
+        related_item: Related item
+        relationship_type: Relationship type
     contact_form:
       button_label: Send
       email_label: Your Email
@@ -1394,6 +1412,12 @@ en:
         save_your_note: You must click "Save Revision" to revert a previous version of this file
         upload: Upload New Version
     flexible_schema_validators:
+      compound_validator:
+        errors:
+          subfields_not_hash: "m3 profile compound property `%{property}` must declare `subfields` as a mapping of sub-field name to its configuration"
+          subfield_not_hash: "m3 profile compound property `%{property}` sub-field `%{subfield}` must be a mapping (got `%{actual}`)"
+          controlled_without_source: "m3 profile compound property `%{property}` sub-field `%{subfield}` is `type: controlled` but declares neither `authority` nor `values`"
+          top_level_indexing: "m3 profile compound property `%{property}` must not declare top-level `indexing`; declare `indexing` (or `index_keys`) on each sub-field instead"
       redirects_validator:
         errors:
           invalid_available_on: "m3 profile `redirects` property must be available on at least one work or collection class declared in this profile"
diff --git a/config/metadata/compound_metadata.yaml b/config/metadata/compound_metadata.yaml
new file mode 100644
index 0000000000..4c5e3977d2
--- /dev/null
+++ b/config/metadata/compound_metadata.yaml
@@ -0,0 +1,108 @@
+# Sample compound (hierarchical) metadata that ships with Hyrax.
+#
+# Each attribute here is a compound: a `type: hash, multiple: true` field whose
+# entries are plain hashes of named sub-fields. The sub-fields are declared in
+# `subfields:` and rendered, populated, and indexed generically by the compound
+# foundation — no per-field Ruby or ERB. See
+# `documentation/forms/compound_fields.md`.
+#
+# These are intentionally generic examples demonstrating the supported
+# sub-field input types (open-entry `string` and `controlled` vocabulary).
+# Applications can add their own compounds the same way (in this file, an
+# app-level schema, or the m3 profile under HYRAX_FLEXIBLE=true) and may remove
+# these samples by setting `Hyrax.config.compound_metadata_enabled = false`.
+attributes:
+  # An agent associated with the work: a person or organization with a display
+  # title, a name, and a controlled role.
+  agent:
+    type: hash
+    multiple: true
+    predicate: http://id.loc.gov/vocabulary/relators/asn
+    form:
+      primary: false
+    subfields:
+      # Indexing is declared per sub-field via `index_keys:` (the literal Solr
+      # field names + suffixes), exactly like scalar fields. A sub-field with
+      # no `index_keys:` is display-only (rendered from the json blob, not its
+      # own searchable field). `display: false` would omit it from the blob.
+      title: { type: string }
+      agent_name:
+        type: string
+        index_keys: [agent_name_sim, agent_name_tesim]
+      # A controlled sub-field can take its options from an inline list (below)
+      # or from an existing QA local authority (`authority: <name>`).
+      agent_role:
+        type: controlled
+        values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
+        index_keys: [agent_role_sim, agent_role_tesim]
+    groups:
+      - { label: ~, cols: 4, fields: [title, agent_name, agent_role] }
+    view:
+      render_as: compound
+      html_dl: true
+  # A typed identifier: an open-entry value plus a controlled identifier type.
+  # Named `identifiers` (plural) to avoid colliding with the scalar
+  # `identifier` defined in basic_metadata / the default m3 profile.
+  identifiers:
+    type: hash
+    multiple: true
+    predicate: http://purl.org/dc/terms/identifier
+    form:
+      primary: false
+    subfields:
+      identifier:
+        type: string
+        index_keys: [identifier_value_sim, identifier_value_tesim]
+      identifier_type:
+        type: controlled
+        values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
+        index_keys: [identifier_type_sim]
+    view:
+      render_as: compound
+      html_dl: true
+  # A rights grouping demonstrating controlled sub-fields backed by *existing*
+  # QA local authorities (rather than inline `values:`), alongside an
+  # open-ended note.
+  compound_rights:
+    type: hash
+    multiple: true
+    predicate: http://purl.org/dc/terms/rights
+    form:
+      primary: false
+    subfields:
+      rights_statement:
+        type: controlled
+        authority: rights_statements
+        index_keys: [compound_rights_statement_sim, compound_rights_statement_tesim]
+      license:
+        type: controlled
+        authority: licenses
+        index_keys: [compound_rights_license_sim, compound_rights_license_tesim]
+      rights_notes:
+        type: string
+        index_keys: [compound_rights_notes_tesim]
+    view:
+      render_as: compound
+      html_dl: true
+  # A related-item grouping demonstrating the `work_or_url` sub-field: the user
+  # searches for an internal work (typeahead) OR types an external URL. The
+  # stored value is a work id or a URL; show pages link to the internal work
+  # (by title) or auto-link the external URL.
+  relationships:
+    type: hash
+    multiple: true
+    predicate: http://purl.org/dc/terms/relation
+    form:
+      primary: false
+    subfields:
+      related_item:
+        type: work_or_url
+        index_keys: [relationships_item_ssim]
+      relationship_type:
+        type: controlled
+        values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
+        index_keys: [relationships_type_sim]
+    view:
+      render_as: compound
+      html_dl: true
+      display: card
diff --git a/config/metadata_profiles/m3_profile.yaml b/config/metadata_profiles/m3_profile.yaml
index ccfe3c0ac5..031e271739 100644
--- a/config/metadata_profiles/m3_profile.yaml
+++ b/config/metadata_profiles/m3_profile.yaml
@@ -951,4 +951,114 @@ properties:
       display: true
       primary: false
     range: http://www.w3.org/2001/XMLSchema#string
-    property_uri: http://vocabulary.samvera.org/ns#transcriptIds
\ No newline at end of file
+    property_uri: http://vocabulary.samvera.org/ns#transcriptIds
+  # Sample compound (hierarchical) metadata shipped with Hyrax. Each is a
+  # `type: hash, multiple: true` property whose entries are hashes of the
+  # `subfields:` keys, rendered/populated/indexed generically by the compound
+  # foundation. See documentation/forms/compound_fields.md.
+  agent:
+    available_on:
+      class:
+        - Hyrax::Work
+        - CollectionResource
+    data_type: array
+    type: hash
+    range: http://www.w3.org/2001/XMLSchema#string
+    display_label:
+      default: Agent
+    form:
+      primary: false
+    property_uri: http://id.loc.gov/vocabulary/relators/asn
+    subfields:
+      # Indexing per sub-field via `indexing:` (literal Solr field names), the
+      # same mechanism scalar properties use. No `indexing:` => display-only.
+      title: { type: string }
+      agent_name:
+        type: string
+        indexing: [agent_name_sim, agent_name_tesim]
+      agent_role:
+        type: controlled
+        values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
+        indexing: [agent_role_sim, agent_role_tesim]
+    groups:
+      - { label: ~, cols: 4, fields: [title, agent_name, agent_role] }
+    view:
+      render_as: compound
+      html_dl: true
+  identifiers:
+    available_on:
+      class:
+        - Hyrax::Work
+        - CollectionResource
+    data_type: array
+    type: hash
+    range: http://www.w3.org/2001/XMLSchema#string
+    display_label:
+      default: Identifiers
+    form:
+      primary: false
+    property_uri: http://purl.org/dc/terms/identifier
+    subfields:
+      identifier:
+        type: string
+        indexing: [identifier_value_sim, identifier_value_tesim]
+      identifier_type:
+        type: controlled
+        values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
+        indexing: [identifier_type_sim]
+    view:
+      render_as: compound
+      html_dl: true
+  compound_rights:
+    available_on:
+      class:
+        - Hyrax::Work
+        - CollectionResource
+    data_type: array
+    type: hash
+    range: http://www.w3.org/2001/XMLSchema#string
+    display_label:
+      default: Rights
+    form:
+      primary: false
+    property_uri: http://purl.org/dc/terms/rights
+    subfields:
+      rights_statement:
+        type: controlled
+        authority: rights_statements
+        indexing: [compound_rights_statement_sim, compound_rights_statement_tesim]
+      license:
+        type: controlled
+        authority: licenses
+        indexing: [compound_rights_license_sim, compound_rights_license_tesim]
+      rights_notes:
+        type: string
+        indexing: [compound_rights_notes_tesim]
+    view:
+      render_as: compound
+      html_dl: true
+  relationships:
+    available_on:
+      class:
+        - Hyrax::Work
+        - CollectionResource
+    data_type: array
+    type: hash
+    range: http://www.w3.org/2001/XMLSchema#string
+    display_label:
+      default: Relationships
+    form:
+      primary: false
+    property_uri: http://purl.org/dc/terms/relation
+    subfields:
+      related_item:
+        type: work_or_url
+        indexing: [relationships_item_ssim]
+      relationship_type:
+        type: controlled
+        values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
+        indexing: [relationships_type_sim]
+    view:
+      render_as: compound
+      html_dl: true
+      display: card
\ No newline at end of file
diff --git a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
new file mode 100644
index 0000000000..2116199594
--- /dev/null
+++ b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Integration spec for the compound-metadata form flow through the real
+# Hyrax::Forms::ResourceForm pipeline (factory build -> validate -> sync).
+#
+# These assertions exercise the wiring that unit specs for the populator and
+# helper can't see:
+#   * the `<compound>` reader is registered (so the form partial can render),
+#   * the virtual `<compound>_attributes` populator is registered *in Reform's
+#     schema* (so `validate` invokes it — registering it too late silently
+#     drops the value), and
+#   * `validate` + `sync` actually writes the compound onto the model.
+#
+# It mirrors the existing redirects coverage in resource_form_spec.rb, which
+# documents the same "Reform drops the assigned value during sync without a
+# class-level FormFields include" failure mode.
+#
+# This is a non-flexible-mode integration spec: it includes the compound schema
+# on the model class via `Hyrax::Schema(:compound_metadata)` (the
+# `HYRAX_FLEXIBLE=false` registration path) and stubs `flexible? => false`. When
+# the host app boots in flexible mode (allinson), the model class composition is
+# fixed at load time and the stub can't retroactively attach the schema, so this
+# path can only be exercised under a non-flexible stack (dassie/koppie). The flex
+# path is covered by the singleton-schema registration in
+# compound_field_behavior_spec and the live allinson UI.
+RSpec.describe 'Compound metadata form flow', type: :model, unless: Hyrax.config.flexible? do
+  before do
+    allow(Hyrax.config).to receive(:compound_metadata_enabled?).and_return(true)
+    allow(Hyrax.config).to receive(:flexible?).and_return(false)
+    # A work-like resource that includes the shipped compound schema, the way
+    # Hyrax::Work does. Named so the form factory's `*Form` lookup falls back
+    # to the generic ResourceForm.
+    stub_const('CompoundTestWork', Class.new(Hyrax::Work) do
+      include Hyrax::Schema(:compound_metadata)
+      include Hyrax::CompoundNormalization
+    end)
+  end
+
+  let(:resource) { CompoundTestWork.new }
+  let(:form) { Hyrax::Forms::ResourceForm.for(resource: resource) }
+
+  describe 'property registration' do
+    it 'exposes the compound readers so the form partial can render existing rows' do
+      expect(form).to respond_to(:agent)
+      expect(form).to respond_to(:identifiers)
+    end
+
+    it 'exposes the virtual `<compound>_attributes` setters for nested form params' do
+      expect(form).to respond_to(:agent_attributes=)
+      expect(form).to respond_to(:identifiers_attributes=)
+    end
+
+    it 'lists the compounds as compound_terms (and keeps them out of primary/secondary terms)' do
+      expect(form.compound_terms).to include(:agent, :identifiers, :compound_rights)
+      expect(form.primary_terms).not_to include(:agent, :identifiers, :compound_rights)
+      expect(form.secondary_terms).not_to include(:agent, :identifiers, :compound_rights)
+    end
+
+    it 'registers `agent_attributes` as a real Reform property (not just method-missing)' do
+      # This is the property that has to exist in Reform's schema *before*
+      # validate runs; if it is registered too late the populator never fires.
+      # In non-flexible mode it is registered on the form class via FormFields;
+      # check the class definitions registry (the same lens the redirects
+      # coverage uses).
+      definition_keys = form.class.definitions.keys.map(&:to_s)
+      expect(definition_keys).to include('agent_attributes')
+    end
+  end
+
+  describe 'validate + sync writes the compound to the model' do
+    let(:params) do
+      { 'agent_attributes' =>
+          { '0' => { 'title' => 'Dr', 'agent_name' => 'Ada Lovelace', 'agent_role' => 'Author' } },
+        'identifiers_attributes' =>
+          { '0' => { 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' } } }
+    end
+
+    it 'populates the compound on the form during validate' do
+      form.validate(params)
+      expect(form.agent)
+        .to eq([{ 'title' => 'Dr', 'agent_name' => 'Ada Lovelace', 'agent_role' => 'Author' }])
+      expect(form.identifiers)
+        .to eq([{ 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' }])
+    end
+
+    it 'writes the compound through to the model on sync' do
+      form.validate(params)
+      form.sync
+      expect(form.model.agent)
+        .to eq([{ 'title' => 'Dr', 'agent_name' => 'Ada Lovelace', 'agent_role' => 'Author' }])
+      expect(form.model.identifiers)
+        .to eq([{ 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' }])
+    end
+
+    it 'drops `_destroy` and all-blank rows' do
+      form.validate('agent_attributes' =>
+        { '0' => { 'agent_name' => 'Keep', 'agent_role' => 'Author' },
+          '1' => { 'agent_name' => 'Remove', '_destroy' => 'true' },
+          '2' => { 'title' => '', 'agent_name' => '', 'agent_role' => '' } })
+      form.sync
+      expect(form.model.agent).to eq([{ 'title' => nil, 'agent_name' => 'Keep', 'agent_role' => 'Author' }])
+    end
+  end
+
+  describe 'persistence round-trip', :active_fedora do
+    # Skips on the Fedora adapter, which cannot serialize plain-hash compounds
+    # to RDF; the compound feature targets the Valkyrie/Postgres path.
+    it 'round-trips the compound through the persister' do
+      skip 'requires a Valkyrie (non-Fedora) persister' if
+        Hyrax.persister.is_a?(Wings::Valkyrie::Persister)
+
+      form.validate('agent_attributes' =>
+        { '0' => { 'agent_name' => 'Grace Hopper', 'agent_role' => 'Editor' } })
+      form.sync
+      saved = Hyrax.persister.save(resource: form.model)
+      reloaded = Hyrax.query_service.find_by(id: saved.id)
+
+      expect(reloaded.agent.first['agent_name'] || reloaded.agent.first[:agent_name])
+        .to eq('Grace Hopper')
+    end
+  end
+end
diff --git a/spec/presenters/hyrax/collection_presenter_spec.rb b/spec/presenters/hyrax/collection_presenter_spec.rb
index 9e71ce9588..9c69cf31c1 100644
--- a/spec/presenters/hyrax/collection_presenter_spec.rb
+++ b/spec/presenters/hyrax/collection_presenter_spec.rb
@@ -20,11 +20,60 @@
   describe ".terms" do
     subject { described_class.terms }
 
-    it do
-      is_expected.to eq [:total_items, :alternative_title, :size, :resource_type, :creator,
-                         :contributor, :keyword, :license, :publisher,
-                         :date_created, :subject, :language, :identifier,
-                         :based_near, :related_url]
+    context 'with compound metadata disabled' do
+      before { allow(Hyrax.config).to receive(:compound_metadata_enabled?).and_return(false) }
+
+      it do
+        is_expected.to eq [:total_items, :alternative_title, :size, :resource_type, :creator,
+                           :contributor, :keyword, :license, :publisher,
+                           :date_created, :subject, :language, :identifier,
+                           :based_near, :related_url]
+      end
+    end
+
+    it 'starts with the base scalar terms' do
+      expect(subject.first(15)).to eq [:total_items, :alternative_title, :size, :resource_type, :creator,
+                                       :contributor, :keyword, :license, :publisher,
+                                       :date_created, :subject, :language, :identifier,
+                                       :based_near, :related_url]
+    end
+
+    it 'appends compound terms declared on the collection model when enabled' do
+      compound_terms = described_class.compound_terms
+      # Under a flexible-mode stack the collection class composition is fixed at
+      # boot, so the shipped compounds are only present when the active flex
+      # schema declares them; guard rather than assert an empty splat.
+      skip 'no compound terms declared on the collection class in this configuration' if compound_terms.empty?
+      expect(subject).to include(*compound_terms)
+    end
+  end
+
+  describe "compound attribute delegation" do
+    context "when a compound is declared on the collection model" do
+      before do
+        allow(described_class).to receive(:all_compound_names).and_return([:relationships])
+        allow(solr_doc).to receive(:relationships).and_return([{ 'related_item' => 'https://example.org' }])
+      end
+
+      it "responds to the declared compound reader" do
+        expect(presenter).to respond_to(:relationships)
+      end
+
+      it "delegates the compound reader to the solr document" do
+        expect(presenter.relationships).to eq([{ 'related_item' => 'https://example.org' }])
+      end
+    end
+
+    context "for an undeclared method" do
+      before { allow(described_class).to receive(:all_compound_names).and_return([]) }
+
+      it "does not respond to it" do
+        expect(presenter).not_to respond_to(:not_a_compound)
+      end
+
+      it "raises NoMethodError" do
+        expect { presenter.not_a_compound }.to raise_error(NoMethodError)
+      end
     end
   end
 
diff --git a/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb b/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb
new file mode 100644
index 0000000000..fa7d5134d5
--- /dev/null
+++ b/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb
@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::FlexibleSchemaValidators::CompoundValidator do
+  subject(:validator) { described_class.new(profile: profile, errors: errors) }
+  let(:errors) { [] }
+
+  def t(key, **opts)
+    I18n.t("hyrax.flexible_schema_validators.compound_validator.errors.#{key}", **opts)
+  end
+
+  describe '#validate!' do
+    context 'with a well-formed compound property' do
+      let(:profile) do
+        {
+          'properties' => {
+            'agent' => {
+              'type' => 'hash',
+              'subfields' => {
+                'title' => { 'type' => 'string' },
+                'agent_name' => { 'type' => 'string', 'indexing' => %w[agent_name_tesim] },
+                'agent_role' => { 'type' => 'controlled', 'values' => %w[Author Editor], 'indexing' => %w[agent_role_sim] }
+              }
+            }
+          }
+        }
+      end
+
+      it 'records no errors' do
+        validator.validate!
+        expect(errors).to be_empty
+      end
+    end
+
+    context 'with a controlled sub-field that uses an authority instead of inline values' do
+      let(:profile) do
+        {
+          'properties' => {
+            'agent' => {
+              'type' => 'hash',
+              'subfields' => { 'role' => { 'type' => 'controlled', 'authority' => 'agent_role' } }
+            }
+          }
+        }
+      end
+
+      it 'is valid (authority satisfies the option-source requirement)' do
+        validator.validate!
+        expect(errors).to be_empty
+      end
+    end
+
+    context 'with a controlled sub-field that declares neither authority nor values' do
+      let(:profile) do
+        {
+          'properties' => {
+            'agent' => {
+              'type' => 'hash',
+              'subfields' => { 'role' => { 'type' => 'controlled' } }
+            }
+          }
+        }
+      end
+
+      it 'records an error' do
+        validator.validate!
+        expect(errors).to include(t('controlled_without_source', property: 'agent', subfield: 'role'))
+      end
+    end
+
+    context 'with a top-level indexing declaration on the compound' do
+      let(:profile) do
+        {
+          'properties' => {
+            'agent' => {
+              'type' => 'hash',
+              'indexing' => %w[agent_tesim],
+              'subfields' => { 'agent_name' => { 'type' => 'string' } }
+            }
+          }
+        }
+      end
+
+      it 'records an error that indexing belongs on sub-fields' do
+        validator.validate!
+        expect(errors).to include(t('top_level_indexing', property: 'agent'))
+      end
+    end
+
+    context 'when subfields is not a mapping' do
+      let(:profile) do
+        { 'properties' => { 'agent' => { 'type' => 'hash', 'subfields' => %w[a b] } } }
+      end
+
+      it 'records an error' do
+        validator.validate!
+        expect(errors).to include(t('subfields_not_hash', property: 'agent'))
+      end
+    end
+
+    context 'when a sub-field config is not a mapping' do
+      let(:profile) do
+        { 'properties' => { 'agent' => { 'type' => 'hash', 'subfields' => { 'name' => 'string' } } } }
+      end
+
+      it 'records an error' do
+        validator.validate!
+        expect(errors).to include(t('subfield_not_hash', property: 'agent', subfield: 'name', actual: 'String'))
+      end
+    end
+
+    context 'with a hash property that is not a compound (no subfields, e.g. redirects)' do
+      let(:profile) do
+        { 'properties' => { 'redirects' => { 'type' => 'hash' } } }
+      end
+
+      it 'ignores it (not a compound)' do
+        validator.validate!
+        expect(errors).to be_empty
+      end
+    end
+
+    context 'with no compound properties at all' do
+      let(:profile) { { 'properties' => { 'title' => { 'type' => 'string' } } } }
+
+      it 'is silent' do
+        validator.validate!
+        expect(errors).to be_empty
+      end
+    end
+  end
+end

From dbc22f2e87792e33965b640096742f8b2629a61a Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 15:43:17 -0400
Subject: [PATCH 06/32] Document compound metadata fields
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a reference for declaring compound (hierarchical) metadata in
schema YAML — sub-field types, indexing, inline vs. card display, the
work-or-url picker, profile validation, and Bulkrax round-tripping —
and points the field-behaviors guide at it as the preferred path for
new multi-sub-field compounds.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 documentation/forms/compound_fields.md | 308 +++++++++++++++++++++++++
 documentation/forms/field_behaviors.md |  11 +
 2 files changed, 319 insertions(+)
 create mode 100644 documentation/forms/compound_fields.md

diff --git a/documentation/forms/compound_fields.md b/documentation/forms/compound_fields.md
new file mode 100644
index 0000000000..aa0a2827c2
--- /dev/null
+++ b/documentation/forms/compound_fields.md
@@ -0,0 +1,308 @@
+# Compound (hierarchical) metadata fields
+
+A **compound field** is a metadata attribute whose value is a list of entries,
+where each entry is itself a small set of named **sub-fields**. It is the
+Hyrax foundation for hierarchical metadata: contributors with a name, role and
+identifier; dates with a value and type; funding references with a funder name
+and award number; and so on.
+
+A compound is declared entirely in the schema (a `config/metadata/*.yaml`
+schema under `HYRAX_FLEXIBLE=false`, or the m3 profile under
+`HYRAX_FLEXIBLE=true`). No per-compound Ruby or ERB is required: the generic
+form input, populator, and indexer all read the declaration from the schema
+and behave identically in both flex modes.
+
+## Declaring a compound
+
+A compound is a `type: hash, multiple: true` attribute that also carries a
+`subfields:` map:
+
+```yaml
+contributors:
+  type: hash
+  multiple: true
+  predicate: https://prvoices.org/terms/contributor
+  subfields:
+    given_name:
+      type: string
+      index_keys: [contributors_given_name_sim, contributors_given_name_tesim]
+    family_name:
+      type: string
+      index_keys: [contributors_family_name_sim, contributors_family_name_tesim]
+    name_type:       { type: controlled, authority: name_type }
+    role_label:      { type: controlled, authority: contributor_role }
+    name_identifier:
+      type: string
+      index_keys: [contributors_name_identifier_ssim]
+    affiliation:     { type: string }   # display-only (no index_keys)
+  groups:
+    - { label: Identity, cols: 4, fields: [given_name, family_name, name_type] }
+    - { label: Role,     cols: 4, fields: [role_label, name_identifier, affiliation] }
+```
+
+In the m3 profile the same declaration uses `data_type: array`, `type: hash`,
+and `available_on: class:` to scope the property, with the identical
+`subfields:` / `groups:` keys; sub-field index targets are declared with
+`indexing:` (the flexible-mode spelling of `index_keys:`).
+
+> **Flexible mode:** the active schema is the `Hyrax::FlexibleSchema` row in the
+> database, seeded from the m3 profile — not the YAML file directly. After
+> editing the m3 profile, reseed the flexible schema (`Hyrax::FlexibleSchema`
+> import) and restart the web process so the running app picks up both the new
+> schema and any Ruby changes. The schema is applied to each resource's
+> singleton class at load time, so a stale running process serves the old
+> attribute set even when the profile YAML is current.
+
+### `subfields:`
+
+An ordered map of `sub_field_key => { type:, ... }`. Supported `type:` values:
+
+| `type:`      | Renders as          | Notes |
+|--------------|---------------------|-------|
+| `string`     | text input          | The default when `type:` is omitted. |
+| `url`        | url input → auto-linked on show | The stored value is rendered as a clickable `<a href>` on show pages (matching the scalar `render_as: external_link` behavior). |
+| `work_or_url` | select2 typeahead → linked on show | Searches internal works (via the `compound_works` QA authority, backed by `Hyrax::CompoundWorkPickerBuilder`) **or** accepts a typed external URL. The stored value is a work id or a URL; on show, a work id links to the work's show page with its title (resolved by `Hyrax::CompoundWorkResolver`), a URL is auto-linked. |
+| `controlled` | `<select>` dropdown | Options come from either an inline `values:` list or a QA local authority named by `authority:` (see below). The row's stored value is preserved even if it is no longer offered, matching the `include_current_value` convention of the ordinary controlled-field partials. |
+
+A `controlled` sub-field sources its options one of two ways:
+
+```yaml
+subfields:
+  # (a) inline list — no authority file needed
+  agent_role:
+    type: controlled
+    values: [Author, Editor, Contributor]
+  # (a') inline list with distinct id and label
+  status:
+    type: controlled
+    values:
+      - { id: pub, label: Published }
+      - { id: dft, label: Draft }
+  # (b) an existing QA local authority (config/authorities/<name>.yml)
+  identifier_type:
+    type: controlled
+    authority: identifier_type
+```
+
+Inline `values:` is convenient for small, stable lists and keeps the whole
+declaration in one file. `authority:` reuses an existing QA local authority —
+the same `config/authorities/*.yml` files ordinary controlled fields use. When
+both are given, `values:` wins. Authority options are read through
+`Hyrax::TolerantSelectService`, so an authority file that omits the `active:`
+key behaves the same as it does for ordinary fields (terms default to active).
+
+A `work_or_url` sub-field's work search is broader than the stock "my works"
+picker: `Hyrax::CompoundWorkPickerBuilder` matches a typed term against any
+indexed query field **or** a partial/prefix title (so "jour" matches "Journal
+of …"), restricted to works. It subclasses `Hyrax::SearchBuilder`, so the
+catalog's read-permission filtering is retained — a user only sees works they
+can read. The picker is mounted as the `compound_works` QA authority at
+`/authorities/search/compound_works`.
+
+`db_table` (a typeahead backed by an ActiveRecord lookup table, with
+add-new) and `geocode` (a Geonames/coordinate lookup, like `based_near`) are
+planned additional sub-field types; the form's row partial has an explicit
+extension point for them.
+
+### `groups:` (optional)
+
+Visual clustering of sub-fields within each entry's card. Each group is
+`{ label:, cols:, fields: [...] }`, where `cols` is the Bootstrap column width
+(out of 12) for each field in the group. When omitted, all sub-fields render in
+a single unlabeled group.
+
+### Indexing sub-fields (`index_keys:` / `indexing:`)
+
+Indexing is declared **per sub-field**, exactly as for scalar fields: list the
+literal Solr field names the sub-field's value should be written to, under
+`index_keys:` (non-flexible mode) or `indexing:` (flexible mode). The Solr
+suffix on each name chooses the behavior — `_tesim` (stored + searchable,
+multi-valued), `_sim` (facetable, not stored), `_ssim` (stored + facetable),
+etc. — the same conventions scalar fields use. The author picks both the field
+names and the suffixes.
+
+A sub-field with no `index_keys:`/`indexing:` is **not** written to a Solr field
+of its own; it can still appear on the show page (see below). As with scalar
+fields, the non-field control tokens (`facetable`, `stored_searchable`,
+`admin_only`, `editor_only`) are filtered out if present.
+
+Indexing a sub-field makes it **searchable/facetable** in Solr; it does **not**
+make it appear as a column on the catalog/search-results page. The catalog
+renders only the fields explicitly registered with Blacklight
+(`config.add_index_field`) — compound sub-fields are not registered by default.
+To show a sub-field in search results, register its Solr field name in your
+`CatalogController` (e.g.
+`config.add_index_field 'agent_name_tesim', label: 'Agent'`). The show page and
+edit form render compounds regardless.
+
+### `display:` (optional, default true)
+
+Controls whether a sub-field is included in the `<compound>_json_ss` blob that
+the show page renders from. Combined with indexing, each sub-field can be:
+
+- **display + searchable** — has `index_keys:` and `display` not false
+- **display-only** — no `index_keys:` (renders on show, not separately searchable)
+- **searchable-only** — has `index_keys:` and `display: false` (indexed, hidden on show)
+- **neither** — no `index_keys:` and `display: false`
+
+## Persisted shape
+
+A compound persists as an array of plain string-keyed hashes — exactly the
+keys declared in `subfields:`:
+
+```ruby
+work.contributors
+# => [{ "given_name" => "Ada", "family_name" => "Lovelace", "role_label" => "author" },
+#     { "given_name" => "Alan", "family_name" => "Turing",  "role_label" => "author" }]
+```
+
+This shape round-trips cleanly through Postgres JSONB in both flex modes. (Use
+this plain-hash shape rather than nesting a `Valkyrie::Resource`; nested
+resources round-trip poorly and lack form-layer support — see
+[`field_behaviors.md`](field_behaviors.md).)
+
+## What the foundation provides
+
+Adding a compound to the schema is enough to get all of the following, with no
+per-compound code:
+
+- **Form rendering** — `Hyrax::Forms::ResourceForm#compound_terms` lists the
+  compounds, and the work form renders each via the
+  `hyrax/compounds/_compound_section` partials (a repeatable card stack with
+  add/remove-row controls). The add/remove client behavior is the engine asset
+  `app/assets/javascripts/hyrax/compound_metadata.js` (required via
+  `hyrax.js`). Compounds are excluded from `primary_terms` / `secondary_terms`
+  so they are not also rendered as scalar inputs.
+- **Form → storage conversion** — `Hyrax::CompoundFieldBehavior` registers a
+  virtual `<name>_attributes` property per compound and a shared populator that
+  builds the persisted array, dropping `_destroy` and all-blank rows and
+  keeping only declared sub-field keys.
+- **Read-path defense** — `Hyrax::CompoundNormalization`, included on the
+  resource, guards against Valkyrie's single-element-array key-splay quirk on
+  reload.
+- **Indexing** — `Hyrax::Indexers::CompoundIndexer`, included on the indexer,
+  writes each sub-field's value to the Solr field names it declares
+  (`index_keys:`/`indexing:`) and stores the displayable sub-fields as a
+  `<compound>_json_ss` blob for the show page.
+
+A resource and its indexer opt in with one include each:
+
+```ruby
+class GenericWorkResource < Hyrax::Work
+  include Hyrax::Schema(:generic_work_resource)
+  include Hyrax::CompoundNormalization
+end
+
+class GenericWorkResourceIndexer < Hyrax::ValkyrieWorkIndexer
+  include Hyrax::Indexer(:generic_work_resource)
+  include Hyrax::Indexers::CompoundIndexer
+end
+```
+
+## Sample compounds shipped with Hyrax
+
+Hyrax ships sample compounds on **works and collections** by default,
+demonstrating the supported sub-field types:
+
+- **`agent`** — `title`, `agent_name`, and a controlled `agent_role` (inline
+  `values:`). A person or organization associated with the work or collection.
+- **`identifiers`** — an open-entry `identifier` plus a controlled
+  `identifier_type` (inline `values:`).
+- **`compound_rights`** — controlled `rights_statement` and `license` backed by
+  *existing* QA local authorities (`authority:`), plus an open `rights_notes`.
+- **`relationships`** — a `work_or_url` `related_item` (search an internal work
+  or enter an external URL; linked on show) plus a controlled
+  `relationship_type`.
+
+They are declared in `config/metadata/compound_metadata.yaml` (non-flexible
+mode) and in the default m3 profile (`config/metadata_profiles/m3_profile.yaml`,
+flexible mode, `available_on` both `Hyrax::Work` and the collection class).
+The engine base `Hyrax::Work` and `Hyrax::PcdmCollection` include them, and the
+base work and collection indexers flatten them, when
+`Hyrax.config.compound_metadata_enabled?` is true (the default; set
+`compound_metadata_enabled = false`, or `HYRAX_COMPOUND_METADATA_ENABLED=false`,
+to omit them). Applications can add their own compounds the same way and remove
+or override the samples.
+
+## Show-page rendering
+
+Because the show page renders from Solr (not the live resource), the indexer
+also stores each compound's ordered rows (limited to sub-fields with `display:`
+not false) as a single JSON field (`<compound>_json_ss`). The SolrDocument exposes a `<compound>` reader that
+parses it back into an array of hashes, and the generic
+`Hyrax::Renderers::CompoundAttributeRenderer` (selected by `view: render_as:
+compound`) renders each entry's populated sub-fields as a small definition
+list. Works render compounds through the standard `attribute_to_html` /
+`render_as` path; collections render them through the same shared renderer,
+invoked from the collection show view for terms the presenter reports as
+compounds. Sub-field labels come from the `hyrax.compound_fields.<compound>.<subfield>`
+i18n keys (humanized fallback).
+
+For a `controlled` sub-field, the show page displays the authority/value-list
+**term**, not the stored id — `Hyrax::CompoundSubfieldLabeler` resolves the id
+through the sub-field's inline `values:` list or its QA `authority:` (falling
+back to the id when no term matches), the same way scalar controlled fields
+display their term.
+
+### Inline vs. card display (`view: { display: card }`)
+
+By default a compound renders **inline** in the metadata list, like any other
+attribute. Declaring `view: { display: card }` on the compound instead renders
+it as its **own titled card** on the show page — matching the Relationships and
+Items cards — for compounds that read better as a standalone block:
+
+```yaml
+relationships:
+  type: hash
+  multiple: true
+  view:
+    render_as: compound
+    display: card
+  subfields:
+    related_item:      { type: work_or_url }
+    relationship_type: { type: controlled, authority: relationship_type }
+```
+
+`Hyrax::CompoundSchema` reports each compound's `display_mode` (`:inline` or
+`:card`); `card_compound_names` lists the card compounds. The view helper
+`render_compound_cards(presenter)` renders every card compound that has a value:
+
+- On a **work** show page, the cards render above the Relationships and Items
+  cards.
+- On a **collection** show page, the cards render after the search-within bar
+  and before the works list.
+
+Inline compounds are still listed by the presenter's `terms`; card compounds are
+excluded from the inline list (`inline_compound_names`) so they appear only as
+their card. A collection presenter delegates the card compound's reader to its
+SolrDocument so the same `attribute_to_html(:<compound>, render_as: :compound)`
+path resolves on a collection as on a work.
+
+## Profile validation (flexible mode)
+
+In flexible mode, `Hyrax::FlexibleSchemaValidators::CompoundValidator` checks
+compound declarations when an m3 profile is saved/uploaded, so a
+misconfiguration fails with a clear message instead of producing dead Solr
+fields or unrenderable values. It enforces: `subfields:` is a mapping; each
+sub-field config is a mapping; a `type: controlled` sub-field declares an
+option source (`authority:` or `values:`); and the compound does **not** carry
+a top-level `indexing:` (indexing is declared per sub-field — a top-level
+`indexing:` would point the catalog at a `<compound>_tesim` field the indexer
+never writes).
+
+## Validation
+
+Sub-field format and controlled-vocabulary correctness belong in an
+`ActiveModel::EachValidator` wired through the form's `validation` block — not
+in the populator, whose only job is shape conversion. This mirrors the
+`field_behaviors.md` guidance.
+
+## Bulkrax
+
+A compound round-trips through Bulkrax import and export with no additional
+code, using Bulkrax's declarative `nested_attributes: true` field-mapping flag
+(Bulkrax v9.4.3+). Declare the flag on every sibling mapping that shares the
+compound's `object:` value, and keep each mapping key equal to the sub-field
+key. See `field_behaviors.md` for the column conventions. Note: Bulkrax's
+controlled-URI sanitization does not currently descend into compound
+sub-fields.
diff --git a/documentation/forms/field_behaviors.md b/documentation/forms/field_behaviors.md
index 30dd68b630..e150959eb1 100644
--- a/documentation/forms/field_behaviors.md
+++ b/documentation/forms/field_behaviors.md
@@ -15,6 +15,17 @@ Two examples ship with Hyrax:
 
 This document covers the contract a Field Behavior must satisfy, the decision points for a new behavior, and the worked examples.
 
+> **For new multi-sub-field compounds, prefer the generic, schema-driven path.**
+> A field whose entries are a hash of named sub-fields (each an open-entry
+> string or a controlled-vocabulary lookup) can be declared entirely in the
+> schema YAML / m3 profile and rendered, populated, and indexed with no
+> per-field Ruby or ERB — see [`compound_fields.md`](compound_fields.md). The
+> hand-written Field Behaviors documented below remain the right tool for
+> special cases: single-value-per-entry controlled URIs with a presenter
+> (`based_near`), or compounds with bespoke behavior such as a radio-group
+> selection, write-time normalization, global-uniqueness validation, or
+> feature gating (`redirects`).
+
 ## Why this pattern exists
 
 Reform's `FormBuilderMethods#deserialize!` rewrites the submitted `<name>_attributes` key to `<name>` before `from_hash` runs. If the form *also* has a property named `<name>` (e.g. from an `include Hyrax::Schema(:foo)`), Reform's `from_hash` writes the raw fragment hash onto the property — bypassing the populator entirely.

From f23f344aae364cba44d20ba88ae812f663d4fd8a Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 16:30:51 -0400
Subject: [PATCH 07/32] Rename agent sample compound to agents

The sample compound now uses the attribute name `agents`, avoiding a
collision with the internal ACL `agent` attribute that shadowed it in
the Valkyrie permissive schema.

The collision dropped one entry from the permissive schema (and broke
its spec); the sub-field names (agent_name, agent_role) are unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../config/metadata_profiles/m3_profile.yaml  |  4 +--
 .../concerns/hyrax/solr_document/metadata.rb  |  2 +-
 config/locales/hyrax.en.yml                   |  2 +-
 config/metadata/compound_metadata.yaml        |  7 +++--
 config/metadata_profiles/m3_profile.yaml      |  4 +--
 documentation/forms/compound_fields.md        |  2 +-
 .../forms/compound_metadata_form_spec.rb      | 28 +++++++++----------
 .../hyrax/simple_schema_loader_spec.rb        |  2 +-
 8 files changed, 26 insertions(+), 25 deletions(-)

diff --git a/.koppie/config/metadata_profiles/m3_profile.yaml b/.koppie/config/metadata_profiles/m3_profile.yaml
index db5d29193b..3e501302cd 100644
--- a/.koppie/config/metadata_profiles/m3_profile.yaml
+++ b/.koppie/config/metadata_profiles/m3_profile.yaml
@@ -930,7 +930,7 @@ properties:
     property_uri: http://vocabulary.samvera.org/ns#transcriptIds
   # Sample compound (hierarchical) metadata, demonstrating the Hyrax compound
   # foundation in flexible mode. See documentation/forms/compound_fields.md.
-  agent:
+  agents:
     available_on:
       class:
         - GenericWork
@@ -939,7 +939,7 @@ properties:
     type: hash
     range: http://www.w3.org/2001/XMLSchema#string
     display_label:
-      default: Agent
+      default: Agents
     form:
       primary: false
     property_uri: http://id.loc.gov/vocabulary/relators/asn
diff --git a/app/models/concerns/hyrax/solr_document/metadata.rb b/app/models/concerns/hyrax/solr_document/metadata.rb
index 3d9f6e8d15..2b438b631d 100644
--- a/app/models/concerns/hyrax/solr_document/metadata.rb
+++ b/app/models/concerns/hyrax/solr_document/metadata.rb
@@ -125,7 +125,7 @@ def alt_text_for_view
         attribute :embargo_release_date, Solr::Date, Hydra.config.permissions.embargo.release_date
         attribute :lease_expiration_date, Solr::Date, Hydra.config.permissions.lease.expiration_date
         # Sample compound attributes shipped with Hyrax.
-        compound_attribute :agent
+        compound_attribute :agents
         compound_attribute :identifiers
         compound_attribute :compound_rights
         compound_attribute :relationships
diff --git a/config/locales/hyrax.en.yml b/config/locales/hyrax.en.yml
index 442ee89515..f898aca9ad 100644
--- a/config/locales/hyrax.en.yml
+++ b/config/locales/hyrax.en.yml
@@ -862,7 +862,7 @@ en:
       add_row: Add %{label}
       remove_row: Remove
       remove_row_with_label: Remove %{label}
-      agent:
+      agents:
         label: Agents
         title: Title
         agent_name: Name
diff --git a/config/metadata/compound_metadata.yaml b/config/metadata/compound_metadata.yaml
index 4c5e3977d2..f622c71e5c 100644
--- a/config/metadata/compound_metadata.yaml
+++ b/config/metadata/compound_metadata.yaml
@@ -12,9 +12,10 @@
 # app-level schema, or the m3 profile under HYRAX_FLEXIBLE=true) and may remove
 # these samples by setting `Hyrax.config.compound_metadata_enabled = false`.
 attributes:
-  # An agent associated with the work: a person or organization with a display
-  # title, a name, and a controlled role.
-  agent:
+  # Agents associated with the work: a person or organization with a display
+  # title, a name, and a controlled role. (Named `agents` to avoid colliding
+  # with the internal ACL `agent` attribute in hyrax_internal_metadata.yaml.)
+  agents:
     type: hash
     multiple: true
     predicate: http://id.loc.gov/vocabulary/relators/asn
diff --git a/config/metadata_profiles/m3_profile.yaml b/config/metadata_profiles/m3_profile.yaml
index 031e271739..2265afbf9e 100644
--- a/config/metadata_profiles/m3_profile.yaml
+++ b/config/metadata_profiles/m3_profile.yaml
@@ -956,7 +956,7 @@ properties:
   # `type: hash, multiple: true` property whose entries are hashes of the
   # `subfields:` keys, rendered/populated/indexed generically by the compound
   # foundation. See documentation/forms/compound_fields.md.
-  agent:
+  agents:
     available_on:
       class:
         - Hyrax::Work
@@ -965,7 +965,7 @@ properties:
     type: hash
     range: http://www.w3.org/2001/XMLSchema#string
     display_label:
-      default: Agent
+      default: Agents
     form:
       primary: false
     property_uri: http://id.loc.gov/vocabulary/relators/asn
diff --git a/documentation/forms/compound_fields.md b/documentation/forms/compound_fields.md
index aa0a2827c2..d5d6808779 100644
--- a/documentation/forms/compound_fields.md
+++ b/documentation/forms/compound_fields.md
@@ -204,7 +204,7 @@ end
 Hyrax ships sample compounds on **works and collections** by default,
 demonstrating the supported sub-field types:
 
-- **`agent`** — `title`, `agent_name`, and a controlled `agent_role` (inline
+- **`agents`** — `title`, `agent_name`, and a controlled `agent_role` (inline
   `values:`). A person or organization associated with the work or collection.
 - **`identifiers`** — an open-entry `identifier` plus a controlled
   `identifier_type` (inline `values:`).
diff --git a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
index 2116199594..8e21554908 100644
--- a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
+++ b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
@@ -41,35 +41,35 @@
 
   describe 'property registration' do
     it 'exposes the compound readers so the form partial can render existing rows' do
-      expect(form).to respond_to(:agent)
+      expect(form).to respond_to(:agents)
       expect(form).to respond_to(:identifiers)
     end
 
     it 'exposes the virtual `<compound>_attributes` setters for nested form params' do
-      expect(form).to respond_to(:agent_attributes=)
+      expect(form).to respond_to(:agents_attributes=)
       expect(form).to respond_to(:identifiers_attributes=)
     end
 
     it 'lists the compounds as compound_terms (and keeps them out of primary/secondary terms)' do
-      expect(form.compound_terms).to include(:agent, :identifiers, :compound_rights)
-      expect(form.primary_terms).not_to include(:agent, :identifiers, :compound_rights)
-      expect(form.secondary_terms).not_to include(:agent, :identifiers, :compound_rights)
+      expect(form.compound_terms).to include(:agents, :identifiers, :compound_rights)
+      expect(form.primary_terms).not_to include(:agents, :identifiers, :compound_rights)
+      expect(form.secondary_terms).not_to include(:agents, :identifiers, :compound_rights)
     end
 
-    it 'registers `agent_attributes` as a real Reform property (not just method-missing)' do
+    it 'registers `agents_attributes` as a real Reform property (not just method-missing)' do
       # This is the property that has to exist in Reform's schema *before*
       # validate runs; if it is registered too late the populator never fires.
       # In non-flexible mode it is registered on the form class via FormFields;
       # check the class definitions registry (the same lens the redirects
       # coverage uses).
       definition_keys = form.class.definitions.keys.map(&:to_s)
-      expect(definition_keys).to include('agent_attributes')
+      expect(definition_keys).to include('agents_attributes')
     end
   end
 
   describe 'validate + sync writes the compound to the model' do
     let(:params) do
-      { 'agent_attributes' =>
+      { 'agents_attributes' =>
           { '0' => { 'title' => 'Dr', 'agent_name' => 'Ada Lovelace', 'agent_role' => 'Author' } },
         'identifiers_attributes' =>
           { '0' => { 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' } } }
@@ -77,7 +77,7 @@
 
     it 'populates the compound on the form during validate' do
       form.validate(params)
-      expect(form.agent)
+      expect(form.agents)
         .to eq([{ 'title' => 'Dr', 'agent_name' => 'Ada Lovelace', 'agent_role' => 'Author' }])
       expect(form.identifiers)
         .to eq([{ 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' }])
@@ -86,19 +86,19 @@
     it 'writes the compound through to the model on sync' do
       form.validate(params)
       form.sync
-      expect(form.model.agent)
+      expect(form.model.agents)
         .to eq([{ 'title' => 'Dr', 'agent_name' => 'Ada Lovelace', 'agent_role' => 'Author' }])
       expect(form.model.identifiers)
         .to eq([{ 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' }])
     end
 
     it 'drops `_destroy` and all-blank rows' do
-      form.validate('agent_attributes' =>
+      form.validate('agents_attributes' =>
         { '0' => { 'agent_name' => 'Keep', 'agent_role' => 'Author' },
           '1' => { 'agent_name' => 'Remove', '_destroy' => 'true' },
           '2' => { 'title' => '', 'agent_name' => '', 'agent_role' => '' } })
       form.sync
-      expect(form.model.agent).to eq([{ 'title' => nil, 'agent_name' => 'Keep', 'agent_role' => 'Author' }])
+      expect(form.model.agents).to eq([{ 'title' => nil, 'agent_name' => 'Keep', 'agent_role' => 'Author' }])
     end
   end
 
@@ -109,13 +109,13 @@
       skip 'requires a Valkyrie (non-Fedora) persister' if
         Hyrax.persister.is_a?(Wings::Valkyrie::Persister)
 
-      form.validate('agent_attributes' =>
+      form.validate('agents_attributes' =>
         { '0' => { 'agent_name' => 'Grace Hopper', 'agent_role' => 'Editor' } })
       form.sync
       saved = Hyrax.persister.save(resource: form.model)
       reloaded = Hyrax.query_service.find_by(id: saved.id)
 
-      expect(reloaded.agent.first['agent_name'] || reloaded.agent.first[:agent_name])
+      expect(reloaded.agents.first['agent_name'] || reloaded.agents.first[:agent_name])
         .to eq('Grace Hopper')
     end
   end
diff --git a/spec/services/hyrax/simple_schema_loader_spec.rb b/spec/services/hyrax/simple_schema_loader_spec.rb
index 25fc43dcd8..98732db2af 100644
--- a/spec/services/hyrax/simple_schema_loader_spec.rb
+++ b/spec/services/hyrax/simple_schema_loader_spec.rb
@@ -140,7 +140,7 @@
     let(:permissive_schema) { schema_loader.permissive_schema_for_valkrie_adapter }
 
     it 'provides the expected hash' do
-      expect(permissive_schema.size).to eq(68)
+      expect(permissive_schema.size).to eq(72)
       expect(permissive_schema.values.all? { |v| v.is_a? RDF::URI }).to be_truthy
       expect(permissive_schema.values.all? { |v| v.value.present? }).to be_truthy
       expect(permissive_schema[:sample_attribute].value).to eq("http://hyrax-example.com/sample_attribute")

From 5b8b54f858cb70478d19e160611b8bf3c90e7925 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 18:41:44 -0400
Subject: [PATCH 08/32] Fix compound metadata display on collections

Compound metadata fields no longer show up twice on the collection form,
the collection creation page now displays validation errors, and those
error messages read cleanly.

The collection form was listing each compound field both in its own
section and again as an ordinary single field; when a sub-field was
required, the duplicate stopped the form from saving. The create page
also wasn't showing error messages at all, and the messages it built
read awkwardly.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../hyrax/dashboard/collections_controller.rb      | 10 +++++-----
 app/forms/hyrax/forms/pcdm_collection_form.rb      |  4 ++--
 app/views/hyrax/dashboard/collections/new.html.erb |  1 +
 .../forms/hyrax/forms/pcdm_collection_form_spec.rb | 14 ++++++++++++++
 4 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/app/controllers/hyrax/dashboard/collections_controller.rb b/app/controllers/hyrax/dashboard/collections_controller.rb
index 80646f0f15..155f6f04ed 100644
--- a/app/controllers/hyrax/dashboard/collections_controller.rb
+++ b/app/controllers/hyrax/dashboard/collections_controller.rb
@@ -271,11 +271,11 @@ def valkyrie_destroy
       end
 
       def form_err_msg(form)
-        errmsg = []
-        form.errors.messages.each do |fld, err|
-          errmsg << "#{fld} #{err.to_sentence}"
-        end
-        errmsg.to_sentence
+        # Use ActiveModel's full_messages: it humanizes the attribute name
+        # ("collection_type_gid" -> "Collection type gid") and renders :base
+        # errors (e.g. the compound-required messages) verbatim, instead of the
+        # raw "#{field_key} #{message}" we'd otherwise emit ("base ...").
+        form.errors.full_messages.to_sentence
       end
 
       def default_collection_type
diff --git a/app/forms/hyrax/forms/pcdm_collection_form.rb b/app/forms/hyrax/forms/pcdm_collection_form.rb
index a007bc3807..6aa8b2f2f0 100644
--- a/app/forms/hyrax/forms/pcdm_collection_form.rb
+++ b/app/forms/hyrax/forms/pcdm_collection_form.rb
@@ -71,7 +71,7 @@ def required_fields
       def primary_terms
         terms = _form_field_definitions
                 .select { |_, definition| definition[:primary] }
-                .keys.map(&:to_sym)
+                .keys.map(&:to_sym) - compound_terms
 
         terms = [:schema_version] + terms if model.flexible?
         terms
@@ -82,7 +82,7 @@ def primary_terms
       def secondary_terms
         _form_field_definitions
           .select { |_, definition| definition[:display] && !definition[:primary] }
-          .keys.map(&:to_sym)
+          .keys.map(&:to_sym) - compound_terms
       end
 
       ##
diff --git a/app/views/hyrax/dashboard/collections/new.html.erb b/app/views/hyrax/dashboard/collections/new.html.erb
index ccdfc3d10f..858ef220ed 100644
--- a/app/views/hyrax/dashboard/collections/new.html.erb
+++ b/app/views/hyrax/dashboard/collections/new.html.erb
@@ -7,6 +7,7 @@
 
 <div class="row">
   <div class="col-md-12">
+    <%= render 'flash_msg' %>
     <%= render 'form' %>
   </div>
 </div>
diff --git a/spec/forms/hyrax/forms/pcdm_collection_form_spec.rb b/spec/forms/hyrax/forms/pcdm_collection_form_spec.rb
index 30feca14bb..e9cff6cbcd 100644
--- a/spec/forms/hyrax/forms/pcdm_collection_form_spec.rb
+++ b/spec/forms/hyrax/forms/pcdm_collection_form_spec.rb
@@ -28,6 +28,20 @@
     end
   end
 
+  # Compounds render via the dedicated compound section, not as scalar fields;
+  # they must be excluded from primary/secondary terms or they would render a
+  # second, broken scalar input (a `required` compound would block form submit
+  # client-side). PcdmCollectionForm overrides these terms, so it needs the same
+  # exclusion ResourceForm has.
+  describe 'compound terms are excluded from scalar term lists', if: Hyrax.config.compound_metadata_enabled? do
+    it 'keeps compounds out of primary_terms and secondary_terms' do
+      compounds = form.compound_terms
+      skip 'no compounds declared on the collection in this configuration' if compounds.empty?
+      expect(form.primary_terms).not_to include(*compounds)
+      expect(form.secondary_terms).not_to include(*compounds)
+    end
+  end
+
   describe '#banner_info' do
     let(:banner_info) do
       CollectionBrandingInfo.new(

From a4363ab827e3ec20963736ab891fc8fd449280d2 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 18:43:30 -0400
Subject: [PATCH 09/32] Validate required compound sub-fields

A compound can now mark sub-fields required (filled in every entry) and
mark itself required (at least one entry). On save the form blocks with
one error per compound, naming the field; required fields show a * on
the form. Works the same in both flexible and non-flexible modes, on
works and collections.

The rules live in Hyrax::CompoundEntryValidation, a plain object
decoupled from the form so they can be reused and tested directly;
Hyrax::CompoundEntryValidator wires it onto the resource form. The
shipped sample compounds require their sub-fields within an entry but
remain optional overall.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../config/metadata_profiles/m3_profile.yaml  |   6 +
 .../concerns/hyrax/flexible_form_behavior.rb  |  15 +++
 app/forms/hyrax/forms/resource_form.rb        |  11 ++
 .../hyrax/compound_entry_validation.rb        |  72 ++++++++++++
 app/services/hyrax/compound_schema.rb         |  55 ++++++++--
 .../hyrax/compound_entry_validator.rb         |  64 +++++++++++
 .../hyrax/compounds/_compound_row.html.erb    |   5 +-
 .../compounds/_compound_section.html.erb      |   3 +-
 config/locales/hyrax.en.yml                   |   3 +
 config/metadata/compound_metadata.yaml        |   6 +
 config/metadata_profiles/m3_profile.yaml      |   6 +
 documentation/forms/compound_fields.md        |  43 ++++++++
 lib/hyrax/form_fields.rb                      |   9 +-
 .../forms/compound_metadata_form_spec.rb      |  42 +++++++
 .../hyrax/compound_entry_validation_spec.rb   |  77 +++++++++++++
 spec/services/hyrax/compound_schema_spec.rb   |  71 +++++++++++-
 .../hyrax/compound_entry_validator_spec.rb    | 103 ++++++++++++++++++
 17 files changed, 572 insertions(+), 19 deletions(-)
 create mode 100644 app/services/hyrax/compound_entry_validation.rb
 create mode 100644 app/validators/hyrax/compound_entry_validator.rb
 create mode 100644 spec/services/hyrax/compound_entry_validation_spec.rb
 create mode 100644 spec/validators/hyrax/compound_entry_validator_spec.rb

diff --git a/.koppie/config/metadata_profiles/m3_profile.yaml b/.koppie/config/metadata_profiles/m3_profile.yaml
index 3e501302cd..083f7873d0 100644
--- a/.koppie/config/metadata_profiles/m3_profile.yaml
+++ b/.koppie/config/metadata_profiles/m3_profile.yaml
@@ -947,9 +947,11 @@ properties:
       title: { type: string }
       agent_name:
         type: string
+        required: true
         indexing: [agent_name_sim, agent_name_tesim]
       agent_role:
         type: controlled
+        required: true
         values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
         indexing: [agent_role_sim, agent_role_tesim]
     groups:
@@ -973,9 +975,11 @@ properties:
     subfields:
       identifier:
         type: string
+        required: true
         indexing: [identifier_value_sim, identifier_value_tesim]
       identifier_type:
         type: controlled
+        required: true
         values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
         indexing: [identifier_type_sim]
     view:
@@ -1025,9 +1029,11 @@ properties:
     subfields:
       related_item:
         type: work_or_url
+        required: true
         indexing: [relationships_item_ssim]
       relationship_type:
         type: controlled
+        required: true
         values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
         indexing: [relationships_type_sim]
     view:
diff --git a/app/forms/concerns/hyrax/flexible_form_behavior.rb b/app/forms/concerns/hyrax/flexible_form_behavior.rb
index 0d1198e4c5..fa59896c4d 100644
--- a/app/forms/concerns/hyrax/flexible_form_behavior.rb
+++ b/app/forms/concerns/hyrax/flexible_form_behavior.rb
@@ -13,6 +13,10 @@ def validate_flexible_required_fields
       required_fields = singleton_class.schema_definitions.select { |_, opts| opts[:required] }.keys
 
       required_fields.each do |field|
+        # Compound fields carry their own requiredness rules (per-row sub-field
+        # checks); Hyrax::CompoundEntryValidator owns them, so skip the generic
+        # blank check to avoid a duplicate "can't be blank" error.
+        next if compound_field?(field)
         value = send(field)
         errors.add(field, :blank) if value.blank?
       end
@@ -25,6 +29,17 @@ def schema
 
     private
 
+    # Whether the field is a compound (declares `subfields:`), looked up from
+    # the resource's compound schema — the flex form definitions don't carry
+    # `subfields`. Memoized per form instance.
+    def compound_field?(field)
+      return false unless Hyrax.config.respond_to?(:compound_metadata_enabled?) && Hyrax.config.compound_metadata_enabled?
+      @compound_field_names ||= Hyrax::CompoundSchema.for(model).compound_names
+      @compound_field_names.include?(field.to_sym)
+    rescue StandardError
+      false
+    end
+
     # OVERRIDE valkyrie 3.0.1 to make schema dynamic
     def field(field_name)
       singleton_class.schema_definitions.fetch(field_name.to_s)
diff --git a/app/forms/hyrax/forms/resource_form.rb b/app/forms/hyrax/forms/resource_form.rb
index 28c6108182..c2cbab8578 100644
--- a/app/forms/hyrax/forms/resource_form.rb
+++ b/app/forms/hyrax/forms/resource_form.rb
@@ -64,6 +64,17 @@ class ResourceForm < Hyrax::ChangeSet # rubocop:disable Metrics/ClassLength
         end
       end
 
+      # Required-compound / required-sub-field validation. Wired through a
+      # `validation { ... }` block (not a bare `validates_with`) because these
+      # are Reform/Disposable forms — a bare `validates_with` does not hook into
+      # Reform's `validate`, so it would never run. Record-level (no
+      # `attributes:`), so it is replay-safe.
+      if Hyrax.config.compound_metadata_enabled?
+        validation(name: :default, inherit: true) do
+          validates_with Hyrax::CompoundEntryValidator
+        end
+      end
+
       ##
       # @api public
       #
diff --git a/app/services/hyrax/compound_entry_validation.rb b/app/services/hyrax/compound_entry_validation.rb
new file mode 100644
index 0000000000..b8d5d04e26
--- /dev/null
+++ b/app/services/hyrax/compound_entry_validation.rb
@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Hyrax
+  ##
+  # @api public
+  #
+  # Pure validation logic for a single compound's entries, decoupled from
+  # ActiveModel and Reform so it can be reused (e.g. a future Bulkrax-side
+  # check) and unit-tested directly. {Hyrax::CompoundEntryValidator} wraps this
+  # for the form layer. See documentation/forms/compound_fields.md.
+  #
+  # Rules (driven by the normalized definition from {Hyrax::CompoundSchema}):
+  #   * a compound marked `required` must have at least one populated row;
+  #   * every populated row must fill all of the compound's `required` sub-fields.
+  #
+  # Rows are the post-populator persisted hashes (all-blank rows already
+  # dropped), so a no-required compound with no rows is valid.
+  class CompoundEntryValidation
+    # @param definition [Hash] the normalized compound definition
+    # @param entries [Array<Hash>] the compound's persisted rows
+    def initialize(definition, entries)
+      @definition = definition || {}
+      @entries = Array(entries)
+    end
+
+    # @return [Array<Hash>] one violation per problem, each
+    #   `{ type:, missing: [keys] }`. Empty when the compound is valid.
+    #   `type` is `:required_but_empty` or `:missing_required_subfields`.
+    def violations
+      return [{ type: :required_but_empty, missing: required_keys }] if required_but_empty?
+
+      rows_missing_required.map { |missing| { type: :missing_required_subfields, missing: missing } }
+    end
+
+    # @return [Boolean]
+    def valid?
+      violations.empty?
+    end
+
+    private
+
+    attr_reader :definition, :entries
+
+    def required_keys
+      definition.fetch(:subfields, {}).select { |_k, spec| spec[:required] }.keys
+    end
+
+    def required_but_empty?
+      definition[:required] && populated_rows.empty?
+    end
+
+    # The set of required keys missing from each populated row that omits any of
+    # them (one entry per offending row; deduped so identical gaps collapse to
+    # one message).
+    def rows_missing_required
+      return [] if required_keys.empty?
+
+      populated_rows.filter_map do |row|
+        missing = required_keys.reject { |key| value_present?(row, key) }
+        missing unless missing.empty?
+      end.uniq
+    end
+
+    def populated_rows
+      entries.select { |row| row.is_a?(::Hash) && row.values.any?(&:present?) }
+    end
+
+    def value_present?(row, key)
+      (row[key] || row[key.to_sym]).present?
+    end
+  end
+end
diff --git a/app/services/hyrax/compound_schema.rb b/app/services/hyrax/compound_schema.rb
index ec04b1bc5c..fbdcec56ed 100644
--- a/app/services/hyrax/compound_schema.rb
+++ b/app/services/hyrax/compound_schema.rb
@@ -12,7 +12,7 @@ module Hyrax
   # Declarations are read from each attribute's Dry type `meta`, which both
   # schema loaders populate identically, so the result is the same in both flex
   # modes.
-  class CompoundSchema
+  class CompoundSchema # rubocop:disable Metrics/ClassLength
     ##
     # Build a CompoundSchema for a resource instance or class.
     #
@@ -102,6 +102,22 @@ def subfield_keys(attribute_name)
       definition[:subfields].keys
     end
 
+    ##
+    # @return [Boolean] whether the compound itself is required (at least one
+    #   row must be present to save).
+    def required?(attribute_name)
+      definition_for(attribute_name)&.dig(:required) || false
+    end
+
+    ##
+    # @return [Array<String>] the sub-field keys declared `required: true` for
+    #   the compound (each must be filled in every populated row).
+    def required_subfield_keys(attribute_name)
+      definition = definition_for(attribute_name)
+      return [] unless definition
+      definition[:subfields].select { |_key, spec| spec[:required] }.keys
+    end
+
     ##
     # @return [Hash{Symbol => Hash}] a map from compound attribute name to its
     #   normalized declaration. Memoized per instance.
@@ -135,19 +151,38 @@ def build_definitions
     # indexer, and renderer consume. See documentation/forms/compound_fields.md
     # for the meaning of each sub-field key.
     def normalize(config, subfields)
-      sub = subfields.each_with_object({}) do |(key, opts), memo|
-        opts = (opts.is_a?(Hash) ? opts : {}).with_indifferent_access
-        memo[key.to_s] = { type: (opts['type'] || 'string').to_s,
-                           authority: opts['authority']&.to_s,
-                           values: normalize_values(opts['values']),
-                           index_keys: normalize_index_keys(opts),
-                           display: opts.fetch('display', true) != false }
-      end
+      sub = subfields.each_with_object({}) { |(key, opts), memo| memo[key.to_s] = normalize_subfield(opts) }
 
       view = config['view']
       display_mode = view.is_a?(Hash) && view['display'].to_s == 'card' ? :card : :inline
 
-      { subfields: sub, groups: normalize_groups(config['groups'], sub.keys), display_mode: display_mode }
+      { subfields: sub,
+        groups: normalize_groups(config['groups'], sub.keys),
+        display_mode: display_mode,
+        required: compound_required?(config) }
+    end
+
+    def normalize_subfield(opts)
+      opts = (opts.is_a?(Hash) ? opts : {}).with_indifferent_access
+      { type: (opts['type'] || 'string').to_s,
+        authority: opts['authority']&.to_s,
+        values: normalize_values(opts['values']),
+        index_keys: normalize_index_keys(opts),
+        display: opts.fetch('display', true) != false,
+        required: truthy?(opts['required']) }
+    end
+
+    # Whether the compound itself is required (at least one row must exist).
+    # Reads `required: true` (non-flexible) or a minimum cardinality >= 1
+    # (flexible), mirroring how M3AttributeDefinition derives requirement.
+    def compound_required?(config)
+      return true if truthy?(config['required'])
+      cardinality = config['cardinality']
+      cardinality.is_a?(Hash) && cardinality['minimum'].present? && cardinality['minimum'].to_i >= 1
+    end
+
+    def truthy?(value)
+      ActiveModel::Type::Boolean.new.cast(value) == true
     end
 
     # Reads `index_keys:` (non-flexible) or `indexing:` (flexible), filtering the
diff --git a/app/validators/hyrax/compound_entry_validator.rb b/app/validators/hyrax/compound_entry_validator.rb
new file mode 100644
index 0000000000..352679c34f
--- /dev/null
+++ b/app/validators/hyrax/compound_entry_validator.rb
@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Hyrax
+  # Validates every compound (hierarchical) metadata attribute on a form,
+  # blocking save when a required compound has no row or a populated row omits a
+  # required sub-field. Adds one error per compound, keyed on the compound name.
+  #
+  # Record-level (not an EachValidator) because the compound set is schema-driven
+  # and not known at form-class-definition time. The per-compound rules live in
+  # the reusable {Hyrax::CompoundEntryValidation}. See
+  # documentation/forms/compound_fields.md.
+  class CompoundEntryValidator < ActiveModel::Validator
+    def validate(record)
+      return unless Hyrax.config.compound_metadata_enabled?
+
+      schema = Hyrax::CompoundSchema.for(schema_source(record))
+      schema.definitions.each do |name, definition|
+        next unless record.respond_to?(name)
+        validate_compound(record, name, definition)
+      end
+    rescue StandardError => e
+      Hyrax.logger.debug("CompoundEntryValidator: #{e.message}")
+    end
+
+    private
+
+    # The schema declarations live on the underlying resource, not the form
+    # wrapper: a Reform form exposes it as `model`. Fall back to the record
+    # itself (e.g. a plain ActiveModel object in unit tests).
+    def schema_source(record)
+      record.respond_to?(:model) ? record.model : record
+    end
+
+    def validate_compound(record, name, definition)
+      entries = Array(record.public_send(name))
+      Hyrax::CompoundEntryValidation.new(definition, entries).violations.each do |violation|
+        # Attach to :base, not the attribute, because the work and collection
+        # forms render errors differently (raw messages vs. full_messages):
+        # keying on the attribute would either double the field name
+        # ("Agents Agents ...") or print the raw key ("agents ..."). A :base
+        # error renders verbatim everywhere, and the message names the compound.
+        record.errors.add(:base, message_for(name, violation))
+      end
+    end
+
+    # The message names the compound itself (it is attached to :base, so no
+    # attribute-name prefix is added by the view).
+    def message_for(name, violation)
+      I18n.t("hyrax.compound_fields.errors.#{violation[:type]}",
+             compound: compound_label(name),
+             fields: subfield_labels(name, violation[:missing]))
+    end
+
+    def compound_label(name)
+      I18n.t("hyrax.compound_fields.#{name}.label", default: name.to_s.humanize)
+    end
+
+    def subfield_labels(name, keys)
+      Array(keys).map do |key|
+        I18n.t("hyrax.compound_fields.#{name}.#{key}", default: key.to_s.humanize)
+      end.join(', ')
+    end
+  end
+end
diff --git a/app/views/hyrax/compounds/_compound_row.html.erb b/app/views/hyrax/compounds/_compound_row.html.erb
index d9dee8d6f4..a5ea6cd834 100644
--- a/app/views/hyrax/compounds/_compound_row.html.erb
+++ b/app/views/hyrax/compounds/_compound_row.html.erb
@@ -40,7 +40,10 @@
           <% input_name = "#{f.object_name}[#{compound_name}_attributes][#{index}][#{sub_field}]" %>
           <% value = row_value.call(sub_field) %>
           <div class="form-group col-md-<%= group.fetch(:cols, 6) %>">
-            <%= label_tag input_id, compound_subfield_label(compound_name, sub_field), class: 'form-label small text-muted' %>
+            <%= label_tag input_id, class: 'form-label small text-muted' do %>
+              <%= compound_subfield_label(compound_name, sub_field) %><%
+                if spec[:required] %><abbr title="<%= t('simple_form.required.text', default: 'required') %>" class="required text-danger">*</abbr><% end %>
+            <% end %>
             <% case spec[:type] %>
             <% when 'controlled' %>
               <% select_classes = ['form-control', 'form-control-sm'] %>
diff --git a/app/views/hyrax/compounds/_compound_section.html.erb b/app/views/hyrax/compounds/_compound_section.html.erb
index 8272ddc9a9..0eec2654dd 100644
--- a/app/views/hyrax/compounds/_compound_section.html.erb
+++ b/app/views/hyrax/compounds/_compound_section.html.erb
@@ -19,7 +19,8 @@
 <section class="hyrax-compound mb-4" data-hyrax-compound data-next-index="<%= rows.length %>" id="<%= compound_id %>">
   <%# A label element, not a heading, so it matches the form's field labels
       rather than inheriting Bootstrap's h1–h6 sizing. role=heading for a11y. %>
-  <label class="control-label d-block mb-2" role="heading" aria-level="3"><%= display_label %></label>
+  <label class="control-label d-block mb-2" role="heading" aria-level="3"><%= display_label %><%
+    if definition[:required] %> <abbr title="<%= t('simple_form.required.text', default: 'required') %>" class="required text-danger">*</abbr><% end %></label>
 
   <%# Always-submitted marker so the populator runs even when every row is
       removed from the DOM. The populator drops the `_marker` row. %>
diff --git a/config/locales/hyrax.en.yml b/config/locales/hyrax.en.yml
index f898aca9ad..3938c7294b 100644
--- a/config/locales/hyrax.en.yml
+++ b/config/locales/hyrax.en.yml
@@ -862,6 +862,9 @@ en:
       add_row: Add %{label}
       remove_row: Remove
       remove_row_with_label: Remove %{label}
+      errors:
+        required_but_empty: "%{compound} requires at least one entry"
+        missing_required_subfields: "Each %{compound} entry requires: %{fields}"
       agents:
         label: Agents
         title: Title
diff --git a/config/metadata/compound_metadata.yaml b/config/metadata/compound_metadata.yaml
index f622c71e5c..1bc6141ebe 100644
--- a/config/metadata/compound_metadata.yaml
+++ b/config/metadata/compound_metadata.yaml
@@ -29,11 +29,13 @@ attributes:
       title: { type: string }
       agent_name:
         type: string
+        required: true
         index_keys: [agent_name_sim, agent_name_tesim]
       # A controlled sub-field can take its options from an inline list (below)
       # or from an existing QA local authority (`authority: <name>`).
       agent_role:
         type: controlled
+        required: true
         values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
         index_keys: [agent_role_sim, agent_role_tesim]
     groups:
@@ -53,9 +55,11 @@ attributes:
     subfields:
       identifier:
         type: string
+        required: true
         index_keys: [identifier_value_sim, identifier_value_tesim]
       identifier_type:
         type: controlled
+        required: true
         values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
         index_keys: [identifier_type_sim]
     view:
@@ -98,9 +102,11 @@ attributes:
     subfields:
       related_item:
         type: work_or_url
+        required: true
         index_keys: [relationships_item_ssim]
       relationship_type:
         type: controlled
+        required: true
         values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
         index_keys: [relationships_type_sim]
     view:
diff --git a/config/metadata_profiles/m3_profile.yaml b/config/metadata_profiles/m3_profile.yaml
index 2265afbf9e..61b8de53e7 100644
--- a/config/metadata_profiles/m3_profile.yaml
+++ b/config/metadata_profiles/m3_profile.yaml
@@ -975,9 +975,11 @@ properties:
       title: { type: string }
       agent_name:
         type: string
+        required: true
         indexing: [agent_name_sim, agent_name_tesim]
       agent_role:
         type: controlled
+        required: true
         values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
         indexing: [agent_role_sim, agent_role_tesim]
     groups:
@@ -1001,9 +1003,11 @@ properties:
     subfields:
       identifier:
         type: string
+        required: true
         indexing: [identifier_value_sim, identifier_value_tesim]
       identifier_type:
         type: controlled
+        required: true
         values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
         indexing: [identifier_type_sim]
     view:
@@ -1053,9 +1057,11 @@ properties:
     subfields:
       related_item:
         type: work_or_url
+        required: true
         indexing: [relationships_item_ssim]
       relationship_type:
         type: controlled
+        required: true
         values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
         indexing: [relationships_type_sim]
     view:
diff --git a/documentation/forms/compound_fields.md b/documentation/forms/compound_fields.md
index d5d6808779..b8a64e387b 100644
--- a/documentation/forms/compound_fields.md
+++ b/documentation/forms/compound_fields.md
@@ -145,6 +145,12 @@ the show page renders from. Combined with indexing, each sub-field can be:
 - **searchable-only** — has `index_keys:` and `display: false` (indexed, hidden on show)
 - **neither** — no `index_keys:` and `display: false`
 
+### `required:` (optional, default false)
+
+Marks a sub-field as required within each populated row, or — when set on the
+compound itself — marks the whole compound as required. See
+[Required sub-fields](#required-sub-fields) below.
+
 ## Persisted shape
 
 A compound persists as an array of plain string-keyed hashes — exactly the
@@ -290,6 +296,43 @@ a top-level `indexing:` (indexing is declared per sub-field — a top-level
 `indexing:` would point the catalog at a `<compound>_tesim` field the indexer
 never writes).
 
+## Required sub-fields
+
+A compound declares requiredness at two levels:
+
+- **Sub-field level** — `required: true` on a sub-field means every populated
+  row must fill it. A row that fills some-but-not-all of its required
+  sub-fields blocks save (e.g. a relationship row with a related item but no
+  type).
+- **Compound level** — `required: true` on the compound (or, in flexible mode,
+  a minimum cardinality of 1) means at least one row must be present to save.
+  An optional compound with no rows is always valid; the sub-field rules only
+  apply to rows the user actually adds.
+
+```yaml
+relationships:
+  type: hash
+  multiple: true
+  required: true            # the work must have at least one relationship
+  subfields:
+    related_item:      { type: work_or_url, required: true }
+    relationship_type: { type: controlled, authority: relationship_type, required: true }
+    note:              { type: string }   # optional
+```
+
+Required sub-fields and required compounds render a `*` marker on the form
+label. On save, `Hyrax::CompoundEntryValidator` (wired on the resource form,
+gated by `compound_metadata_enabled?`) adds one error per compound, keyed on the
+compound's attribute name, so the failure is reported against that field. The
+rules are the same in both flex modes.
+
+The decision logic lives in `Hyrax::CompoundEntryValidation`, a plain object
+decoupled from ActiveModel and Reform — given a compound's definition and its
+rows it returns the violations. That seam keeps the rules reusable (e.g. a
+future Bulkrax-side check) and unit-testable without a form. Note: Bulkrax
+import does not currently run this validation, so a required sub-field can be
+left empty by an import.
+
 ## Validation
 
 Sub-field format and controlled-vocabulary correctness belong in an
diff --git a/lib/hyrax/form_fields.rb b/lib/hyrax/form_fields.rb
index 3e26c0c075..a6a823f2be 100644
--- a/lib/hyrax/form_fields.rb
+++ b/lib/hyrax/form_fields.rb
@@ -68,11 +68,16 @@ def included(descendant)
       configs = attribute_configs
       form_field_definitions.each do |field_name, options|
         descendant.property field_name.to_sym, options.merge(display: options.fetch(:display, true), default: [])
-        descendant.validates field_name.to_sym, presence: true if options.fetch(:required, false)
+        is_compound = compound_field?(configs, field_name)
+        # A compound's requiredness is enforced by Hyrax::CompoundEntryValidator
+        # (which understands per-row sub-field rules); a plain `presence` check
+        # on the array would both duplicate that and pass on a present-but-empty
+        # row. So only scalar fields get the generic presence validator.
+        descendant.validates field_name.to_sym, presence: true if options.fetch(:required, false) && !is_compound
         # A compound also needs a virtual `<field>_attributes` populator
         # property, registered here so it is part of Reform's schema before
         # `validate` runs (cf. Hyrax::RedirectsFieldBehavior).
-        next unless compound_field?(configs, field_name)
+        next unless is_compound
         descendant.property :"#{field_name}_attributes",
                             virtual: true,
                             populator: :compound_attributes_populator
diff --git a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
index 8e21554908..4bcd4fe3c2 100644
--- a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
+++ b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
@@ -102,6 +102,48 @@
     end
   end
 
+  describe 'required-subfield validation blocks save' do
+    # Exercises the real form + Hyrax::CompoundEntryValidator end to end against
+    # the *shipped* compound schema (no stub). The shipped samples require
+    # sub-fields within a row (e.g. agents needs agent_name + agent_role,
+    # relationships needs related_item + relationship_type) but none is required
+    # at the compound level, so an empty compound is valid. Asserting through the
+    # real schema is what catches a validator that reads the form wrapper instead
+    # of `form.model`.
+    #
+    # Compound errors are attached to :base with the compound named in the
+    # message (so they render cleanly on both the work and collection forms).
+    def base_errors(form)
+      form.valid?
+      form.errors[:base]
+    end
+
+    it 'allows an empty compound (none is required at the compound level)' do
+      form.validate('agents_attributes' => { '_marker' => { '_destroy' => '1' } })
+      expect(base_errors(form)).to be_empty
+    end
+
+    it 'flags an agents row that omits a required sub-field' do
+      form.validate('agents_attributes' => { '0' => { 'agent_role' => 'Author' } })
+      expect(base_errors(form)).to include(a_string_including('Agents'))
+    end
+
+    it 'flags a relationships row that omits a required sub-field' do
+      form.validate('relationships_attributes' => { '0' => { 'relationship_type' => 'References' } })
+      expect(base_errors(form)).to include(a_string_including('Relationships'))
+    end
+
+    it 'does not flag agents when its required sub-fields are filled' do
+      form.validate('agents_attributes' => { '0' => { 'agent_name' => 'Ada', 'agent_role' => 'Author' } })
+      expect(base_errors(form)).not_to include(a_string_including('Agents'))
+    end
+
+    it 'never flags `compound_rights` (no required sub-fields)' do
+      form.validate('agents_attributes' => { '0' => { 'agent_name' => 'Ada', 'agent_role' => 'Author' } })
+      expect(base_errors(form)).not_to include(a_string_including('Rights'))
+    end
+  end
+
   describe 'persistence round-trip', :active_fedora do
     # Skips on the Fedora adapter, which cannot serialize plain-hash compounds
     # to RDF; the compound feature targets the Valkyrie/Postgres path.
diff --git a/spec/services/hyrax/compound_entry_validation_spec.rb b/spec/services/hyrax/compound_entry_validation_spec.rb
new file mode 100644
index 0000000000..2e6c01cf8c
--- /dev/null
+++ b/spec/services/hyrax/compound_entry_validation_spec.rb
@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::CompoundEntryValidation do
+  # A definition shaped like Hyrax::CompoundSchema#definition_for produces.
+  def build_definition(required: false, subfields: {})
+    { required: required, subfields: subfields }
+  end
+
+  def sub(required: false)
+    { type: 'string', required: required }
+  end
+
+  describe 'a compound with no required sub-fields and not required itself' do
+    let(:definition) { build_definition(subfields: { 'a' => sub, 'b' => sub }) }
+
+    it 'is valid with no rows' do
+      expect(described_class.new(definition, []).violations).to be_empty
+    end
+
+    it 'is valid with a partially-filled row' do
+      expect(described_class.new(definition, [{ 'a' => 'x' }]).violations).to be_empty
+    end
+  end
+
+  describe 'a compound with required sub-fields (optional compound)' do
+    let(:definition) { build_definition(subfields: { 'item' => sub(required: true), 'type' => sub(required: true), 'note' => sub }) }
+
+    it 'is valid with no rows (compound itself is optional)' do
+      expect(described_class.new(definition, []).violations).to be_empty
+    end
+
+    it 'is valid when every populated row fills all required sub-fields' do
+      entries = [{ 'item' => 'a', 'type' => 't' }, { 'item' => 'b', 'type' => 't', 'note' => 'n' }]
+      expect(described_class.new(definition, entries).violations).to be_empty
+    end
+
+    it 'flags a row missing a required sub-field' do
+      violations = described_class.new(definition, [{ 'item' => 'a' }]).violations
+      expect(violations).to contain_exactly(type: :missing_required_subfields, missing: ['type'])
+    end
+
+    it 'reports one violation per distinct missing-key set (deduped)' do
+      entries = [{ 'item' => 'a' }, { 'item' => 'b' }] # both miss only `type`
+      violations = described_class.new(definition, entries).violations
+      expect(violations.size).to eq(1)
+    end
+
+    it 'accepts symbol-keyed rows' do
+      expect(described_class.new(definition, [{ item: 'a', type: 't' }]).violations).to be_empty
+    end
+  end
+
+  describe 'a required compound' do
+    let(:definition) { build_definition(required: true, subfields: { 'a' => sub(required: true) }) }
+
+    it 'flags an empty compound' do
+      expect(described_class.new(definition, []).violations)
+        .to contain_exactly(type: :required_but_empty, missing: ['a'])
+    end
+
+    it 'is valid with a complete row' do
+      expect(described_class.new(definition, [{ 'a' => 'x' }]).violations).to be_empty
+    end
+
+    it 'flags an incomplete row rather than emptiness when a row is present' do
+      violations = described_class.new(definition, [{ 'a' => '' }]).violations
+      # an all-blank row is not "populated", so the compound reads as empty
+      expect(violations).to contain_exactly(type: :required_but_empty, missing: ['a'])
+    end
+  end
+
+  describe '#valid?' do
+    it 'is true when there are no violations' do
+      expect(described_class.new(build_definition(subfields: { 'a' => sub }), []).valid?).to be true
+    end
+  end
+end
diff --git a/spec/services/hyrax/compound_schema_spec.rb b/spec/services/hyrax/compound_schema_spec.rb
index 5cf9e9052f..4625f1e5f3 100644
--- a/spec/services/hyrax/compound_schema_spec.rb
+++ b/spec/services/hyrax/compound_schema_spec.rb
@@ -42,6 +42,23 @@ def self.name
                   },
                   view: { 'display' => 'card' }
                 )
+      # Required at the compound level (non-flexible `required: true`) with two
+      # required sub-fields and one optional.
+      attribute :required_compound,
+                Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
+                  required: true,
+                  subfields: {
+                    'item' => { 'type' => 'string', 'required' => true },
+                    'kind' => { 'type' => 'string', 'required' => true },
+                    'note' => { 'type' => 'string' }
+                  }
+                )
+      # Required at the compound level via m3 minimum cardinality (flexible).
+      attribute :cardinality_compound,
+                Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
+                  cardinality: { 'minimum' => 1 },
+                  subfields: { 'value' => { 'type' => 'string' } }
+                )
     end
   end
 
@@ -49,7 +66,8 @@ def self.name
 
   describe '#compound_names' do
     it 'returns only the attributes that declare subfields' do
-      expect(schema.compound_names).to contain_exactly(:contributors, :identifiers, :agent, :relationships)
+      expect(schema.compound_names).to contain_exactly(:contributors, :identifiers, :agent, :relationships,
+                                                       :required_compound, :cardinality_compound)
     end
 
     it 'does not treat a plain scalar attribute as a compound' do
@@ -60,7 +78,8 @@ def self.name
   describe 'display mode (view: { display: card })' do
     describe '#inline_compound_names' do
       it 'excludes compounds declared as cards' do
-        expect(schema.inline_compound_names).to contain_exactly(:contributors, :identifiers, :agent)
+        expect(schema.inline_compound_names).to contain_exactly(:contributors, :identifiers, :agent,
+                                                                :required_compound, :cardinality_compound)
       end
     end
 
@@ -91,6 +110,47 @@ def self.name
     end
   end
 
+  describe 'required declarations' do
+    describe '#required?' do
+      it 'is true when the compound declares required: true' do
+        expect(schema.required?(:required_compound)).to be true
+      end
+
+      it 'is true when a minimum cardinality of 1 is declared (m3/flexible)' do
+        expect(schema.required?(:cardinality_compound)).to be true
+      end
+
+      it 'is false for an optional compound' do
+        expect(schema.required?(:relationships)).to be false
+      end
+
+      it 'is false for a non-compound attribute' do
+        expect(schema.required?(:title)).to be false
+      end
+    end
+
+    describe '#required_subfield_keys' do
+      it 'returns the sub-fields declared required: true' do
+        expect(schema.required_subfield_keys(:required_compound)).to eq(%w[item kind])
+      end
+
+      it 'is empty when no sub-field is required' do
+        expect(schema.required_subfield_keys(:relationships)).to eq([])
+      end
+
+      it 'is empty for a non-compound' do
+        expect(schema.required_subfield_keys(:title)).to eq([])
+      end
+    end
+
+    it 'records required on the definition (subfield + compound level)' do
+      definition = schema.definition_for(:required_compound)
+      expect(definition[:required]).to be true
+      expect(definition[:subfields]['item'][:required]).to be true
+      expect(definition[:subfields]['note'][:required]).to be false
+    end
+  end
+
   describe '#compound?' do
     it 'is true for a declared compound' do
       expect(schema.compound?(:contributors)).to be true
@@ -116,10 +176,10 @@ def self.name
     it 'normalizes subfields with type, authority, index_keys and display' do
       definition = schema.definition_for(:contributors)
       expect(definition[:subfields]['role_label'])
-        .to eq(type: 'controlled', authority: 'contributor_role', values: nil, index_keys: [], display: false)
+        .to eq(type: 'controlled', authority: 'contributor_role', values: nil, index_keys: [], display: false, required: false)
       expect(definition[:subfields]['given_name'])
         .to eq(type: 'string', authority: nil, values: nil,
-               index_keys: %w[contributors_given_name_sim contributors_given_name_tesim], display: true)
+               index_keys: %w[contributors_given_name_sim contributors_given_name_tesim], display: true, required: false)
     end
 
     it 'reads per-sub-field index_keys (literal Solr field names)' do
@@ -158,7 +218,8 @@ def self.name
   describe '.for' do
     it 'builds from a resource instance' do
       expect(described_class.for(resource_class.new).compound_names)
-        .to contain_exactly(:contributors, :identifiers, :agent, :relationships)
+        .to contain_exactly(:contributors, :identifiers, :agent, :relationships,
+                            :required_compound, :cardinality_compound)
     end
   end
 end
diff --git a/spec/validators/hyrax/compound_entry_validator_spec.rb b/spec/validators/hyrax/compound_entry_validator_spec.rb
new file mode 100644
index 0000000000..c9760a0799
--- /dev/null
+++ b/spec/validators/hyrax/compound_entry_validator_spec.rb
@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+RSpec.describe Hyrax::CompoundEntryValidator do
+  let(:record_class) do
+    Class.new do
+      include ActiveModel::Validations
+      attr_accessor :relationships
+      validates_with Hyrax::CompoundEntryValidator
+    end
+  end
+  let(:record) { record_class.new.tap { |r| r.relationships = entries } }
+  let(:entries) { [] }
+
+  # A schema with one required-sub-field compound (`relationships`), optional
+  # at the compound level.
+  let(:definition) do
+    { required: false,
+      subfields: { 'related_item' => { type: 'work_or_url', required: true },
+                   'relationship_type' => { type: 'controlled', required: true } } }
+  end
+  let(:schema) { instance_double(Hyrax::CompoundSchema, definitions: { relationships: definition }) }
+
+  before do
+    allow(Hyrax.config).to receive(:compound_metadata_enabled?).and_return(true)
+    allow(Hyrax::CompoundSchema).to receive(:for).and_return(schema)
+  end
+
+  # Compound errors are attached to :base (so the work and collection forms,
+  # which render errors differently, both show them cleanly), and the message
+  # names the compound.
+  context 'when the feature is disabled' do
+    let(:entries) { [{ 'related_item' => 'x' }] } # would otherwise be invalid
+    before { allow(Hyrax.config).to receive(:compound_metadata_enabled?).and_return(false) }
+
+    it 'does not validate' do
+      record.valid?
+      expect(record.errors[:base]).to be_empty
+    end
+  end
+
+  context 'with no rows (optional compound)' do
+    it 'is valid' do
+      record.valid?
+      expect(record.errors[:base]).to be_empty
+    end
+  end
+
+  context 'with a complete row' do
+    let(:entries) { [{ 'related_item' => 'work-1', 'relationship_type' => 'References' }] }
+
+    it 'is valid' do
+      record.valid?
+      expect(record.errors[:base]).to be_empty
+    end
+  end
+
+  context 'with a row missing a required sub-field' do
+    let(:entries) { [{ 'related_item' => 'work-1' }] }
+
+    it 'adds one base error' do
+      record.valid?
+      expect(record.errors[:base].size).to eq(1)
+    end
+
+    it 'names the compound and the missing sub-field in the message' do
+      record.valid?
+      expect(record.errors[:base].first).to include('Relationships').and include('Relationship type')
+    end
+  end
+
+  context 'when the compound itself is required' do
+    let(:definition) { super().merge(required: true) }
+
+    context 'and empty' do
+      it 'flags the empty compound by name' do
+        record.valid?
+        expect(record.errors[:base].first).to include('Relationships').and include('at least one entry')
+      end
+    end
+
+    context 'and populated completely' do
+      let(:entries) { [{ 'related_item' => 'work-1', 'relationship_type' => 'References' }] }
+
+      it 'is valid' do
+        record.valid?
+        expect(record.errors[:base]).to be_empty
+      end
+    end
+  end
+
+  context 'when the record does not respond to the compound reader' do
+    let(:record) do
+      Class.new do
+        include ActiveModel::Validations
+        validates_with Hyrax::CompoundEntryValidator
+      end.new
+    end
+
+    it 'skips it without error' do
+      expect { record.valid? }.not_to raise_error
+    end
+  end
+end

From bb0ca4942689ace0c083535b99bba46477f0ac34 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 19:30:31 -0400
Subject: [PATCH 10/32] Resolve compound card schema from Solr doc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Compound metadata cards now render on show pages in flexible mode. The
card helpers resolved the compound declarations from the resource class,
but in flexible mode the class carries none — they are applied per
instance at load — so no cards appeared. They now resolve from the show
document's indexed schema_version, reading that version's attributes
without loading the resource; non-flexible mode still reads the class.

Also corrects a collection-controller spec that doubled the form errors
object with a class lacking full_messages, matching the real Reform
errors object the controller now reads.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app/helpers/hyrax/compound_fields_helper.rb   | 30 +++++-----
 app/services/hyrax/compound_schema.rb         | 60 ++++++++++++++++---
 .../dashboard/collections_controller_spec.rb  | 16 +++--
 .../hyrax/compound_fields_helper_spec.rb      | 20 ++-----
 spec/services/hyrax/compound_schema_spec.rb   | 39 ++++++++++++
 5 files changed, 120 insertions(+), 45 deletions(-)

diff --git a/app/helpers/hyrax/compound_fields_helper.rb b/app/helpers/hyrax/compound_fields_helper.rb
index a1a80ec7db..8ea7a5b305 100644
--- a/app/helpers/hyrax/compound_fields_helper.rb
+++ b/app/helpers/hyrax/compound_fields_helper.rb
@@ -27,9 +27,7 @@ def render_compound_field(f, compound_name)
     #   (`view: { display: card }`). Show views use this to skip card compounds
     #   in the inline metadata list.
     def compound_card_field?(presenter, field)
-      klass = compound_resource_class_for(presenter)
-      return false unless klass
-      Hyrax::CompoundSchema.for(klass).card?(field)
+      compound_schema_for(presenter).card?(field)
     rescue StandardError
       false
     end
@@ -41,10 +39,7 @@ def compound_card_field?(presenter, field)
     # @param [Object] presenter a work or collection show presenter
     # @return [ActiveSupport::SafeBuffer]
     def render_compound_cards(presenter)
-      klass = compound_resource_class_for(presenter)
-      return ''.html_safe unless klass
-
-      safe_join(Hyrax::CompoundSchema.for(klass).card_compound_names.map do |name|
+      safe_join(compound_schema_for(presenter).card_compound_names.map do |name|
         next ''.html_safe unless presenter.respond_to?(name) && presenter.public_send(name).present?
 
         render 'hyrax/compounds/compound_card', presenter: presenter, field: name
@@ -54,14 +49,19 @@ def render_compound_cards(presenter)
       ''.html_safe
     end
 
-    # The resource class for a show presenter, to read its compound schema.
-    # Works and collections resolve it differently.
-    def compound_resource_class_for(presenter)
-      if presenter.respond_to?(:solr_document) && presenter.solr_document.respond_to?(:hydra_model)
-        presenter.solr_document.hydra_model
-      elsif presenter.is_a?(Hyrax::CollectionPresenter)
-        Hyrax.config.collection_class
-      end
+    # The compound schema for a show presenter, resolved from the backing Solr
+    # document so it works in flexible mode (where the class carries no
+    # compounds). Memoized per request. See {Hyrax::CompoundSchema.for_solr_document}.
+    def compound_schema_for(presenter)
+      @compound_schemas ||= {}
+      @compound_schemas[presenter.object_id] ||=
+        if presenter.respond_to?(:solr_document) && presenter.solr_document.respond_to?(:hydra_model)
+          Hyrax::CompoundSchema.for_solr_document(presenter.solr_document)
+        elsif presenter.is_a?(Hyrax::CollectionPresenter)
+          Hyrax::CompoundSchema.for(Hyrax.config.collection_class)
+        else
+          Hyrax::CompoundSchema.new
+        end
     end
 
     ##
diff --git a/app/services/hyrax/compound_schema.rb b/app/services/hyrax/compound_schema.rb
index fbdcec56ed..e1f89f3650 100644
--- a/app/services/hyrax/compound_schema.rb
+++ b/app/services/hyrax/compound_schema.rb
@@ -23,6 +23,43 @@ def self.for(resource)
       new(*schema_sources_for(resource))
     end
 
+    ##
+    # Build a CompoundSchema for a show-page Solr document. In flexible mode the
+    # resource class carries no compounds (they are applied per-instance at
+    # load), so resolve them from the document's indexed `schema_version`
+    # without loading the resource; fall back to the model class (non-flexible).
+    #
+    # @param document [#hydra_model] a SolrDocument-like object
+    def self.for_solr_document(document)
+      new(*solr_document_schema_sources(document))
+    end
+
+    def self.solr_document_schema_sources(document)
+      klass = document.hydra_model if document.respond_to?(:hydra_model)
+      version = document['schema_version_ssi'] if document.respond_to?(:[])
+
+      if klass && version.present?
+        attrs = flexible_attributes_for(klass, version)
+        return [attrs] if attrs.present?
+      end
+
+      schema_sources_for(klass)
+    rescue StandardError => e
+      Hyrax.logger.debug("CompoundSchema.for_solr_document: #{e.message}")
+      []
+    end
+    private_class_method :solr_document_schema_sources
+
+    # The `{ name => dry_type }` attribute map for a class at a flexible schema
+    # version; nil when the loader is unavailable (non-flexible installs).
+    def self.flexible_attributes_for(klass, version)
+      loader = Hyrax::Schema.m3_schema_loader
+      loader.attributes_for(schema: klass.name, version: version, contexts: [])
+    rescue StandardError
+      nil
+    end
+    private_class_method :flexible_attributes_for
+
     # For a class, its own schema. For an instance, both the class schema
     # (non-flexible) and the singleton schema (flexible: the m3 attributes are
     # applied to the singleton at load time). Unioning both makes {.for} work in
@@ -129,14 +166,8 @@ def definitions
 
     def build_definitions
       schema_sources.each_with_object({}) do |schema, memo|
-        next unless schema.respond_to?(:each)
-
-        schema.each do |property|
-          meta = property.respond_to?(:meta) ? property.meta : nil
-          next if meta.nil?
-
-          name = property.name.to_sym
-          next if memo.key?(name)
+        name_meta_pairs(schema).each do |name, meta|
+          next if meta.nil? || memo.key?(name)
 
           config = meta.with_indifferent_access
           subfields = config['subfields']
@@ -147,6 +178,19 @@ def build_definitions
       end
     end
 
+    # `[name, meta]` pairs for a schema source, which is either a Dry schema (an
+    # iterable of properties with `name`/`meta`) or a `{ name => dry_type }` Hash
+    # (the `SchemaLoader#attributes_for` output used for version resolution).
+    def name_meta_pairs(schema)
+      if schema.is_a?(::Hash)
+        schema.map { |name, type| [name.to_sym, (type.meta if type.respond_to?(:meta))] }
+      elsif schema.respond_to?(:each)
+        schema.map { |property| [property.name.to_sym, (property.meta if property.respond_to?(:meta))] }
+      else
+        []
+      end
+    end
+
     # Normalizes the raw declaration into the symbol-keyed shape the form,
     # indexer, and renderer consume. See documentation/forms/compound_fields.md
     # for the meaning of each sub-field key.
diff --git a/spec/controllers/hyrax/dashboard/collections_controller_spec.rb b/spec/controllers/hyrax/dashboard/collections_controller_spec.rb
index da829a1722..0a89d667a6 100644
--- a/spec/controllers/hyrax/dashboard/collections_controller_spec.rb
+++ b/spec/controllers/hyrax/dashboard/collections_controller_spec.rb
@@ -231,9 +231,11 @@
 
           context "in validations" do
             let(:form) { instance_double(Hyrax::Forms::PcdmCollectionForm, errors: errors) }
-            let(:errors) { instance_double(Reform::Contract::CustomError, messages: messages) }
-            let(:messages) { { publisher: ["must exist"] } }
-            let(:errmsg) { "publisher must exist" }
+            # Plain double: a real Reform form's errors responds to full_messages,
+            # but Reform::Contract::CustomError (what instance_double would verify) does not.
+            let(:errors) { double("errors", full_messages: full_messages) }
+            let(:full_messages) { ["Publisher must exist"] }
+            let(:errmsg) { "Publisher must exist" }
 
             before do
               skip("these validations only apply to Valkyrie forms") if
@@ -459,9 +461,11 @@
 
           context "in validations" do
             let(:form) { instance_double(Hyrax::Forms::PcdmCollectionForm, errors: errors) }
-            let(:errors) { instance_double(Reform::Contract::CustomError, messages: messages) }
-            let(:messages) { { publisher: ["must exist"] } }
-            let(:errmsg) { "publisher must exist" }
+            # Plain double: a real Reform form's errors responds to full_messages,
+            # but Reform::Contract::CustomError (what instance_double would verify) does not.
+            let(:errors) { double("errors", full_messages: full_messages) }
+            let(:full_messages) { ["Publisher must exist"] }
+            let(:errmsg) { "Publisher must exist" }
 
             before do
               skip("these validations only apply to Valkyrie forms") if
diff --git a/spec/helpers/hyrax/compound_fields_helper_spec.rb b/spec/helpers/hyrax/compound_fields_helper_spec.rb
index 1febbe5cbe..097bcf4485 100644
--- a/spec/helpers/hyrax/compound_fields_helper_spec.rb
+++ b/spec/helpers/hyrax/compound_fields_helper_spec.rb
@@ -52,26 +52,14 @@
                       card_compound_names: [:relationships])
     end
 
+    # Show presenters resolve their compound schema from the backing Solr
+    # document (so flexible mode works), so stub that resolution path.
     before do
-      allow(Hyrax::CompoundSchema).to receive(:for).and_return(schema)
+      allow(Hyrax::CompoundSchema).to receive(:for_solr_document).and_return(schema)
       allow(schema).to receive(:card?).with(:relationships).and_return(true)
       allow(schema).to receive(:card?).with(:contributors).and_return(false)
     end
 
-    describe '#compound_resource_class_for' do
-      it 'uses the work hydra_model for a work presenter' do
-        solr_document = instance_double(SolrDocument, hydra_model: GenericWork)
-        presenter = instance_double(Hyrax::WorkShowPresenter, solr_document: solr_document)
-        allow(presenter).to receive(:respond_to?).with(:solr_document).and_return(true)
-        expect(helper.compound_resource_class_for(presenter)).to eq(GenericWork)
-      end
-
-      it 'uses the configured collection class for a collection presenter' do
-        presenter = Hyrax::CollectionPresenter.allocate
-        expect(helper.compound_resource_class_for(presenter)).to eq(Hyrax.config.collection_class)
-      end
-    end
-
     describe '#compound_card_field?' do
       let(:solr_document) { instance_double(SolrDocument, hydra_model: GenericWork) }
       let(:presenter) do
@@ -88,7 +76,7 @@
         expect(helper.compound_card_field?(presenter, :contributors)).to be false
       end
 
-      it 'is false (not raising) when the resource class cannot be resolved' do
+      it 'is false (not raising) when the schema cannot be resolved' do
         expect(helper.compound_card_field?(Object.new, :relationships)).to be false
       end
     end
diff --git a/spec/services/hyrax/compound_schema_spec.rb b/spec/services/hyrax/compound_schema_spec.rb
index 4625f1e5f3..2848bee7a0 100644
--- a/spec/services/hyrax/compound_schema_spec.rb
+++ b/spec/services/hyrax/compound_schema_spec.rb
@@ -222,4 +222,43 @@ def self.name
                             :required_compound, :cardinality_compound)
     end
   end
+
+  describe '.for_solr_document' do
+    # The attribute map a flexible schema loader returns for a version:
+    # `{ name => dry_type_with_meta }` — the same shape SchemaLoader#attributes_for
+    # produces. Show pages resolve compounds from this (via schema_version)
+    # without loading the resource.
+    let(:version_attributes) do
+      resource_class.schema.index_by(&:name)
+    end
+
+    context 'in flexible mode (document has a schema_version)' do
+      let(:document) { instance_double(SolrDocument, hydra_model: resource_class) }
+
+      before do
+        allow(document).to receive(:[]).with('schema_version_ssi').and_return('7')
+        loader = instance_double(Hyrax::M3SchemaLoader)
+        allow(Hyrax::Schema).to receive(:m3_schema_loader).and_return(loader)
+        allow(loader).to receive(:attributes_for)
+          .with(schema: 'TestResourceWithCompounds', version: '7', contexts: [])
+          .and_return(version_attributes)
+      end
+
+      it 'resolves compounds from the version attribute map (no resource load)' do
+        expect(described_class.for_solr_document(document).card_compound_names)
+          .to contain_exactly(:relationships)
+      end
+    end
+
+    context 'when the document has no schema_version (non-flexible)' do
+      let(:document) { instance_double(SolrDocument, hydra_model: resource_class) }
+
+      before { allow(document).to receive(:[]).with('schema_version_ssi').and_return(nil) }
+
+      it 'falls back to the model class schema' do
+        expect(described_class.for_solr_document(document).compound_names)
+          .to include(:relationships, :agent)
+      end
+    end
+  end
 end

From 70cc1719a27bf5b230807662d55855027df32d28 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 19:59:08 -0400
Subject: [PATCH 11/32] Show collection compounds in flexible mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Inline compound metadata (e.g. agents, identifiers) now appears on a
collection's show page in flexible mode. The presenter resolved its
displayed terms and compound readers from the collection class, but a
flexible schema is per-resource — keyed by the document's indexed
schema_version and mutable at runtime — so the class often carries
none. It now resolves them from the backing document, the same way the
compound cards already do.
---
 app/presenters/hyrax/collection_presenter.rb  | 56 +++++++++++++------
 .../hyrax/collection_presenter_spec.rb        | 48 ++++++++--------
 2 files changed, 63 insertions(+), 41 deletions(-)

diff --git a/app/presenters/hyrax/collection_presenter.rb b/app/presenters/hyrax/collection_presenter.rb
index cf1046a0fc..d5a4f980e7 100644
--- a/app/presenters/hyrax/collection_presenter.rb
+++ b/app/presenters/hyrax/collection_presenter.rb
@@ -40,38 +40,51 @@ def collection_type
              :title_or_label, :collection_type_gid, :create_date, :modified_date, :visibility, :edit_groups, :edit_people,
              to: :solr_document
 
-    # Terms is the list of fields displayed by
-    # app/views/collections/_show_descriptions.html.erb
+    # The standard metadata terms displayed by
+    # app/views/collections/_show_descriptions.html.erb. Compound terms are
+    # appended per instance (see {#terms}); they can't be resolved at the class
+    # level because a flexible schema is per-resource (keyed by the indexed
+    # schema_version) and mutable at runtime.
+    DEFAULT_TERMS = [:total_items, :alternative_title, :size, :resource_type, :creator, :contributor,
+                     :keyword, :license, :publisher, :date_created, :subject, :language, :identifier,
+                     :based_near, :related_url].freeze
+
+    # @deprecated kept for backward compatibility; the standard terms only. Use
+    #   the instance {#terms} to include this collection's compound terms.
     def self.terms
-      [:total_items, :alternative_title, :size, :resource_type, :creator, :contributor, :keyword, :license, :publisher, :date_created, :subject,
-       :language, :identifier, :based_near, :related_url] + compound_terms
+      DEFAULT_TERMS.dup
     end
 
-    # Compound terms that render inline in the collection metadata list. Card
-    # compounds are excluded (they render via `render_compound_cards`). See
-    # documentation/forms/compound_fields.md.
-    def self.compound_terms
-      return [] unless Hyrax.config.compound_metadata_enabled?
-      Hyrax::CompoundSchema.for(Hyrax.config.collection_class).inline_compound_names
-    rescue StandardError
-      []
+    # This collection's displayed terms: the standard terms plus its inline
+    # compound terms, resolved from the backing document so it is correct in
+    # flexible mode.
+    def terms
+      DEFAULT_TERMS + compound_terms
     end
 
     def terms_with_values
-      self.class.terms.select { |t| self[t].present? }
+      terms.select { |t| self[t].present? }
     end
 
+    # Inline compound terms for this collection (card compounds render
+    # separately via `render_compound_cards`). Resolved from the backing
+    # document. See documentation/forms/compound_fields.md.
     def compound_terms
-      self.class.compound_terms
+      return [] unless Hyrax.config.compound_metadata_enabled?
+      compound_schema.inline_compound_names
+    rescue StandardError
+      []
     end
 
     def compound_term?(term)
       compound_terms.include?(term.to_sym)
     end
 
-    def self.all_compound_names
+    # All compound names (inline + card) declared for this collection, used to
+    # delegate the readers to the solr document below.
+    def all_compound_names
       return [] unless Hyrax.config.compound_metadata_enabled?
-      Hyrax::CompoundSchema.for(Hyrax.config.collection_class).compound_names
+      compound_schema.compound_names
     rescue StandardError
       []
     end
@@ -80,14 +93,21 @@ def self.all_compound_names
     # resolves on a collection as on a work. Via method_missing because the
     # compound set is schema-driven, not known at class-definition time.
     def respond_to_missing?(name, include_private = false)
-      self.class.all_compound_names.include?(name.to_sym) || super
+      all_compound_names.include?(name.to_sym) || super
     end
 
     def method_missing(name, *args, &block)
-      return solr_document.send(name, *args, &block) if self.class.all_compound_names.include?(name.to_sym)
+      return solr_document.send(name, *args, &block) if all_compound_names.include?(name.to_sym)
       super
     end
 
+    # The compound schema for this collection, resolved from the backing Solr
+    # document (so it reflects the resource's own schema_version in flexible
+    # mode, rather than an empty or stale class-level schema). Memoized.
+    def compound_schema
+      @compound_schema ||= Hyrax::CompoundSchema.for_solr_document(solr_document)
+    end
+
     ##
     # @param [Symbol] key
     # @return [Object]
diff --git a/spec/presenters/hyrax/collection_presenter_spec.rb b/spec/presenters/hyrax/collection_presenter_spec.rb
index 9c69cf31c1..2c18818651 100644
--- a/spec/presenters/hyrax/collection_presenter_spec.rb
+++ b/spec/presenters/hyrax/collection_presenter_spec.rb
@@ -18,40 +18,42 @@
   it { is_expected.to delegate_method(:date_created).to(:solr_document) }
 
   describe ".terms" do
+    # The class method is the default terms only; compound terms are resolved
+    # per instance (see "#terms") because a flexible schema is per-resource.
     subject { described_class.terms }
 
-    context 'with compound metadata disabled' do
-      before { allow(Hyrax.config).to receive(:compound_metadata_enabled?).and_return(false) }
+    it 'is the default terms' do
+      is_expected.to eq [:total_items, :alternative_title, :size, :resource_type, :creator,
+                         :contributor, :keyword, :license, :publisher,
+                         :date_created, :subject, :language, :identifier,
+                         :based_near, :related_url]
+    end
+  end
 
-      it do
-        is_expected.to eq [:total_items, :alternative_title, :size, :resource_type, :creator,
-                           :contributor, :keyword, :license, :publisher,
-                           :date_created, :subject, :language, :identifier,
-                           :based_near, :related_url]
-      end
+  describe "#terms" do
+    it 'starts with the default terms' do
+      expect(presenter.terms.first(15)).to eq described_class::DEFAULT_TERMS
     end
 
-    it 'starts with the base scalar terms' do
-      expect(subject.first(15)).to eq [:total_items, :alternative_title, :size, :resource_type, :creator,
-                                       :contributor, :keyword, :license, :publisher,
-                                       :date_created, :subject, :language, :identifier,
-                                       :based_near, :related_url]
+    it 'appends this collection\'s inline compound terms' do
+      allow(presenter).to receive(:compound_terms).and_return([:agents, :identifiers])
+      expect(presenter.terms).to end_with(:agents, :identifiers)
     end
 
-    it 'appends compound terms declared on the collection model when enabled' do
-      compound_terms = described_class.compound_terms
-      # Under a flexible-mode stack the collection class composition is fixed at
-      # boot, so the shipped compounds are only present when the active flex
-      # schema declares them; guard rather than assert an empty splat.
-      skip 'no compound terms declared on the collection class in this configuration' if compound_terms.empty?
-      expect(subject).to include(*compound_terms)
+    context 'with compound metadata disabled' do
+      before { allow(Hyrax.config).to receive(:compound_metadata_enabled?).and_return(false) }
+
+      it 'is the default terms only' do
+        expect(presenter.terms).to eq described_class::DEFAULT_TERMS
+      end
     end
   end
 
   describe "compound attribute delegation" do
-    context "when a compound is declared on the collection model" do
+    # Resolution is per instance, from the backing document's compound schema.
+    context "when a compound is declared for the collection" do
       before do
-        allow(described_class).to receive(:all_compound_names).and_return([:relationships])
+        allow(presenter).to receive(:all_compound_names).and_return([:relationships])
         allow(solr_doc).to receive(:relationships).and_return([{ 'related_item' => 'https://example.org' }])
       end
 
@@ -65,7 +67,7 @@
     end
 
     context "for an undeclared method" do
-      before { allow(described_class).to receive(:all_compound_names).and_return([]) }
+      before { allow(presenter).to receive(:all_compound_names).and_return([]) }
 
       it "does not respond to it" do
         expect(presenter).not_to respond_to(:not_a_compound)

From c3417801ab835762368352e275f3b5f5b92bb089 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 20:11:01 -0400
Subject: [PATCH 12/32] Build collection terms on the class term list

The instance term list now derives from the class-level terms plus the
collection's compound terms, instead of a hardcoded constant. This
restores the effect of a downstream override of the class `terms`
method (e.g. one that removes a term), which the previous instance
implementation bypassed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app/presenters/hyrax/collection_presenter.rb | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/app/presenters/hyrax/collection_presenter.rb b/app/presenters/hyrax/collection_presenter.rb
index d5a4f980e7..9837fc10e2 100644
--- a/app/presenters/hyrax/collection_presenter.rb
+++ b/app/presenters/hyrax/collection_presenter.rb
@@ -49,17 +49,18 @@ def collection_type
                      :keyword, :license, :publisher, :date_created, :subject, :language, :identifier,
                      :based_near, :related_url].freeze
 
-    # @deprecated kept for backward compatibility; the standard terms only. Use
-    #   the instance {#terms} to include this collection's compound terms.
+    # The standard (non-compound) terms. Class-level so downstream apps can
+    # override the list (e.g. to remove a term); the instance {#terms} builds on
+    # this and appends the per-resource compound terms.
     def self.terms
       DEFAULT_TERMS.dup
     end
 
-    # This collection's displayed terms: the standard terms plus its inline
-    # compound terms, resolved from the backing document so it is correct in
-    # flexible mode.
+    # This collection's displayed terms: the class-level standard terms (honoring
+    # any downstream override) plus its inline compound terms, which are resolved
+    # from the backing document so they are correct in flexible mode.
     def terms
-      DEFAULT_TERMS + compound_terms
+      self.class.terms + compound_terms
     end
 
     def terms_with_values

From 18777a1190ec009ba86d27cf290c35be29331d97 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 20:22:11 -0400
Subject: [PATCH 13/32] Fix compound card display in flexible mode

Three fixes for compound cards on show pages:

- Sub-field specs now resolve from the backing document, not the class,
  so in flexible mode a card's controlled terms display their labels and
  a work-or-url value links correctly (the class carries no compounds in
  flexible mode, so the renderer was getting raw values).
- A work-or-url value that is neither a URL nor a resolvable indexed work
  now renders as plain text instead of a broken link.
- Compound values sit flush with the value column instead of carrying a
  fixed indent that misaligned under downstream layouts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../stylesheets/hyrax/_compound_metadata.scss |  7 +++--
 app/presenters/hyrax/presents_attributes.rb   |  9 ++++--
 .../renderers/compound_attribute_renderer.rb  | 13 +++++----
 app/services/hyrax/compound_work_resolver.rb  | 28 +++++++++++++++++--
 .../compound_attribute_renderer_spec.rb       | 17 +++++++++--
 .../hyrax/compound_work_resolver_spec.rb      | 20 +++++++++++++
 6 files changed, 77 insertions(+), 17 deletions(-)

diff --git a/app/assets/stylesheets/hyrax/_compound_metadata.scss b/app/assets/stylesheets/hyrax/_compound_metadata.scss
index d162a87976..1f46da0218 100644
--- a/app/assets/stylesheets/hyrax/_compound_metadata.scss
+++ b/app/assets/stylesheets/hyrax/_compound_metadata.scss
@@ -9,9 +9,10 @@
   display: block !important;
   flex-direction: column;
   border: 0 !important;
-  // Indent to align with scalar metadata values (their `ul.tabular` keeps the
-  // browser default ~40px list padding).
-  padding: 0 0 0 40px !important;
+  // Sit flush with the value column. No indent of our own: scalar values get
+  // theirs from a `ul.tabular` wrapper that apps and themes style differently,
+  // so a fixed pad here would misalign in some of them.
+  padding: 0 !important;
   max-width: 100%;
 
   // Force block flow on the entries/sub-fields; the label/value spans stay
diff --git a/app/presenters/hyrax/presents_attributes.rb b/app/presenters/hyrax/presents_attributes.rb
index ed165b8e38..7f35f546cb 100644
--- a/app/presenters/hyrax/presents_attributes.rb
+++ b/app/presenters/hyrax/presents_attributes.rb
@@ -52,9 +52,12 @@ def microdata_type_to_html
     # controlled ids to their terms; nil if the resource class can't be
     # resolved (the renderer then renders raw values).
     def compound_subfields_for(field)
-      klass = solr_document.try(:hydra_model) if respond_to?(:solr_document)
-      return nil unless klass
-      Hyrax::CompoundSchema.for(klass).definition_for(field)&.fetch(:subfields, nil)
+      return nil unless respond_to?(:solr_document) && solr_document.respond_to?(:hydra_model)
+      # Resolve from the backing document, not the class: in flexible mode the
+      # class carries no compounds, so a class lookup would drop the sub-field
+      # specs and the renderer would fall back to raw (unlinked, untranslated)
+      # values.
+      Hyrax::CompoundSchema.for_solr_document(solr_document).definition_for(field)&.fetch(:subfields, nil)
     rescue StandardError => e
       Hyrax.logger.debug("compound_subfields_for(#{field}): #{e.message}")
       nil
diff --git a/app/renderers/hyrax/renderers/compound_attribute_renderer.rb b/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
index cdbc8718e3..f19b2fae10 100644
--- a/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
+++ b/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
@@ -75,13 +75,14 @@ def value_markup(sub_field, value)
         end
       end
 
+      # Link a URL or a resolvable work; render anything else as plain text so
+      # we never emit a broken link to a non-existent work.
       def work_or_url_markup(value)
-        if Hyrax::CompoundWorkResolver.url?(value)
-          auto_link(ERB::Util.h(value.to_s))
-        else
-          title, path = Hyrax::CompoundWorkResolver.title_and_path(value)
-          link_to(ERB::Util.h(title), path)
-        end
+        return auto_link(ERB::Util.h(value.to_s)) if Hyrax::CompoundWorkResolver.url?(value)
+
+        title, path = Hyrax::CompoundWorkResolver.resolve(value)
+        return ERB::Util.h(value.to_s) if title.nil?
+        link_to(ERB::Util.h(title), path)
       end
 
       def display_value(sub_field, value)
diff --git a/app/services/hyrax/compound_work_resolver.rb b/app/services/hyrax/compound_work_resolver.rb
index 519e82c3df..f25235b94f 100644
--- a/app/services/hyrax/compound_work_resolver.rb
+++ b/app/services/hyrax/compound_work_resolver.rb
@@ -22,13 +22,35 @@ def self.title_and_path(id)
       [title_for(id), path_for(id)]
     end
 
+    ##
+    # Resolve an internal work id to its display title and show path, but only
+    # when a matching work is actually indexed. Returns nil when nothing
+    # matches, so callers can render a bare, unlinked value rather than a broken
+    # link to a non-existent work.
+    #
+    # @param id [String]
+    # @return [Array(String, String), nil] `[title, path]`, or nil when unresolved
+    def self.resolve(id)
+      title = indexed_title_for(id)
+      return nil if title.nil?
+      [title, path_for(id)]
+    end
+
     def self.title_for(id)
+      indexed_title_for(id) || id.to_s
+    end
+
+    # The indexed title for a work id, or nil when no such work is indexed
+    # (distinguishes "resolved to a real work" from "no match").
+    def self.indexed_title_for(id)
       doc = Hyrax::SolrService.query("{!field f=id}#{id}", fl: 'title_tesim', rows: 1).first
-      Array(doc&.fetch('title_tesim', nil)).first.presence || id.to_s
+      return nil if doc.nil?
+      Array(doc['title_tesim']).first.presence || id.to_s
     rescue StandardError => e
-      Hyrax.logger.debug("CompoundWorkResolver.title_for(#{id}): #{e.message}")
-      id.to_s
+      Hyrax.logger.debug("CompoundWorkResolver.indexed_title_for(#{id}): #{e.message}")
+      nil
     end
+    private_class_method :indexed_title_for
 
     # The model-agnostic Blacklight show route (`/catalog/:id`) links any
     # indexed work without knowing its class.
diff --git a/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb b/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
index f2b04e88e9..d95811f1f7 100644
--- a/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
+++ b/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
@@ -113,12 +113,12 @@
       end
     end
 
-    context 'when the value is an internal work id' do
+    context 'when the value resolves to an indexed work' do
       let(:values) { [{ 'related_item' => 'work-123' }] }
       let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subfields: subfields) }
 
       before do
-        allow(Hyrax::CompoundWorkResolver).to receive(:title_and_path)
+        allow(Hyrax::CompoundWorkResolver).to receive(:resolve)
           .with('work-123').and_return(['Linked Work', '/catalog/work-123'])
       end
 
@@ -128,5 +128,18 @@
         expect(markup).to include('Linked Work')
       end
     end
+
+    context 'when the value is neither a URL nor a resolvable work' do
+      let(:values) { [{ 'related_item' => 'not-a-real-id' }] }
+      let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subfields: subfields) }
+
+      before { allow(Hyrax::CompoundWorkResolver).to receive(:resolve).with('not-a-real-id').and_return(nil) }
+
+      it 'renders the value as plain text without a link' do
+        markup = renderer.render_dl_row
+        expect(markup).to include('not-a-real-id')
+        expect(markup).not_to include('<a href')
+      end
+    end
   end
 end
diff --git a/spec/services/hyrax/compound_work_resolver_spec.rb b/spec/services/hyrax/compound_work_resolver_spec.rb
index e19deeb543..5681520ba2 100644
--- a/spec/services/hyrax/compound_work_resolver_spec.rb
+++ b/spec/services/hyrax/compound_work_resolver_spec.rb
@@ -42,4 +42,24 @@
       expect(title).to eq('work-123')
     end
   end
+
+  describe '.resolve' do
+    let(:id) { 'work-123' }
+
+    it 'returns [title, path] when a matching work is indexed' do
+      allow(Hyrax::SolrService).to receive(:query)
+        .and_return([{ 'title_tesim' => ['Resolved Title'] }])
+      expect(described_class.resolve(id)).to eq(['Resolved Title', '/catalog/work-123'])
+    end
+
+    it 'returns nil when no work matches (so the caller renders plain text)' do
+      allow(Hyrax::SolrService).to receive(:query).and_return([])
+      expect(described_class.resolve(id)).to be_nil
+    end
+
+    it 'returns nil when the Solr lookup raises' do
+      allow(Hyrax::SolrService).to receive(:query).and_raise(StandardError)
+      expect(described_class.resolve(id)).to be_nil
+    end
+  end
 end

From 62d1e9040e37c9a1d385b2092549409ec0e29b45 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 20:35:19 -0400
Subject: [PATCH 14/32] Drop duplicate label from compound cards
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A compound rendered as a card showed its label twice — once as the card
title and again as the field label inside the body. The card body now
renders the entry values only, via a new value_only option on
attribute_to_html, leaving the card title as the single label.
---
 app/presenters/hyrax/presents_attributes.rb       | 12 +++++++++---
 app/views/hyrax/compounds/_compound_card.html.erb |  7 +++----
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/app/presenters/hyrax/presents_attributes.rb b/app/presenters/hyrax/presents_attributes.rb
index 7f35f546cb..54925cb013 100644
--- a/app/presenters/hyrax/presents_attributes.rb
+++ b/app/presenters/hyrax/presents_attributes.rb
@@ -13,6 +13,9 @@ module PresentsAttributes
     # @option options [String] :label The default label for the field if no translation is found
     # @option options [TrueClass, FalseClass] :include_empty should we display a row if there are no values?
     # @option options [String] :work_type name of work type class (e.g., "GenericWork")
+    # @option options [TrueClass, FalseClass] :value_only render only the value
+    #   markup, without the field-label row — used by compound cards, which
+    #   already show the label as the card title.
     def attribute_to_html(field, options = {})
       unless respond_to?(field)
         Hyrax.logger.warn("#{self.class} attempted to render #{field}, but no method exists with that name.")
@@ -20,11 +23,14 @@ def attribute_to_html(field, options = {})
       end
 
       options = options.merge(subfields: compound_subfields_for(field)) if options[:render_as].to_s == 'compound'
+      renderer = renderer_for(field, options).new(field, send(field), options)
 
-      if options[:html_dl]
-        renderer_for(field, options).new(field, send(field), options).render_dl_row
+      if options[:value_only] && renderer.respond_to?(:render_value)
+        renderer.render_value
+      elsif options[:html_dl]
+        renderer.render_dl_row
       else
-        renderer_for(field, options).new(field, send(field), options).render
+        renderer.render
       end
     end
 
diff --git a/app/views/hyrax/compounds/_compound_card.html.erb b/app/views/hyrax/compounds/_compound_card.html.erb
index 05ad41c465..337600000f 100644
--- a/app/views/hyrax/compounds/_compound_card.html.erb
+++ b/app/views/hyrax/compounds/_compound_card.html.erb
@@ -12,9 +12,8 @@
     <h2 class="card-title"><%= compound_field_label(field) %></h2>
   </div>
   <div class="card-body">
-    <dl class="work-show">
-      <%= presenter.attribute_to_html(field.to_sym, render_as: :compound, html_dl: true,
-                                      label: compound_field_label(field)) %>
-    </dl>
+    <%# value_only: the compound's label is already the card title above, so
+        render just the entries (no duplicate field label). %>
+    <%= presenter.attribute_to_html(field.to_sym, render_as: :compound, value_only: true) %>
   </div>
 </div>

From ff1b7e90164a5a5cad0130de3f5e7f87309f4648 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 22:18:59 -0400
Subject: [PATCH 15/32] Align collection metadata values past long URLs

A long unbreakable value such as a rights-statement or license URL link
was shrinking the flex label column and shifting the value column left,
so compound rows no longer lined up with the rows above them. Hold the
label column fixed and let the value column shrink so long URLs wrap
within it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app/assets/stylesheets/hyrax/_collections.scss | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/app/assets/stylesheets/hyrax/_collections.scss b/app/assets/stylesheets/hyrax/_collections.scss
index 3fe27c0bff..98edae4e35 100644
--- a/app/assets/stylesheets/hyrax/_collections.scss
+++ b/app/assets/stylesheets/hyrax/_collections.scss
@@ -610,11 +610,18 @@ button.branding-banner-remove:hover {
 
     dt {
       flex-basis: 115px;
+      // Hold the label column fixed so every value column (dd) starts at the
+      // same x; otherwise a long unbreakable value (e.g. a URL link) shrinks
+      // this column and shifts the value left.
+      flex-shrink: 0;
       font-weight: bold;
     }
 
     dd {
       flex-basis: auto;
+      // Let the value column shrink to its flex space so long URLs wrap within
+      // it rather than forcing the row wider.
+      min-width: 0;
     }
 
   }

From 032264b64dddeae53aef19746d8ae7974f527fcd Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Thu, 4 Jun 2026 22:19:31 -0400
Subject: [PATCH 16/32] Improve compound metadata show rendering

- Compounds use a declared display_label, resolved the same way ordinary
  properties are (the rights sample now shows "Rights"); the card title
  uses it and no longer duplicates the field label.
- A controlled sub-field whose value is a URI (rights statement, license)
  links the term to that URI; a work-or-url value that resolves to no
  indexed work renders as plain text instead of a broken link.
- Inline compound values align with the surrounding metadata: work-page
  values share the ul.tabular wrapper, and collection values resolve
  their definition from the document so they render correctly in
  flexible mode.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../stylesheets/hyrax/_compound_metadata.scss |  3 ---
 app/helpers/hyrax/collections_helper.rb       | 19 ++++++++-------
 app/helpers/hyrax/compound_fields_helper.rb   | 24 +++++++++++++++----
 .../renderers/compound_attribute_renderer.rb  | 21 +++++++++++++++-
 app/services/hyrax/compound_schema.rb         | 11 ++++++++-
 .../hyrax/compounds/_compound_card.html.erb   |  2 +-
 config/metadata/compound_metadata.yaml        |  2 ++
 .../hyrax/compound_fields_helper_spec.rb      | 10 ++++++++
 .../compound_attribute_renderer_spec.rb       | 19 +++++++++++++++
 spec/services/hyrax/compound_schema_spec.rb   | 11 +++++++++
 10 files changed, 104 insertions(+), 18 deletions(-)

diff --git a/app/assets/stylesheets/hyrax/_compound_metadata.scss b/app/assets/stylesheets/hyrax/_compound_metadata.scss
index 1f46da0218..15e54343b7 100644
--- a/app/assets/stylesheets/hyrax/_compound_metadata.scss
+++ b/app/assets/stylesheets/hyrax/_compound_metadata.scss
@@ -9,9 +9,6 @@
   display: block !important;
   flex-direction: column;
   border: 0 !important;
-  // Sit flush with the value column. No indent of our own: scalar values get
-  // theirs from a `ul.tabular` wrapper that apps and themes style differently,
-  // so a fixed pad here would misalign in some of them.
   padding: 0 !important;
   max-width: 100%;
 
diff --git a/app/helpers/hyrax/collections_helper.rb b/app/helpers/hyrax/collections_helper.rb
index 31786029a9..6fb60d1c79 100644
--- a/app/helpers/hyrax/collections_helper.rb
+++ b/app/helpers/hyrax/collections_helper.rb
@@ -30,6 +30,11 @@ def available_parent_collections_data(collection:)
     # @since 3.0.0
     # @return [#to_s]
     def collection_metadata_label(collection, field)
+      if collection.respond_to?(:compound_term?) && collection.compound_term?(field)
+        definition = compound_schema_for(collection).definition_for(field)
+        return compound_field_label(field, display_label: definition&.fetch(:display_label, nil))
+      end
+
       Hyrax::PresenterRenderer.new(collection, self).label(field)
     end
 
@@ -37,16 +42,14 @@ def collection_metadata_label(collection, field)
     # @since 3.0.0
     # @return [#to_s]
     def collection_metadata_value(collection, field)
-      # Compounds render through the shared CompoundAttributeRenderer. The show
-      # partials already wrap label/value in <dt>/<dd>, so render only the entry
-      # rows; pass the sub-field specs so controlled ids display as their term.
-      # See documentation/forms/compound_fields.md.
+      # Compounds render through the shared CompoundAttributeRenderer, resolving
+      # the definition from the presenter's document (correct in flexible mode).
+      # Collection scalar values render as bare spans (no `ul.tabular`), so the
+      # entries render flush to match. See documentation/forms/compound_fields.md.
       if collection.respond_to?(:compound_term?) && collection.compound_term?(field)
-        definition = Hyrax::CompoundSchema.for(Hyrax.config.collection_class).definition_for(field)
+        definition = compound_schema_for(collection).definition_for(field)
         return Hyrax::Renderers::CompoundAttributeRenderer
-               .new(field, collection[field],
-                    label: collection_metadata_label(collection, field),
-                    subfields: definition&.fetch(:subfields, nil))
+               .new(field, collection[field], subfields: definition&.fetch(:subfields, nil))
                .render_value
       end
 
diff --git a/app/helpers/hyrax/compound_fields_helper.rb b/app/helpers/hyrax/compound_fields_helper.rb
index 8ea7a5b305..6e8c5f0635 100644
--- a/app/helpers/hyrax/compound_fields_helper.rb
+++ b/app/helpers/hyrax/compound_fields_helper.rb
@@ -19,7 +19,7 @@ def render_compound_field(f, compound_name)
              f: f,
              compound_name: compound_name.to_sym,
              definition: definition,
-             display_label: compound_field_label(compound_name)
+             display_label: compound_field_label(compound_name, display_label: definition[:display_label])
     end
 
     ##
@@ -100,9 +100,25 @@ def compound_work_or_url_option(value)
       [title, value.to_s]
     end
 
-    def compound_field_label(compound_name)
-      t("hyrax.compound_fields.#{compound_name}.label",
-        default: compound_name.to_s.humanize)
+    # The label for a compound. A declared `display_label` is resolved through
+    # the same path ordinary properties use ({Hyrax::AttributesHelper#conform_options});
+    # otherwise it falls back to the `hyrax.compound_fields.<name>.label` key.
+    #
+    # @param display_label [Hash, nil] the compound's `{ locale => label }` hash
+    def compound_field_label(compound_name, display_label: nil)
+      if display_label.present?
+        conform_options(compound_name.to_s, display_label: display_label)[:label]
+      else
+        t("hyrax.compound_fields.#{compound_name}.label", default: compound_name.to_s.humanize)
+      end
+    rescue StandardError
+      t("hyrax.compound_fields.#{compound_name}.label", default: compound_name.to_s.humanize)
+    end
+
+    # The card title for a compound on a show page (resolves the compound's
+    # declared display_label from the presenter's schema).
+    def compound_card_label(presenter, field)
+      compound_field_label(field, display_label: compound_schema_for(presenter).definition_for(field)&.dig(:display_label))
     end
 
     def compound_subfield_label(compound_name, sub_field)
diff --git a/app/renderers/hyrax/renderers/compound_attribute_renderer.rb b/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
index f19b2fae10..d474ef5ca5 100644
--- a/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
+++ b/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
@@ -18,7 +18,11 @@ def render
       def render_dl_row
         return '' if blank_values? && !options[:include_empty]
 
-        %(<dt>#{label}</dt>\n<dd>#{entries_markup}</dd>).html_safe
+        # Wrap in the same `ul.tabular` structure ordinary fields use, so inline
+        # compound values inherit the same indentation as the surrounding
+        # metadata (whatever an app/theme styles `ul.tabular` to) rather than a
+        # fixed pad that misaligns downstream.
+        %(<dt>#{label}</dt>\n<dd><ul class="tabular"><li class="attribute attribute-#{field}">#{entries_markup}</li></ul></dd>).html_safe
       end
 
       # Just the entry rows, without a surrounding label/row wrapper. Used by
@@ -70,11 +74,26 @@ def value_markup(sub_field, value)
           auto_link(ERB::Util.h(value.to_s))
         when 'work_or_url'
           work_or_url_markup(value)
+        when 'controlled'
+          controlled_markup(sub_field, value)
         else
           ERB::Util.h(display_value(sub_field, value))
         end
       end
 
+      # A controlled value displays its authority/value-list term. When the
+      # stored value is itself a linkable URI (e.g. a rights-statement or license
+      # URI), link the term to that URI — mirroring the ordinary rights/license
+      # renderer. Non-URI controlled values (e.g. inline option ids) stay plain.
+      def controlled_markup(sub_field, value)
+        label = display_value(sub_field, value)
+        if Hyrax::AuthorityRenderingHelper.linkable_uri?(value)
+          %(<a href="#{ERB::Util.h(value)}" target="_blank" rel="noopener noreferrer">#{ERB::Util.h(label)}</a>).html_safe
+        else
+          ERB::Util.h(label)
+        end
+      end
+
       # Link a URL or a resolvable work; render anything else as plain text so
       # we never emit a broken link to a non-existent work.
       def work_or_url_markup(value)
diff --git a/app/services/hyrax/compound_schema.rb b/app/services/hyrax/compound_schema.rb
index e1f89f3650..d45fe1ece6 100644
--- a/app/services/hyrax/compound_schema.rb
+++ b/app/services/hyrax/compound_schema.rb
@@ -203,7 +203,16 @@ def normalize(config, subfields)
       { subfields: sub,
         groups: normalize_groups(config['groups'], sub.keys),
         display_mode: display_mode,
-        required: compound_required?(config) }
+        required: compound_required?(config),
+        display_label: normalize_display_label(config) }
+    end
+
+    # The declared display label as `{ locale => String }` (the m3
+    # `display_label` shape), or nil when none is declared.
+    def normalize_display_label(config)
+      raw = config['display_label']
+      return nil if raw.blank?
+      raw.is_a?(Hash) ? raw.with_indifferent_access : { default: raw.to_s }.with_indifferent_access
     end
 
     def normalize_subfield(opts)
diff --git a/app/views/hyrax/compounds/_compound_card.html.erb b/app/views/hyrax/compounds/_compound_card.html.erb
index 337600000f..24f70ce0d1 100644
--- a/app/views/hyrax/compounds/_compound_card.html.erb
+++ b/app/views/hyrax/compounds/_compound_card.html.erb
@@ -9,7 +9,7 @@
 %>
 <div class="card hyrax-compound-card">
   <div class="card-header">
-    <h2 class="card-title"><%= compound_field_label(field) %></h2>
+    <h2 class="card-title"><%= compound_card_label(presenter, field) %></h2>
   </div>
   <div class="card-body">
     <%# value_only: the compound's label is already the card title above, so
diff --git a/config/metadata/compound_metadata.yaml b/config/metadata/compound_metadata.yaml
index 1bc6141ebe..2e4fafb90e 100644
--- a/config/metadata/compound_metadata.yaml
+++ b/config/metadata/compound_metadata.yaml
@@ -72,6 +72,8 @@ attributes:
     type: hash
     multiple: true
     predicate: http://purl.org/dc/terms/rights
+    display_label:
+      default: Rights
     form:
       primary: false
     subfields:
diff --git a/spec/helpers/hyrax/compound_fields_helper_spec.rb b/spec/helpers/hyrax/compound_fields_helper_spec.rb
index 097bcf4485..e73986d934 100644
--- a/spec/helpers/hyrax/compound_fields_helper_spec.rb
+++ b/spec/helpers/hyrax/compound_fields_helper_spec.rb
@@ -44,6 +44,16 @@
     end
   end
 
+  describe '#compound_field_label' do
+    it 'uses a declared display_label' do
+      expect(helper.compound_field_label(:compound_rights, display_label: { 'default' => 'Rights' })).to eq('Rights')
+    end
+
+    it 'falls back to a humanized name when no display_label or translation exists' do
+      expect(helper.compound_field_label(:nonexistent_compound)).to eq('Nonexistent compound')
+    end
+  end
+
   describe 'card display' do
     # A schema whose only card compound is :relationships.
     let(:schema) do
diff --git a/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb b/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
index d95811f1f7..8d505874dc 100644
--- a/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
+++ b/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
@@ -82,6 +82,25 @@
     end
   end
 
+  describe 'controlled sub-field with a linkable URI value' do
+    let(:uri) { 'http://rightsstatements.org/vocab/InC/1.0/' }
+    let(:values) { [{ 'rights_statement' => uri }] }
+    let(:subfields) do
+      { 'rights_statement' => { type: 'controlled', authority: 'rights_statements', values: nil } }
+    end
+    let(:renderer) { described_class.new(:compound_rights, values, label: 'Rights', html_dl: true, subfields: subfields) }
+
+    before do
+      allow(Hyrax::CompoundSubfieldLabeler).to receive(:label_for)
+        .with(subfields['rights_statement'], uri).and_return('In Copyright')
+    end
+
+    it 'links the resolved term to its URI' do
+      markup = renderer.render_dl_row
+      expect(markup).to include(%(<a href="#{uri}" target="_blank" rel="noopener noreferrer">In Copyright</a>))
+    end
+  end
+
   describe 'url sub-field auto-linking' do
     let(:values) { [{ 'related_item_url' => 'https://example.org/item/42', 'note' => 'see also' }] }
     let(:subfields) do
diff --git a/spec/services/hyrax/compound_schema_spec.rb b/spec/services/hyrax/compound_schema_spec.rb
index 2848bee7a0..43661427a3 100644
--- a/spec/services/hyrax/compound_schema_spec.rb
+++ b/spec/services/hyrax/compound_schema_spec.rb
@@ -40,6 +40,7 @@ def self.name
                     'related_item' => { 'type' => 'work_or_url' },
                     'relationship_type' => { 'type' => 'controlled', 'authority' => 'relationship_type' }
                   },
+                  display_label: { 'default' => 'Related works' },
                   view: { 'display' => 'card' }
                 )
       # Required at the compound level (non-flexible `required: true`) with two
@@ -110,6 +111,16 @@ def self.name
     end
   end
 
+  describe 'display_label' do
+    it 'normalizes a declared display_label to a locale hash' do
+      expect(schema.definition_for(:relationships)[:display_label]).to eq('default' => 'Related works')
+    end
+
+    it 'is nil when none is declared' do
+      expect(schema.definition_for(:contributors)[:display_label]).to be_nil
+    end
+  end
+
   describe 'required declarations' do
     describe '#required?' do
       it 'is true when the compound declares required: true' do

From d1458c078c14cc4e0c33f89d9149a262d2d6d9f9 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Fri, 5 Jun 2026 17:42:23 -0400
Subject: [PATCH 17/32] Dynamic solr doc method creation for compounds

The SolrDocument now exposes a reader for every compound in its active
schema, resolved dynamically. An application that declares its own
compounds renders them on the show page with no per-document setup.
---
 .../concerns/hyrax/solr_document/metadata.rb  | 52 +++++++++++++++++--
 documentation/forms/compound_fields.md        |  6 ++-
 2 files changed, 51 insertions(+), 7 deletions(-)

diff --git a/app/models/concerns/hyrax/solr_document/metadata.rb b/app/models/concerns/hyrax/solr_document/metadata.rb
index 2b438b631d..6c6edbd5a6 100644
--- a/app/models/concerns/hyrax/solr_document/metadata.rb
+++ b/app/models/concerns/hyrax/solr_document/metadata.rb
@@ -20,6 +20,51 @@ def compound_attribute(name)
         end
       end
 
+      # Resolve a reader for any compound on the document, derived from the
+      # stored data rather than a hardcoded list. The compound set is
+      # schema-driven (see {Hyrax::CompoundSchema}) and, in flexible mode,
+      # per-document — so it cannot be enumerated at class-load time. A name that
+      # has the `<name>_json_ss` blob the compound indexer writes is parsed back
+      # into its rows. This keeps the show page working for an application's own
+      # compounds with no per-app declaration.
+      def method_missing(name, *args, &block)
+        return super unless args.empty? && block.nil?
+        return super unless compound_attribute?(name)
+
+        Solr::CompoundEntries.coerce(self["#{name}_json_ss"])
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        compound_attribute?(name) || super
+      end
+
+      # A name is a dynamic compound reader when either the document carries the
+      # `<name>_json_ss` blob the compound indexer writes (the fast path, no
+      # schema load), or the document's active schema declares it as a compound.
+      # The schema check is what lets a *declared but empty* compound still
+      # answer (returning `[]`), which callers such as the collection presenter's
+      # `terms_with_values` rely on. The schema-name set is memoized per document
+      # and guarded so resolving it never recurses back through method_missing.
+      def compound_attribute?(name)
+        return false if @resolving_compound_names
+        return true if key?("#{name}_json_ss")
+
+        schema_compound_names.include?(name.to_sym)
+      end
+      private :compound_attribute?
+
+      def schema_compound_names
+        return @schema_compound_names if defined?(@schema_compound_names)
+
+        @resolving_compound_names = true
+        @schema_compound_names = Hyrax::CompoundSchema.for_solr_document(self).compound_names
+      rescue StandardError
+        @schema_compound_names = []
+      ensure
+        @resolving_compound_names = false
+      end
+      private :schema_compound_names
+
       module Solr
         class Array
           # @return [Array]
@@ -124,11 +169,8 @@ def alt_text_for_view
         attribute :modified_date, Solr::Date, "system_modified_dtsi"
         attribute :embargo_release_date, Solr::Date, Hydra.config.permissions.embargo.release_date
         attribute :lease_expiration_date, Solr::Date, Hydra.config.permissions.lease.expiration_date
-        # Sample compound attributes shipped with Hyrax.
-        compound_attribute :agents
-        compound_attribute :identifiers
-        compound_attribute :compound_rights
-        compound_attribute :relationships
+        # Compound readers are resolved dynamically per document (see
+        # #method_missing); they are schema-driven, not enumerated here.
       end
     end
   end
diff --git a/documentation/forms/compound_fields.md b/documentation/forms/compound_fields.md
index b8a64e387b..8d098a3973 100644
--- a/documentation/forms/compound_fields.md
+++ b/documentation/forms/compound_fields.md
@@ -234,8 +234,10 @@ or override the samples.
 
 Because the show page renders from Solr (not the live resource), the indexer
 also stores each compound's ordered rows (limited to sub-fields with `display:`
-not false) as a single JSON field (`<compound>_json_ss`). The SolrDocument exposes a `<compound>` reader that
-parses it back into an array of hashes, and the generic
+not false) as a single JSON field (`<compound>_json_ss`). The SolrDocument
+exposes a `<compound>` reader for any compound that has this blob — resolved
+dynamically, so an application's own compounds work with no per-document
+declaration — that parses it back into an array of hashes, and the generic
 `Hyrax::Renderers::CompoundAttributeRenderer` (selected by `view: render_as:
 compound`) renders each entry's populated sub-fields as a small definition
 list. Works render compounds through the standard `attribute_to_html` /

From 803338e3598a36c30a7142deb93555a230e670a8 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Fri, 5 Jun 2026 17:44:22 -0400
Subject: [PATCH 18/32] Rename the sample agents compound to participants

The shipped sample compound `agents` is now `participants`.

Agents as a term has too many other uses and meanings. Additionally,
it also refers to sipity agents, permissions agents, Fedora ACl agents,
etc, meaning it could create a collision of terms & break the app.
---
 .../hyrax/compound_entry_validator.rb         |  3 +-
 config/locales/hyrax.en.yml                   |  8 +--
 config/metadata/compound_metadata.yaml        | 17 +++---
 config/metadata_profiles/m3_profile.yaml      | 14 ++---
 documentation/forms/compound_fields.md        |  5 +-
 .../forms/compound_metadata_form_spec.rb      | 60 +++++++++----------
 .../hyrax/collection_presenter_spec.rb        |  4 +-
 7 files changed, 56 insertions(+), 55 deletions(-)

diff --git a/app/validators/hyrax/compound_entry_validator.rb b/app/validators/hyrax/compound_entry_validator.rb
index 352679c34f..eea7da423e 100644
--- a/app/validators/hyrax/compound_entry_validator.rb
+++ b/app/validators/hyrax/compound_entry_validator.rb
@@ -37,7 +37,8 @@ def validate_compound(record, name, definition)
         # Attach to :base, not the attribute, because the work and collection
         # forms render errors differently (raw messages vs. full_messages):
         # keying on the attribute would either double the field name
-        # ("Agents Agents ...") or print the raw key ("agents ..."). A :base
+        # ("Participants Participants ...") or print the raw key
+        # ("participants ..."). A :base
         # error renders verbatim everywhere, and the message names the compound.
         record.errors.add(:base, message_for(name, violation))
       end
diff --git a/config/locales/hyrax.en.yml b/config/locales/hyrax.en.yml
index 3938c7294b..14f6d5498e 100644
--- a/config/locales/hyrax.en.yml
+++ b/config/locales/hyrax.en.yml
@@ -865,11 +865,11 @@ en:
       errors:
         required_but_empty: "%{compound} requires at least one entry"
         missing_required_subfields: "Each %{compound} entry requires: %{fields}"
-      agents:
-        label: Agents
+      participants:
+        label: Participants
         title: Title
-        agent_name: Name
-        agent_role: Role
+        participant_name: Name
+        participant_role: Role
       identifiers:
         label: Identifiers
         identifier: Identifier
diff --git a/config/metadata/compound_metadata.yaml b/config/metadata/compound_metadata.yaml
index 2e4fafb90e..c62dc16793 100644
--- a/config/metadata/compound_metadata.yaml
+++ b/config/metadata/compound_metadata.yaml
@@ -12,10 +12,9 @@
 # app-level schema, or the m3 profile under HYRAX_FLEXIBLE=true) and may remove
 # these samples by setting `Hyrax.config.compound_metadata_enabled = false`.
 attributes:
-  # Agents associated with the work: a person or organization with a display
-  # title, a name, and a controlled role. (Named `agents` to avoid colliding
-  # with the internal ACL `agent` attribute in hyrax_internal_metadata.yaml.)
-  agents:
+  # Participants associated with the work: a person or organization with a
+  # display title, a name, and a controlled role.
+  participants:
     type: hash
     multiple: true
     predicate: http://id.loc.gov/vocabulary/relators/asn
@@ -27,19 +26,19 @@ attributes:
       # no `index_keys:` is display-only (rendered from the json blob, not its
       # own searchable field). `display: false` would omit it from the blob.
       title: { type: string }
-      agent_name:
+      participant_name:
         type: string
         required: true
-        index_keys: [agent_name_sim, agent_name_tesim]
+        index_keys: [participant_name_sim, participant_name_tesim]
       # A controlled sub-field can take its options from an inline list (below)
       # or from an existing QA local authority (`authority: <name>`).
-      agent_role:
+      participant_role:
         type: controlled
         required: true
         values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
-        index_keys: [agent_role_sim, agent_role_tesim]
+        index_keys: [participant_role_sim, participant_role_tesim]
     groups:
-      - { label: ~, cols: 4, fields: [title, agent_name, agent_role] }
+      - { label: ~, cols: 4, fields: [title, participant_name, participant_role] }
     view:
       render_as: compound
       html_dl: true
diff --git a/config/metadata_profiles/m3_profile.yaml b/config/metadata_profiles/m3_profile.yaml
index 61b8de53e7..1bb100d144 100644
--- a/config/metadata_profiles/m3_profile.yaml
+++ b/config/metadata_profiles/m3_profile.yaml
@@ -956,7 +956,7 @@ properties:
   # `type: hash, multiple: true` property whose entries are hashes of the
   # `subfields:` keys, rendered/populated/indexed generically by the compound
   # foundation. See documentation/forms/compound_fields.md.
-  agents:
+  participants:
     available_on:
       class:
         - Hyrax::Work
@@ -965,7 +965,7 @@ properties:
     type: hash
     range: http://www.w3.org/2001/XMLSchema#string
     display_label:
-      default: Agents
+      default: Participants
     form:
       primary: false
     property_uri: http://id.loc.gov/vocabulary/relators/asn
@@ -973,17 +973,17 @@ properties:
       # Indexing per sub-field via `indexing:` (literal Solr field names), the
       # same mechanism scalar properties use. No `indexing:` => display-only.
       title: { type: string }
-      agent_name:
+      participant_name:
         type: string
         required: true
-        indexing: [agent_name_sim, agent_name_tesim]
-      agent_role:
+        indexing: [participant_name_sim, participant_name_tesim]
+      participant_role:
         type: controlled
         required: true
         values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
-        indexing: [agent_role_sim, agent_role_tesim]
+        indexing: [participant_role_sim, participant_role_tesim]
     groups:
-      - { label: ~, cols: 4, fields: [title, agent_name, agent_role] }
+      - { label: ~, cols: 4, fields: [title, participant_name, participant_role] }
     view:
       render_as: compound
       html_dl: true
diff --git a/documentation/forms/compound_fields.md b/documentation/forms/compound_fields.md
index 8d098a3973..a364cedb46 100644
--- a/documentation/forms/compound_fields.md
+++ b/documentation/forms/compound_fields.md
@@ -210,8 +210,9 @@ end
 Hyrax ships sample compounds on **works and collections** by default,
 demonstrating the supported sub-field types:
 
-- **`agents`** — `title`, `agent_name`, and a controlled `agent_role` (inline
-  `values:`). A person or organization associated with the work or collection.
+- **`participants`** — `title`, `participant_name`, and a controlled
+  `participant_role` (inline `values:`). A person or organization associated
+  with the work or collection.
 - **`identifiers`** — an open-entry `identifier` plus a controlled
   `identifier_type` (inline `values:`).
 - **`compound_rights`** — controlled `rights_statement` and `license` backed by
diff --git a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
index 4bcd4fe3c2..f955af1f6b 100644
--- a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
+++ b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
@@ -41,44 +41,44 @@
 
   describe 'property registration' do
     it 'exposes the compound readers so the form partial can render existing rows' do
-      expect(form).to respond_to(:agents)
+      expect(form).to respond_to(:participants)
       expect(form).to respond_to(:identifiers)
     end
 
     it 'exposes the virtual `<compound>_attributes` setters for nested form params' do
-      expect(form).to respond_to(:agents_attributes=)
+      expect(form).to respond_to(:participants_attributes=)
       expect(form).to respond_to(:identifiers_attributes=)
     end
 
     it 'lists the compounds as compound_terms (and keeps them out of primary/secondary terms)' do
-      expect(form.compound_terms).to include(:agents, :identifiers, :compound_rights)
-      expect(form.primary_terms).not_to include(:agents, :identifiers, :compound_rights)
-      expect(form.secondary_terms).not_to include(:agents, :identifiers, :compound_rights)
+      expect(form.compound_terms).to include(:participants, :identifiers, :compound_rights)
+      expect(form.primary_terms).not_to include(:participants, :identifiers, :compound_rights)
+      expect(form.secondary_terms).not_to include(:participants, :identifiers, :compound_rights)
     end
 
-    it 'registers `agents_attributes` as a real Reform property (not just method-missing)' do
+    it 'registers `participants_attributes` as a real Reform property (not just method-missing)' do
       # This is the property that has to exist in Reform's schema *before*
       # validate runs; if it is registered too late the populator never fires.
       # In non-flexible mode it is registered on the form class via FormFields;
       # check the class definitions registry (the same lens the redirects
       # coverage uses).
       definition_keys = form.class.definitions.keys.map(&:to_s)
-      expect(definition_keys).to include('agents_attributes')
+      expect(definition_keys).to include('participants_attributes')
     end
   end
 
   describe 'validate + sync writes the compound to the model' do
     let(:params) do
-      { 'agents_attributes' =>
-          { '0' => { 'title' => 'Dr', 'agent_name' => 'Ada Lovelace', 'agent_role' => 'Author' } },
+      { 'participants_attributes' =>
+          { '0' => { 'title' => 'Dr', 'participant_name' => 'Ada Lovelace', 'participant_role' => 'Author' } },
         'identifiers_attributes' =>
           { '0' => { 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' } } }
     end
 
     it 'populates the compound on the form during validate' do
       form.validate(params)
-      expect(form.agents)
-        .to eq([{ 'title' => 'Dr', 'agent_name' => 'Ada Lovelace', 'agent_role' => 'Author' }])
+      expect(form.participants)
+        .to eq([{ 'title' => 'Dr', 'participant_name' => 'Ada Lovelace', 'participant_role' => 'Author' }])
       expect(form.identifiers)
         .to eq([{ 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' }])
     end
@@ -86,26 +86,26 @@
     it 'writes the compound through to the model on sync' do
       form.validate(params)
       form.sync
-      expect(form.model.agents)
-        .to eq([{ 'title' => 'Dr', 'agent_name' => 'Ada Lovelace', 'agent_role' => 'Author' }])
+      expect(form.model.participants)
+        .to eq([{ 'title' => 'Dr', 'participant_name' => 'Ada Lovelace', 'participant_role' => 'Author' }])
       expect(form.model.identifiers)
         .to eq([{ 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' }])
     end
 
     it 'drops `_destroy` and all-blank rows' do
-      form.validate('agents_attributes' =>
-        { '0' => { 'agent_name' => 'Keep', 'agent_role' => 'Author' },
-          '1' => { 'agent_name' => 'Remove', '_destroy' => 'true' },
-          '2' => { 'title' => '', 'agent_name' => '', 'agent_role' => '' } })
+      form.validate('participants_attributes' =>
+        { '0' => { 'participant_name' => 'Keep', 'participant_role' => 'Author' },
+          '1' => { 'participant_name' => 'Remove', '_destroy' => 'true' },
+          '2' => { 'title' => '', 'participant_name' => '', 'participant_role' => '' } })
       form.sync
-      expect(form.model.agents).to eq([{ 'title' => nil, 'agent_name' => 'Keep', 'agent_role' => 'Author' }])
+      expect(form.model.participants).to eq([{ 'title' => nil, 'participant_name' => 'Keep', 'participant_role' => 'Author' }])
     end
   end
 
   describe 'required-subfield validation blocks save' do
     # Exercises the real form + Hyrax::CompoundEntryValidator end to end against
     # the *shipped* compound schema (no stub). The shipped samples require
-    # sub-fields within a row (e.g. agents needs agent_name + agent_role,
+    # sub-fields within a row (e.g. participants needs participant_name + participant_role,
     # relationships needs related_item + relationship_type) but none is required
     # at the compound level, so an empty compound is valid. Asserting through the
     # real schema is what catches a validator that reads the form wrapper instead
@@ -119,13 +119,13 @@ def base_errors(form)
     end
 
     it 'allows an empty compound (none is required at the compound level)' do
-      form.validate('agents_attributes' => { '_marker' => { '_destroy' => '1' } })
+      form.validate('participants_attributes' => { '_marker' => { '_destroy' => '1' } })
       expect(base_errors(form)).to be_empty
     end
 
-    it 'flags an agents row that omits a required sub-field' do
-      form.validate('agents_attributes' => { '0' => { 'agent_role' => 'Author' } })
-      expect(base_errors(form)).to include(a_string_including('Agents'))
+    it 'flags a participants row that omits a required sub-field' do
+      form.validate('participants_attributes' => { '0' => { 'participant_role' => 'Author' } })
+      expect(base_errors(form)).to include(a_string_including('Participants'))
     end
 
     it 'flags a relationships row that omits a required sub-field' do
@@ -133,13 +133,13 @@ def base_errors(form)
       expect(base_errors(form)).to include(a_string_including('Relationships'))
     end
 
-    it 'does not flag agents when its required sub-fields are filled' do
-      form.validate('agents_attributes' => { '0' => { 'agent_name' => 'Ada', 'agent_role' => 'Author' } })
-      expect(base_errors(form)).not_to include(a_string_including('Agents'))
+    it 'does not flag participants when its required sub-fields are filled' do
+      form.validate('participants_attributes' => { '0' => { 'participant_name' => 'Ada', 'participant_role' => 'Author' } })
+      expect(base_errors(form)).not_to include(a_string_including('Participants'))
     end
 
     it 'never flags `compound_rights` (no required sub-fields)' do
-      form.validate('agents_attributes' => { '0' => { 'agent_name' => 'Ada', 'agent_role' => 'Author' } })
+      form.validate('participants_attributes' => { '0' => { 'participant_name' => 'Ada', 'participant_role' => 'Author' } })
       expect(base_errors(form)).not_to include(a_string_including('Rights'))
     end
   end
@@ -151,13 +151,13 @@ def base_errors(form)
       skip 'requires a Valkyrie (non-Fedora) persister' if
         Hyrax.persister.is_a?(Wings::Valkyrie::Persister)
 
-      form.validate('agents_attributes' =>
-        { '0' => { 'agent_name' => 'Grace Hopper', 'agent_role' => 'Editor' } })
+      form.validate('participants_attributes' =>
+        { '0' => { 'participant_name' => 'Grace Hopper', 'participant_role' => 'Editor' } })
       form.sync
       saved = Hyrax.persister.save(resource: form.model)
       reloaded = Hyrax.query_service.find_by(id: saved.id)
 
-      expect(reloaded.agents.first['agent_name'] || reloaded.agents.first[:agent_name])
+      expect(reloaded.participants.first['participant_name'] || reloaded.participants.first[:participant_name])
         .to eq('Grace Hopper')
     end
   end
diff --git a/spec/presenters/hyrax/collection_presenter_spec.rb b/spec/presenters/hyrax/collection_presenter_spec.rb
index 2c18818651..773d68c36d 100644
--- a/spec/presenters/hyrax/collection_presenter_spec.rb
+++ b/spec/presenters/hyrax/collection_presenter_spec.rb
@@ -36,8 +36,8 @@
     end
 
     it 'appends this collection\'s inline compound terms' do
-      allow(presenter).to receive(:compound_terms).and_return([:agents, :identifiers])
-      expect(presenter.terms).to end_with(:agents, :identifiers)
+      allow(presenter).to receive(:compound_terms).and_return([:participants, :identifiers])
+      expect(presenter.terms).to end_with(:participants, :identifiers)
     end
 
     context 'with compound metadata disabled' do

From 4b52b20040c832449cec8f73f0b163beabdedb04 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Fri, 5 Jun 2026 18:55:11 -0400
Subject: [PATCH 19/32] Define real SolrDocument readers for compounds

The SolrDocument now defines a real reader method for each compound it
carries (its `<name>_json_ss` blob) when the document is built, so an
application's own compounds render on the show page with no per-document
declaration, in both flex modes.
---
 .../concerns/hyrax/solr_document/metadata.rb  | 68 +++++++------------
 documentation/forms/compound_fields.md        |  6 +-
 spec/models/solr_document_spec.rb             | 45 ++++++++++++
 .../hyrax/compound_entry_validator_spec.rb    | 15 ++--
 4 files changed, 82 insertions(+), 52 deletions(-)

diff --git a/app/models/concerns/hyrax/solr_document/metadata.rb b/app/models/concerns/hyrax/solr_document/metadata.rb
index 6c6edbd5a6..1e4e63ca85 100644
--- a/app/models/concerns/hyrax/solr_document/metadata.rb
+++ b/app/models/concerns/hyrax/solr_document/metadata.rb
@@ -20,50 +20,23 @@ def compound_attribute(name)
         end
       end
 
-      # Resolve a reader for any compound on the document, derived from the
-      # stored data rather than a hardcoded list. The compound set is
-      # schema-driven (see {Hyrax::CompoundSchema}) and, in flexible mode,
-      # per-document — so it cannot be enumerated at class-load time. A name that
-      # has the `<name>_json_ss` blob the compound indexer writes is parsed back
-      # into its rows. This keeps the show page working for an application's own
-      # compounds with no per-app declaration.
-      def method_missing(name, *args, &block)
-        return super unless args.empty? && block.nil?
-        return super unless compound_attribute?(name)
-
-        Solr::CompoundEntries.coerce(self["#{name}_json_ss"])
-      end
-
-      def respond_to_missing?(name, include_private = false)
-        compound_attribute?(name) || super
-      end
-
-      # A name is a dynamic compound reader when either the document carries the
-      # `<name>_json_ss` blob the compound indexer writes (the fast path, no
-      # schema load), or the document's active schema declares it as a compound.
-      # The schema check is what lets a *declared but empty* compound still
-      # answer (returning `[]`), which callers such as the collection presenter's
-      # `terms_with_values` rely on. The schema-name set is memoized per document
-      # and guarded so resolving it never recurses back through method_missing.
-      def compound_attribute?(name)
-        return false if @resolving_compound_names
-        return true if key?("#{name}_json_ss")
-
-        schema_compound_names.include?(name.to_sym)
-      end
-      private :compound_attribute?
-
-      def schema_compound_names
-        return @schema_compound_names if defined?(@schema_compound_names)
-
-        @resolving_compound_names = true
-        @schema_compound_names = Hyrax::CompoundSchema.for_solr_document(self).compound_names
-      rescue StandardError
-        @schema_compound_names = []
-      ensure
-        @resolving_compound_names = false
+      # Defines a reader for each compound on the document (its `<name>_json_ss`
+      # blob, written by {Hyrax::Indexers::CompoundIndexer}). Uses a real method
+      # rather than #method_missing on purpose: a Blacklight/Solr document can
+      # answer to an arbitrary field name with a nil-returning accessor that
+      # would shadow #method_missing, so a real method is required to win.
+      def define_compound_readers!
+        keys.each do |key|
+          next unless key.to_s.end_with?('_json_ss')
+
+          name = key.to_s.delete_suffix('_json_ss')
+          next if singleton_class.method_defined?(name)
+
+          define_singleton_method(name) do
+            Solr::CompoundEntries.coerce(self["#{name}_json_ss"])
+          end
+        end
       end
-      private :schema_compound_names
 
       module Solr
         class Array
@@ -169,8 +142,13 @@ def alt_text_for_view
         attribute :modified_date, Solr::Date, "system_modified_dtsi"
         attribute :embargo_release_date, Solr::Date, Hydra.config.permissions.embargo.release_date
         attribute :lease_expiration_date, Solr::Date, Hydra.config.permissions.lease.expiration_date
-        # Compound readers are resolved dynamically per document (see
-        # #method_missing); they are schema-driven, not enumerated here.
+
+        # Define compound readers per-instance so an application's own compounds
+        # render with no per-app declaration. See #define_compound_readers!.
+        def initialize(source_doc = {}, *args)
+          super
+          define_compound_readers!
+        end
       end
     end
   end
diff --git a/documentation/forms/compound_fields.md b/documentation/forms/compound_fields.md
index a364cedb46..6d0cb5d8e7 100644
--- a/documentation/forms/compound_fields.md
+++ b/documentation/forms/compound_fields.md
@@ -236,9 +236,9 @@ or override the samples.
 Because the show page renders from Solr (not the live resource), the indexer
 also stores each compound's ordered rows (limited to sub-fields with `display:`
 not false) as a single JSON field (`<compound>_json_ss`). The SolrDocument
-exposes a `<compound>` reader for any compound that has this blob — resolved
-dynamically, so an application's own compounds work with no per-document
-declaration — that parses it back into an array of hashes, and the generic
+defines a `<compound>` reader for each such blob it carries — so an
+application's own compounds work with no per-document declaration — that
+parses it back into an array of hashes, and the generic
 `Hyrax::Renderers::CompoundAttributeRenderer` (selected by `view: render_as:
 compound`) renders each entry's populated sub-fields as a small definition
 list. Works render compounds through the standard `attribute_to_html` /
diff --git a/spec/models/solr_document_spec.rb b/spec/models/solr_document_spec.rb
index f2c63cc3b9..cc82fd1427 100644
--- a/spec/models/solr_document_spec.rb
+++ b/spec/models/solr_document_spec.rb
@@ -241,4 +241,49 @@ class Mimes
       is_expected.to eq ['foo']
     end
   end
+
+  describe "compound readers" do
+    # A compound (hierarchical) attribute is indexed as a `<name>_json_ss`
+    # blob. The document defines a reader per such field at construction, so an
+    # application's own compounds render without a per-app declaration and
+    # without depending on the (possibly stale) flexible schema. See
+    # documentation/forms/compound_fields.md.
+    let(:attributes) do
+      { 'contributors_json_ss' =>
+          [%([{"given_name":"Grace","family_name":"Hopper"}])],
+        'funding_references_json_ss' =>
+          [%([{"funder_name":"NSF","award_number":"123"}])],
+        'empty_compound_json_ss' => [] }
+    end
+
+    it "defines a reader for each compound present on the document" do
+      expect(document).to respond_to(:contributors)
+      expect(document).to respond_to(:funding_references)
+    end
+
+    it "defines the reader as a real method (not via method_missing)" do
+      # A real method is required so the reader wins over a same-named dynamic
+      # field accessor that would otherwise shadow it and return nil.
+      expect(document.singleton_class.method_defined?(:contributors)).to be true
+      expect(document.method(:contributors).owner).to eq(document.singleton_class)
+    end
+
+    it "parses the stored rows back into an array of hashes" do
+      expect(document.contributors)
+        .to eq([{ 'given_name' => 'Grace', 'family_name' => 'Hopper' }])
+    end
+
+    it "handles multi-word compound names" do
+      expect(document.funding_references)
+        .to eq([{ 'funder_name' => 'NSF', 'award_number' => '123' }])
+    end
+
+    it "returns an empty array for a present-but-blank compound blob" do
+      expect(document.empty_compound).to eq([])
+    end
+
+    it "does not define a reader for a compound that is not on the document" do
+      expect(document).not_to respond_to(:nonexistent_compound)
+    end
+  end
 end
diff --git a/spec/validators/hyrax/compound_entry_validator_spec.rb b/spec/validators/hyrax/compound_entry_validator_spec.rb
index c9760a0799..afce3841f7 100644
--- a/spec/validators/hyrax/compound_entry_validator_spec.rb
+++ b/spec/validators/hyrax/compound_entry_validator_spec.rb
@@ -63,8 +63,12 @@
     end
 
     it 'names the compound and the missing sub-field in the message' do
-      record.valid?
-      expect(record.errors[:base].first).to include('Relationships').and include('Relationship type')
+      # Assert the English wording under :en, so the test is independent of the
+      # suite's default locale (other locales need only the same key structure).
+      I18n.with_locale(:en) do
+        record.valid?
+        expect(record.errors[:base].first).to include('Relationships').and include('Relationship type')
+      end
     end
   end
 
@@ -73,8 +77,11 @@
 
     context 'and empty' do
       it 'flags the empty compound by name' do
-        record.valid?
-        expect(record.errors[:base].first).to include('Relationships').and include('at least one entry')
+        # English wording; see the note above on locale.
+        I18n.with_locale(:en) do
+          record.valid?
+          expect(record.errors[:base].first).to include('Relationships').and include('at least one entry')
+        end
       end
     end
 

From d82788ad0afd29730871ab8d6603d5686ddcb541 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Fri, 5 Jun 2026 19:52:55 -0400
Subject: [PATCH 20/32] Show collections with declared but empty compounds

Collection show pages now render when a compound is declared for the
collection but the record has no entries for it, instead of raising
NoMethodError.

The collection presenter lists every declared compound among its terms,
but the SolrDocument only defines a reader for a compound that has
indexed data. Reading a declared-but-empty compound now returns no
entries rather than calling an undefined method.
---
 app/presenters/hyrax/collection_presenter.rb | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/app/presenters/hyrax/collection_presenter.rb b/app/presenters/hyrax/collection_presenter.rb
index 9837fc10e2..61c6a1fb08 100644
--- a/app/presenters/hyrax/collection_presenter.rb
+++ b/app/presenters/hyrax/collection_presenter.rb
@@ -119,10 +119,19 @@ def [](key)
       when :total_items
         total_items
       else
+        # A declared compound with no indexed `<name>_json_ss` blob has no reader
+        # defined on the document; treat it as empty rather than raising.
+        return compound_value(key) if compound_term?(key) && !solr_document.respond_to?(key)
         solr_document.send key
       end
     end
 
+    # The rows for a declared-but-empty compound term, coerced from the absent
+    # blob exactly as the SolrDocument reader would (nil => []).
+    def compound_value(key)
+      Hyrax::SolrDocument::Metadata::Solr::CompoundEntries.coerce(solr_document["#{key}_json_ss"])
+    end
+
     # @deprecated to be removed in 4.0.0; this feature was replaced with a
     #   hard-coded null implementation
     # @return [String] 'unknown'

From a54d3f7abd4547e273409888de2b0321c89574ac Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Fri, 5 Jun 2026 21:06:50 -0400
Subject: [PATCH 21/32] Rename compound "subfield" to "subproperty"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Compound (hierarchical) metadata now calls its nested members
"subproperties" instead of "subfields" — the YAML key is
`subproperties:`, and the supporting classes, methods, i18n keys, and
CSS classes follow the same name.

This is a vocabulary rename only; the declaration structure, the
normalized internal shape, indexing, rendering, and validation are
unchanged. It sets up a later change that expresses subproperties as
composable, first-class properties.
---
 .../config/metadata_profiles/m3_profile.yaml  |  8 +-
 .../javascripts/hyrax/compound_metadata.js    |  2 +-
 .../stylesheets/hyrax/_compound_metadata.scss | 16 ++--
 .../qa/authorities/compound_works.rb          |  2 +-
 .../concerns/hyrax/compound_field_behavior.rb |  8 +-
 .../concerns/hyrax/flexible_form_behavior.rb  |  6 +-
 app/forms/hyrax/forms/resource_form.rb        |  2 +-
 app/helpers/hyrax/collections_helper.rb       |  2 +-
 app/helpers/hyrax/compound_fields_helper.rb   | 20 ++--
 .../hyrax/indexers/compound_indexer.rb        | 22 ++---
 .../hyrax/indexers/pcdm_collection_indexer.rb |  2 +-
 .../hyrax/indexers/pcdm_object_indexer.rb     |  2 +-
 .../concerns/hyrax/compound_normalization.rb  |  2 +-
 app/presenters/hyrax/presents_attributes.rb   | 12 +--
 .../renderers/compound_attribute_renderer.rb  | 54 +++++------
 .../hyrax/compound_work_picker_builder.rb     |  2 +-
 .../hyrax/compound_entry_validation.rb        |  9 +-
 app/services/hyrax/compound_schema.rb         | 41 ++++----
 ...ler.rb => compound_subproperty_labeler.rb} | 12 +--
 app/services/hyrax/compound_work_resolver.rb  |  2 +-
 .../flexible_schema_validator_service.rb      |  4 +-
 .../compound_validator.rb                     | 30 +++---
 app/services/hyrax/schema_loader.rb           |  2 +-
 .../hyrax/compound_entry_validator.rb         |  7 +-
 .../hyrax/compounds/_compound_row.html.erb    | 22 ++---
 .../compounds/_compound_section.html.erb      |  4 +-
 config/locales/hyrax.en.yml                   | 10 +-
 config/metadata/compound_metadata.yaml        | 24 ++---
 config/metadata_profiles/m3_profile.yaml      | 12 +--
 documentation/forms/compound_fields.md        | 96 +++++++++----------
 documentation/forms/field_behaviors.md        | 12 +--
 lib/hyrax/form_fields.rb                      |  8 +-
 .../hyrax/compound_field_behavior_spec.rb     |  4 +-
 .../forms/compound_metadata_form_spec.rb      | 12 +--
 .../hyrax/compound_fields_helper_spec.rb      | 26 ++---
 .../hyrax/indexers/compound_indexer_spec.rb   | 12 +--
 .../hyrax/compound_normalization_spec.rb      |  2 +-
 .../compound_attribute_renderer_spec.rb       | 50 +++++-----
 .../hyrax/compound_entry_validation_spec.rb   | 22 ++---
 spec/services/hyrax/compound_schema_spec.rb   | 62 ++++++------
 ...b => compound_subproperty_labeler_spec.rb} |  4 +-
 .../compound_validator_spec.rb                | 30 +++---
 .../hyrax/compound_entry_validator_spec.rb    | 10 +-
 43 files changed, 347 insertions(+), 344 deletions(-)
 rename app/services/hyrax/{compound_subfield_labeler.rb => compound_subproperty_labeler.rb} (79%)
 rename spec/services/hyrax/{compound_subfield_labeler_spec.rb => compound_subproperty_labeler_spec.rb} (93%)

diff --git a/.koppie/config/metadata_profiles/m3_profile.yaml b/.koppie/config/metadata_profiles/m3_profile.yaml
index 083f7873d0..d8f58af69f 100644
--- a/.koppie/config/metadata_profiles/m3_profile.yaml
+++ b/.koppie/config/metadata_profiles/m3_profile.yaml
@@ -943,7 +943,7 @@ properties:
     form:
       primary: false
     property_uri: http://id.loc.gov/vocabulary/relators/asn
-    subfields:
+    subproperties:
       title: { type: string }
       agent_name:
         type: string
@@ -972,7 +972,7 @@ properties:
     form:
       primary: false
     property_uri: http://purl.org/dc/terms/identifier
-    subfields:
+    subproperties:
       identifier:
         type: string
         required: true
@@ -998,7 +998,7 @@ properties:
     form:
       primary: false
     property_uri: http://purl.org/dc/terms/rights
-    subfields:
+    subproperties:
       rights_statement:
         type: controlled
         authority: rights_statements
@@ -1026,7 +1026,7 @@ properties:
     form:
       primary: false
     property_uri: http://purl.org/dc/terms/relation
-    subfields:
+    subproperties:
       related_item:
         type: work_or_url
         required: true
diff --git a/app/assets/javascripts/hyrax/compound_metadata.js b/app/assets/javascripts/hyrax/compound_metadata.js
index b5a7099de2..3f09bb7ed6 100644
--- a/app/assets/javascripts/hyrax/compound_metadata.js
+++ b/app/assets/javascripts/hyrax/compound_metadata.js
@@ -7,7 +7,7 @@
     if (document.hyraxCompoundsBound) return;
     document.hyraxCompoundsBound = true;
 
-    // Bind select2 to a `work_or_url` sub-field. The v3 API (Hyrax bundles
+    // Bind select2 to a `work_or_url` sub-property. The v3 API (Hyrax bundles
     // select2-rails 3.x) binds to a hidden input; createSearchChoice lets a
     // typed external URL be selected as-is.
     function bindWorkOrUrlInputs(root) {
diff --git a/app/assets/stylesheets/hyrax/_compound_metadata.scss b/app/assets/stylesheets/hyrax/_compound_metadata.scss
index 15e54343b7..17e8c6fcee 100644
--- a/app/assets/stylesheets/hyrax/_compound_metadata.scss
+++ b/app/assets/stylesheets/hyrax/_compound_metadata.scss
@@ -12,17 +12,17 @@
   padding: 0 !important;
   max-width: 100%;
 
-  // Force block flow on the entries/sub-fields; the label/value spans stay
-  // inline so each sub-field reads as "Label: value" on one wrapping line.
+  // Force block flow on the entries/sub-properties; the label/value spans stay
+  // inline so each sub-property reads as "Label: value" on one wrapping line.
   .hyrax-compound-entry,
-  .hyrax-compound-subfield {
+  .hyrax-compound-subproperty {
     display: block !important;
   }
 
   .hyrax-compound-entry,
-  .hyrax-compound-subfield,
-  .hyrax-compound-subfield-label,
-  .hyrax-compound-subfield-value {
+  .hyrax-compound-subproperty,
+  .hyrax-compound-subproperty-label,
+  .hyrax-compound-subproperty-value {
     border: 0 !important;
     padding: 0 !important;
     margin: 0;
@@ -36,14 +36,14 @@
     border-top: 1px solid $gray-200 !important;
   }
 
-  .hyrax-compound-subfield {
+  .hyrax-compound-subproperty {
     display: block;
     line-height: 1.4;
     overflow-wrap: break-word;
     word-break: break-word;
   }
 
-  .hyrax-compound-subfield-label {
+  .hyrax-compound-subproperty-label {
     font-weight: 600;
     margin-right: 0.25rem;
   }
diff --git a/app/authorities/qa/authorities/compound_works.rb b/app/authorities/qa/authorities/compound_works.rb
index 66e70cba84..3f84882291 100644
--- a/app/authorities/qa/authorities/compound_works.rb
+++ b/app/authorities/qa/authorities/compound_works.rb
@@ -2,7 +2,7 @@
 
 module Qa::Authorities
   ##
-  # Autocomplete authority for the compound `work_or_url` sub-field's work
+  # Autocomplete authority for the compound `work_or_url` sub-property's work
   # picker, mounted at `/authorities/search/compound_works`. Returns readable
   # works matched by {Hyrax::CompoundWorkPickerBuilder}.
   class CompoundWorks < Qa::Authorities::Base
diff --git a/app/forms/concerns/hyrax/compound_field_behavior.rb b/app/forms/concerns/hyrax/compound_field_behavior.rb
index f5ca4bf3c0..1897f53ef6 100644
--- a/app/forms/concerns/hyrax/compound_field_behavior.rb
+++ b/app/forms/concerns/hyrax/compound_field_behavior.rb
@@ -53,13 +53,13 @@ def compound_field_names
     end
 
     # One populator serves every compound (Reform passes the property name as
-    # `as:`). Builds the replacement array of plain hashes — declared sub-field
-    # keys only, dropping `_destroy` and all-blank rows.
+    # `as:`). Builds the replacement array of plain hashes — declared
+    # sub-property keys only, dropping `_destroy` and all-blank rows.
     def compound_attributes_populator(fragment:, as:, **_options)
       name = as.to_s.delete_suffix('_attributes')
       return unless respond_to?(name)
 
-      allowed = Hyrax::CompoundSchema.for(model).subfield_keys(name)
+      allowed = Hyrax::CompoundSchema.for(model).subproperty_keys(name)
       public_send(:"#{name}=", build_compound_rows(fragment, allowed))
     end
 
@@ -75,7 +75,7 @@ def compound_fragment_pairs(fragment)
       fragment.respond_to?(:to_unsafe_h) ? fragment.to_unsafe_h : fragment.to_h
     end
 
-    # Returns nil for a row marked for destruction or whose declared sub-fields
+    # Returns nil for a row marked for destruction or whose declared sub-properties
     # are all blank, otherwise the persisted hash for that row.
     def compound_row_from(row, allowed_keys)
       row = row.respond_to?(:to_unsafe_h) ? row.to_unsafe_h : row.to_h
diff --git a/app/forms/concerns/hyrax/flexible_form_behavior.rb b/app/forms/concerns/hyrax/flexible_form_behavior.rb
index fa59896c4d..f0874b1a23 100644
--- a/app/forms/concerns/hyrax/flexible_form_behavior.rb
+++ b/app/forms/concerns/hyrax/flexible_form_behavior.rb
@@ -13,7 +13,7 @@ def validate_flexible_required_fields
       required_fields = singleton_class.schema_definitions.select { |_, opts| opts[:required] }.keys
 
       required_fields.each do |field|
-        # Compound fields carry their own requiredness rules (per-row sub-field
+        # Compound fields carry their own requiredness rules (per-row sub-property
         # checks); Hyrax::CompoundEntryValidator owns them, so skip the generic
         # blank check to avoid a duplicate "can't be blank" error.
         next if compound_field?(field)
@@ -29,9 +29,9 @@ def schema
 
     private
 
-    # Whether the field is a compound (declares `subfields:`), looked up from
+    # Whether the field is a compound (declares `subproperties:`), looked up from
     # the resource's compound schema — the flex form definitions don't carry
-    # `subfields`. Memoized per form instance.
+    # `subproperties`. Memoized per form instance.
     def compound_field?(field)
       return false unless Hyrax.config.respond_to?(:compound_metadata_enabled?) && Hyrax.config.compound_metadata_enabled?
       @compound_field_names ||= Hyrax::CompoundSchema.for(model).compound_names
diff --git a/app/forms/hyrax/forms/resource_form.rb b/app/forms/hyrax/forms/resource_form.rb
index c2cbab8578..d0c2c4adff 100644
--- a/app/forms/hyrax/forms/resource_form.rb
+++ b/app/forms/hyrax/forms/resource_form.rb
@@ -64,7 +64,7 @@ class ResourceForm < Hyrax::ChangeSet # rubocop:disable Metrics/ClassLength
         end
       end
 
-      # Required-compound / required-sub-field validation. Wired through a
+      # Required-compound / required-sub-property validation. Wired through a
       # `validation { ... }` block (not a bare `validates_with`) because these
       # are Reform/Disposable forms — a bare `validates_with` does not hook into
       # Reform's `validate`, so it would never run. Record-level (no
diff --git a/app/helpers/hyrax/collections_helper.rb b/app/helpers/hyrax/collections_helper.rb
index 6fb60d1c79..70cfbc3307 100644
--- a/app/helpers/hyrax/collections_helper.rb
+++ b/app/helpers/hyrax/collections_helper.rb
@@ -49,7 +49,7 @@ def collection_metadata_value(collection, field)
       if collection.respond_to?(:compound_term?) && collection.compound_term?(field)
         definition = compound_schema_for(collection).definition_for(field)
         return Hyrax::Renderers::CompoundAttributeRenderer
-               .new(field, collection[field], subfields: definition&.fetch(:subfields, nil))
+               .new(field, collection[field], subproperties: definition&.fetch(:subproperties, nil))
                .render_value
       end
 
diff --git a/app/helpers/hyrax/compound_fields_helper.rb b/app/helpers/hyrax/compound_fields_helper.rb
index 6e8c5f0635..aac4e5722b 100644
--- a/app/helpers/hyrax/compound_fields_helper.rb
+++ b/app/helpers/hyrax/compound_fields_helper.rb
@@ -5,7 +5,7 @@ module Hyrax
   # and show pages. See documentation/forms/compound_fields.md.
   module CompoundFieldsHelper
     ##
-    # Renders one compound section (a repeatable stack of sub-field rows) for the
+    # Renders one compound section (a repeatable stack of sub-property rows) for the
     # given attribute via the `hyrax/compounds/*` partials.
     #
     # @return [String, nil] rendered HTML, or nil when the attribute is not a
@@ -65,29 +65,29 @@ def compound_schema_for(presenter)
     end
 
     ##
-    # Options for a `controlled` sub-field's `<select>`: an inline `values:`
+    # Options for a `controlled` sub-property's `<select>`: an inline `values:`
     # list when present, otherwise the named QA authority. A stored value not
     # among the options is appended so it still renders (`include_current_value`).
     #
     # @return [Array<Array(String, String)>] `[[label, id], ...]`
-    def compound_subfield_options(spec, current_value = nil)
+    def compound_subproperty_options(spec, current_value = nil)
       options = spec[:values].presence || authority_options(spec[:authority])
       ensure_current_value(options, current_value)
     end
 
     ##
     # @return [Boolean] whether +current_value+ is present but not among the
-    #   sub-field's offered options — i.e. a forced/stale value. The select
+    #   sub-property's offered options — i.e. a forced/stale value. The select
     #   gets the +force-select+ class in that case, matching the ordinary
     #   controlled-field convention.
-    def compound_subfield_forced?(spec, current_value = nil)
+    def compound_subproperty_forced?(spec, current_value = nil)
       return false if current_value.blank?
       base = spec[:values].presence || authority_options(spec[:authority])
       base.none? { |(_label, id)| id.to_s == current_value.to_s }
     end
 
     ##
-    # The pre-selected `[label, value]` option for a `work_or_url` sub-field's
+    # The pre-selected `[label, value]` option for a `work_or_url` sub-property's
     # select2, or nil when empty. An internal work id resolves to its title; an
     # external URL is shown as-is.
     #
@@ -121,9 +121,9 @@ def compound_card_label(presenter, field)
       compound_field_label(field, display_label: compound_schema_for(presenter).definition_for(field)&.dig(:display_label))
     end
 
-    def compound_subfield_label(compound_name, sub_field)
-      t("hyrax.compound_fields.#{compound_name}.#{sub_field}",
-        default: sub_field.to_s.humanize)
+    def compound_subproperty_label(compound_name, sub_property)
+      t("hyrax.compound_fields.#{compound_name}.#{sub_property}",
+        default: sub_property.to_s.humanize)
     end
 
     private
@@ -135,7 +135,7 @@ def authority_options(authority_name)
       return [] if authority_name.blank?
       Hyrax::TolerantSelectService.new(authority_name).select_active_options
     rescue StandardError => e
-      Hyrax.logger.debug("compound_subfield_options: #{authority_name}: #{e.message}")
+      Hyrax.logger.debug("compound_subproperty_options: #{authority_name}: #{e.message}")
       []
     end
 
diff --git a/app/indexers/hyrax/indexers/compound_indexer.rb b/app/indexers/hyrax/indexers/compound_indexer.rb
index 3983166396..33fd72e80f 100644
--- a/app/indexers/hyrax/indexers/compound_indexer.rb
+++ b/app/indexers/hyrax/indexers/compound_indexer.rb
@@ -3,11 +3,11 @@
 module Hyrax
   module Indexers
     ##
-    # Indexer mixin that projects compound metadata sub-fields into Solr. For
+    # Indexer mixin that projects compound metadata sub-properties into Solr. For
     # every compound on the resource (see {Hyrax::CompoundSchema}), it writes
-    # each sub-field's declared `index_keys:`/`indexing:` Solr fields and stores
-    # the displayable rows as a `<compound>_json_ss` blob the show page renders
-    # from. See documentation/forms/compound_fields.md.
+    # each sub-property's declared `index_keys:`/`indexing:` Solr fields and
+    # stores the displayable rows as a `<compound>_json_ss` blob the show page
+    # renders from. See documentation/forms/compound_fields.md.
     #
     # @example
     #   class WorkIndexer < Hyrax::Indexers::PcdmObjectIndexer
@@ -31,15 +31,15 @@ def compound_schema
 
       def index_compound(document, compound_name, definition)
         rows = Array(resource.public_send(compound_name))
-        index_searchable_subfields(document, definition, rows)
+        index_searchable_subproperties(document, definition, rows)
         index_display_blob(document, compound_name, definition, rows)
       end
 
-      def index_searchable_subfields(document, definition, rows)
-        definition[:subfields].each do |sub_field, spec|
+      def index_searchable_subproperties(document, definition, rows)
+        definition[:subproperties].each do |sub_property, spec|
           next if spec[:index_keys].blank?
 
-          values = rows.map { |row| compound_entry_value(row, sub_field) }.reject(&:blank?)
+          values = rows.map { |row| compound_entry_value(row, sub_property) }.reject(&:blank?)
           next if values.empty?
 
           spec[:index_keys].each { |index_key| document[index_key] = values }
@@ -47,7 +47,7 @@ def index_searchable_subfields(document, definition, rows)
       end
 
       def index_display_blob(document, compound_name, definition, rows)
-        display_keys = definition[:subfields].select { |_k, spec| spec[:display] }.keys
+        display_keys = definition[:subproperties].select { |_k, spec| spec[:display] }.keys
         normalized = rows.map { |row| display_entry(row, display_keys) }.reject(&:empty?)
         document["#{compound_name}_json_ss"] = normalized.to_json unless normalized.empty?
       end
@@ -60,9 +60,9 @@ def display_entry(row, display_keys)
         end
       end
 
-      def compound_entry_value(row, sub_field)
+      def compound_entry_value(row, sub_property)
         return nil unless row.respond_to?(:[])
-        row[sub_field] || row[sub_field.to_sym]
+        row[sub_property] || row[sub_property.to_sym]
       end
     end
   end
diff --git a/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb b/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
index d356fdb934..ca3daa6726 100644
--- a/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
+++ b/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
@@ -11,7 +11,7 @@ class PcdmCollectionIndexer < Hyrax::Indexers::ResourceIndexer
       include Hyrax::ThumbnailIndexer
       include Hyrax::Indexer(:core_metadata) if Hyrax.config.collection_include_metadata?
       include Hyrax::Indexers::RedirectsIndexer if Hyrax.config.redirects_enabled?
-      # Flatten compound (hierarchical) metadata sub-fields into Solr. No-op for
+      # Flatten compound (hierarchical) metadata sub-properties into Solr. No-op for
       # collections without compounds. See documentation/forms/compound_fields.md.
       include Hyrax::Indexers::CompoundIndexer if Hyrax.config.compound_metadata_enabled?
       check_if_flexible(Hyrax::PcdmCollection)
diff --git a/app/indexers/hyrax/indexers/pcdm_object_indexer.rb b/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
index 58100c64bb..7cb547a646 100644
--- a/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
+++ b/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
@@ -11,7 +11,7 @@ class PcdmObjectIndexer < Hyrax::Indexers::ResourceIndexer
       include Hyrax::ThumbnailIndexer
       include Hyrax::WorkflowIndexer
       include Hyrax::Indexers::RedirectsIndexer if Hyrax.config.redirects_enabled?
-      # Flatten compound (hierarchical) metadata sub-fields into Solr. No-op for
+      # Flatten compound (hierarchical) metadata sub-properties into Solr. No-op for
       # resources without compounds. See documentation/forms/compound_fields.md.
       include Hyrax::Indexers::CompoundIndexer if Hyrax.config.compound_metadata_enabled?
 
diff --git a/app/models/concerns/hyrax/compound_normalization.rb b/app/models/concerns/hyrax/compound_normalization.rb
index 62f7fdf5af..1cec6b78fc 100644
--- a/app/models/concerns/hyrax/compound_normalization.rb
+++ b/app/models/concerns/hyrax/compound_normalization.rb
@@ -2,7 +2,7 @@
 
 module Hyrax
   ##
-  # Defends compound attributes (`type: hash, multiple: true` with `subfields:` —
+  # Defends compound attributes (`type: hash, multiple: true` with `subproperties:` —
   # see {Hyrax::CompoundSchema}) against a read-path quirk in Valkyrie's Postgres
   # orm_converter: `JSONValueMapper` unwraps a single-element array to its first
   # element and re-symbolizes the Hash's keys, then dry-struct's `Array.of(Hash)`
diff --git a/app/presenters/hyrax/presents_attributes.rb b/app/presenters/hyrax/presents_attributes.rb
index 54925cb013..18f70b0db3 100644
--- a/app/presenters/hyrax/presents_attributes.rb
+++ b/app/presenters/hyrax/presents_attributes.rb
@@ -22,7 +22,7 @@ def attribute_to_html(field, options = {})
         return
       end
 
-      options = options.merge(subfields: compound_subfields_for(field)) if options[:render_as].to_s == 'compound'
+      options = options.merge(subproperties: compound_subproperties_for(field)) if options[:render_as].to_s == 'compound'
       renderer = renderer_for(field, options).new(field, send(field), options)
 
       if options[:value_only] && renderer.respond_to?(:render_value)
@@ -54,18 +54,18 @@ def microdata_type_to_html
 
     private
 
-    # Normalized sub-field specs for a compound, so the renderer can translate
+    # Normalized sub-property specs for a compound, so the renderer can translate
     # controlled ids to their terms; nil if the resource class can't be
     # resolved (the renderer then renders raw values).
-    def compound_subfields_for(field)
+    def compound_subproperties_for(field)
       return nil unless respond_to?(:solr_document) && solr_document.respond_to?(:hydra_model)
       # Resolve from the backing document, not the class: in flexible mode the
-      # class carries no compounds, so a class lookup would drop the sub-field
+      # class carries no compounds, so a class lookup would drop the sub-property
       # specs and the renderer would fall back to raw (unlinked, untranslated)
       # values.
-      Hyrax::CompoundSchema.for_solr_document(solr_document).definition_for(field)&.fetch(:subfields, nil)
+      Hyrax::CompoundSchema.for_solr_document(solr_document).definition_for(field)&.fetch(:subproperties, nil)
     rescue StandardError => e
-      Hyrax.logger.debug("compound_subfields_for(#{field}): #{e.message}")
+      Hyrax.logger.debug("compound_subproperties_for(#{field}): #{e.message}")
       nil
     end
 
diff --git a/app/renderers/hyrax/renderers/compound_attribute_renderer.rb b/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
index d474ef5ca5..4807632b0a 100644
--- a/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
+++ b/app/renderers/hyrax/renderers/compound_attribute_renderer.rb
@@ -5,9 +5,9 @@ module Renderers
     ##
     # Renders a compound metadata attribute on a show page (selected via
     # `view: { render_as: compound }`). Each value is one entry — a hash of
-    # sub-fields produced by the SolrDocument `compound_attribute` reader — and
-    # renders as a block of its populated sub-fields. Sub-field labels come from
-    # the `hyrax.compound_fields.<compound>.<subfield>` i18n keys.
+    # sub-properties produced by the SolrDocument `compound_attribute` reader —
+    # and renders as a block of its populated sub-properties. Sub-property labels
+    # come from the `hyrax.compound_fields.<compound>.<subproperty>` i18n keys.
     class CompoundAttributeRenderer < AttributeRenderer
       def render
         return '' if blank_values? && !options[:include_empty]
@@ -51,33 +51,33 @@ def entry_markup(entry)
         pairs = entry_to_pairs(entry)
         return '' if pairs.empty?
 
-        items = pairs.map { |sub_field, value| subfield_markup(sub_field, value) }.join
+        items = pairs.map { |sub_property, value| subproperty_markup(sub_property, value) }.join
         %(<div class="hyrax-compound-entry">#{items}</div>)
       end
 
-      def subfield_markup(sub_field, value)
-        label_html = ERB::Util.h(sub_field_label(sub_field))
-        %(<div class="hyrax-compound-subfield">) +
-          %(<span class="hyrax-compound-subfield-label">#{label_html}:</span> ) +
-          %(<span class="hyrax-compound-subfield-value">#{value_markup(sub_field, value)}</span>) +
+      def subproperty_markup(sub_property, value)
+        label_html = ERB::Util.h(sub_property_label(sub_property))
+        %(<div class="hyrax-compound-subproperty">) +
+          %(<span class="hyrax-compound-subproperty-label">#{label_html}:</span> ) +
+          %(<span class="hyrax-compound-subproperty-value">#{value_markup(sub_property, value)}</span>) +
           %(</div>)
       end
 
-      # Display markup for one sub-field value, by sub-field type: `url` and
+      # Display markup for one sub-property value, by sub-property type: `url` and
       # `work_or_url` are linked; otherwise escaped text with controlled ids
       # translated to their term.
-      def value_markup(sub_field, value)
-        return ERB::Util.h(display_value(sub_field, value)) if value.blank?
+      def value_markup(sub_property, value)
+        return ERB::Util.h(display_value(sub_property, value)) if value.blank?
 
-        case subfield_spec(sub_field)&.dig(:type).to_s
+        case subproperty_spec(sub_property)&.dig(:type).to_s
         when 'url'
           auto_link(ERB::Util.h(value.to_s))
         when 'work_or_url'
           work_or_url_markup(value)
         when 'controlled'
-          controlled_markup(sub_field, value)
+          controlled_markup(sub_property, value)
         else
-          ERB::Util.h(display_value(sub_field, value))
+          ERB::Util.h(display_value(sub_property, value))
         end
       end
 
@@ -85,8 +85,8 @@ def value_markup(sub_field, value)
       # stored value is itself a linkable URI (e.g. a rights-statement or license
       # URI), link the term to that URI — mirroring the ordinary rights/license
       # renderer. Non-URI controlled values (e.g. inline option ids) stay plain.
-      def controlled_markup(sub_field, value)
-        label = display_value(sub_field, value)
+      def controlled_markup(sub_property, value)
+        label = display_value(sub_property, value)
         if Hyrax::AuthorityRenderingHelper.linkable_uri?(value)
           %(<a href="#{ERB::Util.h(value)}" target="_blank" rel="noopener noreferrer">#{ERB::Util.h(label)}</a>).html_safe
         else
@@ -104,19 +104,19 @@ def work_or_url_markup(value)
         link_to(ERB::Util.h(title), path)
       end
 
-      def display_value(sub_field, value)
-        Hyrax::CompoundSubfieldLabeler.label_for(subfield_spec(sub_field), value)
+      def display_value(sub_property, value)
+        Hyrax::CompoundSubpropertyLabeler.label_for(subproperty_spec(sub_property), value)
       end
 
-      # The normalized sub-field spec, supplied by the caller via
-      # `options[:subfields]`.
-      def subfield_spec(sub_field)
-        specs = options[:subfields]
+      # The normalized sub-property spec, supplied by the caller via
+      # `options[:subproperties]`.
+      def subproperty_spec(sub_property)
+        specs = options[:subproperties]
         return nil unless specs.is_a?(Hash)
-        specs[sub_field] || specs[sub_field.to_sym]
+        specs[sub_property] || specs[sub_property.to_sym]
       end
 
-      # Populated [sub_field, value] pairs for one entry; blanks dropped.
+      # Populated [sub_property, value] pairs for one entry; blanks dropped.
       def entry_to_pairs(entry)
         return [] unless entry.respond_to?(:each_pair) || entry.is_a?(::Hash)
         entry.to_h.each_with_object([]) do |(key, value), memo|
@@ -125,8 +125,8 @@ def entry_to_pairs(entry)
         end
       end
 
-      def sub_field_label(sub_field)
-        I18n.t("hyrax.compound_fields.#{field}.#{sub_field}", default: sub_field.to_s.humanize)
+      def sub_property_label(sub_property)
+        I18n.t("hyrax.compound_fields.#{field}.#{sub_property}", default: sub_property.to_s.humanize)
       end
     end
   end
diff --git a/app/search_builders/hyrax/compound_work_picker_builder.rb b/app/search_builders/hyrax/compound_work_picker_builder.rb
index 78299d3f50..7c215df118 100644
--- a/app/search_builders/hyrax/compound_work_picker_builder.rb
+++ b/app/search_builders/hyrax/compound_work_picker_builder.rb
@@ -2,7 +2,7 @@
 
 module Hyrax
   ##
-  # Search builder for the compound `work_or_url` sub-field's work picker. Finds
+  # Search builder for the compound `work_or_url` sub-property's work picker. Finds
   # works the current user can read (it subclasses {Hyrax::SearchBuilder}, so
   # permission filtering is retained), matching any indexed query term OR a
   # partial/prefix title.
diff --git a/app/services/hyrax/compound_entry_validation.rb b/app/services/hyrax/compound_entry_validation.rb
index b8d5d04e26..737ebe906a 100644
--- a/app/services/hyrax/compound_entry_validation.rb
+++ b/app/services/hyrax/compound_entry_validation.rb
@@ -11,7 +11,8 @@ module Hyrax
   #
   # Rules (driven by the normalized definition from {Hyrax::CompoundSchema}):
   #   * a compound marked `required` must have at least one populated row;
-  #   * every populated row must fill all of the compound's `required` sub-fields.
+  #   * every populated row must fill all of the compound's `required`
+  #     sub-properties.
   #
   # Rows are the post-populator persisted hashes (all-blank rows already
   # dropped), so a no-required compound with no rows is valid.
@@ -25,11 +26,11 @@ def initialize(definition, entries)
 
     # @return [Array<Hash>] one violation per problem, each
     #   `{ type:, missing: [keys] }`. Empty when the compound is valid.
-    #   `type` is `:required_but_empty` or `:missing_required_subfields`.
+    #   `type` is `:required_but_empty` or `:missing_required_subproperties`.
     def violations
       return [{ type: :required_but_empty, missing: required_keys }] if required_but_empty?
 
-      rows_missing_required.map { |missing| { type: :missing_required_subfields, missing: missing } }
+      rows_missing_required.map { |missing| { type: :missing_required_subproperties, missing: missing } }
     end
 
     # @return [Boolean]
@@ -42,7 +43,7 @@ def valid?
     attr_reader :definition, :entries
 
     def required_keys
-      definition.fetch(:subfields, {}).select { |_k, spec| spec[:required] }.keys
+      definition.fetch(:subproperties, {}).select { |_k, spec| spec[:required] }.keys
     end
 
     def required_but_empty?
diff --git a/app/services/hyrax/compound_schema.rb b/app/services/hyrax/compound_schema.rb
index d45fe1ece6..51a63ea8c4 100644
--- a/app/services/hyrax/compound_schema.rb
+++ b/app/services/hyrax/compound_schema.rb
@@ -5,9 +5,10 @@ module Hyrax
   # @api public
   #
   # Reads the compound metadata declarations off a resource's schema. A compound
-  # is a `type: hash, multiple: true` attribute carrying a `subfields:` map; the
-  # declaration drives the generic form, indexer, and renderer so a hierarchical
-  # field can be defined in YAML alone. See documentation/forms/compound_fields.md.
+  # is a `type: hash, multiple: true` attribute carrying a `subproperties:` map;
+  # the declaration drives the generic form, indexer, and renderer so a
+  # hierarchical field can be defined in YAML alone. See
+  # documentation/forms/compound_fields.md.
   #
   # Declarations are read from each attribute's Dry type `meta`, which both
   # schema loaders populate identically, so the result is the same in both flex
@@ -86,7 +87,7 @@ def initialize(*schema_sources)
 
     ##
     # @return [Boolean] whether the given attribute is a compound (declares
-    #   `subfields:`)
+    #   `subproperties:`)
     def compound?(attribute_name)
       definitions.key?(attribute_name.to_sym)
     end
@@ -122,8 +123,8 @@ def card?(attribute_name)
     # @param [#to_sym] attribute_name
     #
     # @return [Hash{Symbol => Object}, nil] the compound's declaration:
-    #   `{ subfields:, groups:, index_subfields: }`, or nil when the attribute
-    #   is not a compound.
+    #   `{ subproperties:, groups: }`, or nil when the attribute is not a
+    #   compound.
     def definition_for(attribute_name)
       definitions[attribute_name.to_sym]
     end
@@ -131,12 +132,12 @@ def definition_for(attribute_name)
     ##
     # @param [#to_sym] attribute_name
     #
-    # @return [Array<String>] the ordered sub-field keys declared for the
+    # @return [Array<String>] the ordered sub-property keys declared for the
     #   compound (empty when not a compound).
-    def subfield_keys(attribute_name)
+    def subproperty_keys(attribute_name)
       definition = definition_for(attribute_name)
       return [] unless definition
-      definition[:subfields].keys
+      definition[:subproperties].keys
     end
 
     ##
@@ -147,12 +148,12 @@ def required?(attribute_name)
     end
 
     ##
-    # @return [Array<String>] the sub-field keys declared `required: true` for
+    # @return [Array<String>] the sub-property keys declared `required: true` for
     #   the compound (each must be filled in every populated row).
-    def required_subfield_keys(attribute_name)
+    def required_subproperty_keys(attribute_name)
       definition = definition_for(attribute_name)
       return [] unless definition
-      definition[:subfields].select { |_key, spec| spec[:required] }.keys
+      definition[:subproperties].select { |_key, spec| spec[:required] }.keys
     end
 
     ##
@@ -170,10 +171,10 @@ def build_definitions
           next if meta.nil? || memo.key?(name)
 
           config = meta.with_indifferent_access
-          subfields = config['subfields']
-          next if subfields.blank?
+          subproperties = config['subproperties']
+          next if subproperties.blank?
 
-          memo[name] = normalize(config, subfields)
+          memo[name] = normalize(config, subproperties)
         end
       end
     end
@@ -193,14 +194,14 @@ def name_meta_pairs(schema)
 
     # Normalizes the raw declaration into the symbol-keyed shape the form,
     # indexer, and renderer consume. See documentation/forms/compound_fields.md
-    # for the meaning of each sub-field key.
-    def normalize(config, subfields)
-      sub = subfields.each_with_object({}) { |(key, opts), memo| memo[key.to_s] = normalize_subfield(opts) }
+    # for the meaning of each sub-property key.
+    def normalize(config, subproperties)
+      sub = subproperties.each_with_object({}) { |(key, opts), memo| memo[key.to_s] = normalize_subproperty(opts) }
 
       view = config['view']
       display_mode = view.is_a?(Hash) && view['display'].to_s == 'card' ? :card : :inline
 
-      { subfields: sub,
+      { subproperties: sub,
         groups: normalize_groups(config['groups'], sub.keys),
         display_mode: display_mode,
         required: compound_required?(config),
@@ -215,7 +216,7 @@ def normalize_display_label(config)
       raw.is_a?(Hash) ? raw.with_indifferent_access : { default: raw.to_s }.with_indifferent_access
     end
 
-    def normalize_subfield(opts)
+    def normalize_subproperty(opts)
       opts = (opts.is_a?(Hash) ? opts : {}).with_indifferent_access
       { type: (opts['type'] || 'string').to_s,
         authority: opts['authority']&.to_s,
diff --git a/app/services/hyrax/compound_subfield_labeler.rb b/app/services/hyrax/compound_subproperty_labeler.rb
similarity index 79%
rename from app/services/hyrax/compound_subfield_labeler.rb
rename to app/services/hyrax/compound_subproperty_labeler.rb
index 4d0e2d4663..caed10e306 100644
--- a/app/services/hyrax/compound_subfield_labeler.rb
+++ b/app/services/hyrax/compound_subproperty_labeler.rb
@@ -4,14 +4,14 @@ module Hyrax
   ##
   # @api public
   #
-  # Resolves a `controlled` compound sub-field's stored id to its display term
-  # (via inline `values:` or a QA `authority:`). Non-controlled sub-fields and
+  # Resolves a `controlled` compound sub-property's stored id to its display term
+  # (via inline `values:` or a QA `authority:`). Non-controlled sub-properties and
   # ids with no matching term fall back to the value itself.
-  class CompoundSubfieldLabeler
+  class CompoundSubpropertyLabeler
     ##
-    # @param spec [Hash, nil] the normalized sub-field spec
+    # @param spec [Hash, nil] the normalized sub-property spec
     #   (`{ type:, authority:, values: }`) from {Hyrax::CompoundSchema}
-    # @param value [Object] the stored value (id for controlled sub-fields)
+    # @param value [Object] the stored value (id for controlled sub-properties)
     #
     # @return [String] the term to display
     def self.label_for(spec, value)
@@ -35,7 +35,7 @@ def self.label_from_values(values, value)
     def self.label_from_authority(authority_name, value)
       Hyrax::TolerantSelectService.new(authority_name).label(value.to_s) { value.to_s }
     rescue StandardError => e
-      Hyrax.logger.debug("CompoundSubfieldLabeler: #{authority_name}: #{e.message}")
+      Hyrax.logger.debug("CompoundSubpropertyLabeler: #{authority_name}: #{e.message}")
       value.to_s
     end
     private_class_method :label_from_authority
diff --git a/app/services/hyrax/compound_work_resolver.rb b/app/services/hyrax/compound_work_resolver.rb
index f25235b94f..b4cdec0a18 100644
--- a/app/services/hyrax/compound_work_resolver.rb
+++ b/app/services/hyrax/compound_work_resolver.rb
@@ -4,7 +4,7 @@ module Hyrax
   ##
   # @api public
   #
-  # Helpers for the `work_or_url` compound sub-field, whose stored value is
+  # Helpers for the `work_or_url` compound sub-property, whose stored value is
   # either an external URL or an internal work id. Distinguishes the two and
   # resolves an internal work id to a display title (from Solr) and a show path.
   class CompoundWorkResolver
diff --git a/app/services/hyrax/flexible_schema_validator_service.rb b/app/services/hyrax/flexible_schema_validator_service.rb
index 45db289b9c..f79a3c434d 100644
--- a/app/services/hyrax/flexible_schema_validator_service.rb
+++ b/app/services/hyrax/flexible_schema_validator_service.rb
@@ -134,8 +134,8 @@ def validate_redirects
     end
 
     # Validates compound (hierarchical) metadata properties — those declaring
-    # `subfields:` — for well-formed sub-fields and correct (per-sub-field)
-    # indexing declaration.
+    # `subproperties:` — for well-formed sub-properties and correct
+    # (per-sub-property) indexing declaration.
     #
     # @return [void]
     def validate_compound
diff --git a/app/services/hyrax/flexible_schema_validators/compound_validator.rb b/app/services/hyrax/flexible_schema_validators/compound_validator.rb
index e2bda68a32..0089f2de06 100644
--- a/app/services/hyrax/flexible_schema_validators/compound_validator.rb
+++ b/app/services/hyrax/flexible_schema_validators/compound_validator.rb
@@ -6,9 +6,9 @@ module FlexibleSchemaValidators
     # @api private
     #
     # Validates compound metadata properties (a `type: hash` property declaring
-    # `subfields:` — see {Hyrax::CompoundSchema}) in an m3 profile at save time,
-    # so a misconfiguration fails with a clear message instead of producing dead
-    # Solr fields or unrenderable values. See
+    # `subproperties:` — see {Hyrax::CompoundSchema}) in an m3 profile at save
+    # time, so a misconfiguration fails with a clear message instead of producing
+    # dead Solr fields or unrenderable values. See
     # documentation/forms/compound_fields.md for the rules.
     class CompoundValidator
       ##
@@ -22,44 +22,44 @@ def initialize(profile:, errors:)
       # @return [void]
       def validate!
         compound_properties.each do |name, config|
-          validate_subfields(name, config['subfields'])
+          validate_subproperties(name, config['subproperties'])
           validate_no_top_level_indexing(name, config)
         end
       end
 
       private
 
-      # Compounds are detected by `subfields:` presence (not `type`), so other
-      # hash fields like redirects stay out of scope.
+      # Compounds are detected by `subproperties:` presence (not `type`), so
+      # other hash fields like redirects stay out of scope.
       def compound_properties
         (@profile&.dig('properties') || {}).select do |_name, config|
-          config.is_a?(Hash) && config['subfields'].present?
+          config.is_a?(Hash) && config['subproperties'].present?
         end
       end
 
-      def validate_subfields(name, subfields)
-        unless subfields.is_a?(Hash)
-          @errors << t('subfields_not_hash', property: name)
+      def validate_subproperties(name, subproperties)
+        unless subproperties.is_a?(Hash)
+          @errors << t('subproperties_not_hash', property: name)
           return
         end
 
-        subfields.each { |sub_name, sub_config| validate_subfield(name, sub_name, sub_config) }
+        subproperties.each { |sub_name, sub_config| validate_subproperty(name, sub_name, sub_config) }
       end
 
-      def validate_subfield(name, sub_name, sub_config)
+      def validate_subproperty(name, sub_name, sub_config)
         unless sub_config.is_a?(Hash)
-          @errors << t('subfield_not_hash', property: name, subfield: sub_name, actual: sub_config.class.to_s)
+          @errors << t('subproperty_not_hash', property: name, subproperty: sub_name, actual: sub_config.class.to_s)
           return
         end
 
         return unless sub_config['type'].to_s == 'controlled'
         return if sub_config['authority'].present? || sub_config['values'].present?
 
-        @errors << t('controlled_without_source', property: name, subfield: sub_name)
+        @errors << t('controlled_without_source', property: name, subproperty: sub_name)
       end
 
       # A top-level `indexing:` would point the catalog at a `<compound>_tesim`
-      # field the indexer never writes; indexing is per sub-field.
+      # field the indexer never writes; indexing is per sub-property.
       def validate_no_top_level_indexing(name, config)
         return if config['indexing'].blank?
         @errors << t('top_level_indexing', property: name)
diff --git a/app/services/hyrax/schema_loader.rb b/app/services/hyrax/schema_loader.rb
index a23deb946c..9641f1a115 100644
--- a/app/services/hyrax/schema_loader.rb
+++ b/app/services/hyrax/schema_loader.rb
@@ -162,7 +162,7 @@ def self.of(type)
       #
       # Recognized values:
       #   - `id`, `uri`, `date_time` — Valkyrie type shortcuts.
-      #   - `hash` — for attributes whose entries carry multiple sub-fields
+      #   - `hash` — for attributes whose entries carry multiple sub-properties
       #     (e.g. redirects, with path / canonical / sequence). Use this
       #     instead of nesting a Valkyrie::Resource. See
       #     `documentation/redirects.md` for a worked example.
diff --git a/app/validators/hyrax/compound_entry_validator.rb b/app/validators/hyrax/compound_entry_validator.rb
index eea7da423e..5b47afc1da 100644
--- a/app/validators/hyrax/compound_entry_validator.rb
+++ b/app/validators/hyrax/compound_entry_validator.rb
@@ -3,7 +3,8 @@
 module Hyrax
   # Validates every compound (hierarchical) metadata attribute on a form,
   # blocking save when a required compound has no row or a populated row omits a
-  # required sub-field. Adds one error per compound, keyed on the compound name.
+  # required sub-property. Adds one error per compound, keyed on the compound
+  # name.
   #
   # Record-level (not an EachValidator) because the compound set is schema-driven
   # and not known at form-class-definition time. The per-compound rules live in
@@ -49,14 +50,14 @@ def validate_compound(record, name, definition)
     def message_for(name, violation)
       I18n.t("hyrax.compound_fields.errors.#{violation[:type]}",
              compound: compound_label(name),
-             fields: subfield_labels(name, violation[:missing]))
+             fields: subproperty_labels(name, violation[:missing]))
     end
 
     def compound_label(name)
       I18n.t("hyrax.compound_fields.#{name}.label", default: name.to_s.humanize)
     end
 
-    def subfield_labels(name, keys)
+    def subproperty_labels(name, keys)
       Array(keys).map do |key|
         I18n.t("hyrax.compound_fields.#{name}.#{key}", default: key.to_s.humanize)
       end.join(', ')
diff --git a/app/views/hyrax/compounds/_compound_row.html.erb b/app/views/hyrax/compounds/_compound_row.html.erb
index a5ea6cd834..c3bdf0bd3c 100644
--- a/app/views/hyrax/compounds/_compound_row.html.erb
+++ b/app/views/hyrax/compounds/_compound_row.html.erb
@@ -3,17 +3,17 @@
     Locals:
       f                  - form builder for the parent resource
       compound_name      - Symbol, e.g. :contributors
-      definition         - Hash{ subfields:, groups:, index_subfields: }
+      definition         - Hash{ subproperties:, groups: }
       row                - Hash of persisted values, or nil for a new row
       index              - Integer position, or the literal "__INDEX__"
                            placeholder when rendered inside the JS template
       row_label_singular - "Contributor", "License", etc.
 
-    Each sub-field renders according to its declared `type:` (string,
+    Each sub-property renders according to its declared `type:` (string,
     controlled, url, work_or_url). db_table / geocode are future types; the
     `else` branch is the extension seam.
 %>
-<% subfields = definition[:subfields] %>
+<% subproperties = definition[:subproperties] %>
 <% groups = definition[:groups] %>
 <% row_position = index.is_a?(String) ? '' : (index.to_i + 1).to_s %>
 <% row_value = ->(key) { row.is_a?(Hash) ? (row[key] || row[key.to_sym]) : nil } %>
@@ -34,22 +34,22 @@
         <h4 class="h6 text-muted text-uppercase mt-1 mb-2"><%= group[:label] %></h4>
       <% end %>
       <div class="form-row">
-        <% group[:fields].each do |sub_field| %>
-          <% spec = subfields[sub_field] || { type: 'string' } %>
-          <% input_id = "#{f.object_name}_#{compound_name}_attributes_#{index}_#{sub_field}" %>
-          <% input_name = "#{f.object_name}[#{compound_name}_attributes][#{index}][#{sub_field}]" %>
-          <% value = row_value.call(sub_field) %>
+        <% group[:fields].each do |sub_property| %>
+          <% spec = subproperties[sub_property] || { type: 'string' } %>
+          <% input_id = "#{f.object_name}_#{compound_name}_attributes_#{index}_#{sub_property}" %>
+          <% input_name = "#{f.object_name}[#{compound_name}_attributes][#{index}][#{sub_property}]" %>
+          <% value = row_value.call(sub_property) %>
           <div class="form-group col-md-<%= group.fetch(:cols, 6) %>">
             <%= label_tag input_id, class: 'form-label small text-muted' do %>
-              <%= compound_subfield_label(compound_name, sub_field) %><%
+              <%= compound_subproperty_label(compound_name, sub_property) %><%
                 if spec[:required] %><abbr title="<%= t('simple_form.required.text', default: 'required') %>" class="required text-danger">*</abbr><% end %>
             <% end %>
             <% case spec[:type] %>
             <% when 'controlled' %>
               <% select_classes = ['form-control', 'form-control-sm'] %>
-              <% select_classes << 'force-select' if compound_subfield_forced?(spec, value) %>
+              <% select_classes << 'force-select' if compound_subproperty_forced?(spec, value) %>
               <%= select_tag input_name,
-                             options_for_select(compound_subfield_options(spec, value), value),
+                             options_for_select(compound_subproperty_options(spec, value), value),
                              id: input_id,
                              include_blank: true,
                              class: select_classes.join(' ') %>
diff --git a/app/views/hyrax/compounds/_compound_section.html.erb b/app/views/hyrax/compounds/_compound_section.html.erb
index 0eec2654dd..bd80b032f7 100644
--- a/app/views/hyrax/compounds/_compound_section.html.erb
+++ b/app/views/hyrax/compounds/_compound_section.html.erb
@@ -5,10 +5,10 @@
     Locals:
       f             - form builder for the parent resource
       compound_name - Symbol, e.g. :contributors
-      definition    - Hash{ subfields:, groups: } from CompoundSchema#definition_for
+      definition    - Hash{ subproperties:, groups: } from CompoundSchema#definition_for
       display_label - String shown as the section heading
 
-    Form params: <obj>[<compound>_attributes][<index>][<sub_field>]
+    Form params: <obj>[<compound>_attributes][<index>][<sub_property>]
 %>
 <%# Read rows from the form when it exposes the compound reader, else the model. %>
 <% source = f.object.respond_to?(compound_name) ? f.object : f.object.model %>
diff --git a/config/locales/hyrax.en.yml b/config/locales/hyrax.en.yml
index 14f6d5498e..98d9f54139 100644
--- a/config/locales/hyrax.en.yml
+++ b/config/locales/hyrax.en.yml
@@ -864,7 +864,7 @@ en:
       remove_row_with_label: Remove %{label}
       errors:
         required_but_empty: "%{compound} requires at least one entry"
-        missing_required_subfields: "Each %{compound} entry requires: %{fields}"
+        missing_required_subproperties: "Each %{compound} entry requires: %{fields}"
       participants:
         label: Participants
         title: Title
@@ -1417,10 +1417,10 @@ en:
     flexible_schema_validators:
       compound_validator:
         errors:
-          subfields_not_hash: "m3 profile compound property `%{property}` must declare `subfields` as a mapping of sub-field name to its configuration"
-          subfield_not_hash: "m3 profile compound property `%{property}` sub-field `%{subfield}` must be a mapping (got `%{actual}`)"
-          controlled_without_source: "m3 profile compound property `%{property}` sub-field `%{subfield}` is `type: controlled` but declares neither `authority` nor `values`"
-          top_level_indexing: "m3 profile compound property `%{property}` must not declare top-level `indexing`; declare `indexing` (or `index_keys`) on each sub-field instead"
+          subproperties_not_hash: "m3 profile compound property `%{property}` must declare `subproperties` as a mapping of sub-property name to its configuration"
+          subproperty_not_hash: "m3 profile compound property `%{property}` sub-property `%{subproperty}` must be a mapping (got `%{actual}`)"
+          controlled_without_source: "m3 profile compound property `%{property}` sub-property `%{subproperty}` is `type: controlled` but declares neither `authority` nor `values`"
+          top_level_indexing: "m3 profile compound property `%{property}` must not declare top-level `indexing`; declare `indexing` (or `index_keys`) on each sub-property instead"
       redirects_validator:
         errors:
           invalid_available_on: "m3 profile `redirects` property must be available on at least one work or collection class declared in this profile"
diff --git a/config/metadata/compound_metadata.yaml b/config/metadata/compound_metadata.yaml
index c62dc16793..5f091cf1d8 100644
--- a/config/metadata/compound_metadata.yaml
+++ b/config/metadata/compound_metadata.yaml
@@ -1,13 +1,13 @@
 # Sample compound (hierarchical) metadata that ships with Hyrax.
 #
 # Each attribute here is a compound: a `type: hash, multiple: true` field whose
-# entries are plain hashes of named sub-fields. The sub-fields are declared in
-# `subfields:` and rendered, populated, and indexed generically by the compound
+# entries are plain hashes of named sub-properties. The sub-properties are declared in
+# `subproperties:` and rendered, populated, and indexed generically by the compound
 # foundation — no per-field Ruby or ERB. See
 # `documentation/forms/compound_fields.md`.
 #
 # These are intentionally generic examples demonstrating the supported
-# sub-field input types (open-entry `string` and `controlled` vocabulary).
+# sub-property input types (open-entry `string` and `controlled` vocabulary).
 # Applications can add their own compounds the same way (in this file, an
 # app-level schema, or the m3 profile under HYRAX_FLEXIBLE=true) and may remove
 # these samples by setting `Hyrax.config.compound_metadata_enabled = false`.
@@ -20,9 +20,9 @@ attributes:
     predicate: http://id.loc.gov/vocabulary/relators/asn
     form:
       primary: false
-    subfields:
-      # Indexing is declared per sub-field via `index_keys:` (the literal Solr
-      # field names + suffixes), exactly like scalar fields. A sub-field with
+    subproperties:
+      # Indexing is declared per sub-property via `index_keys:` (the literal Solr
+      # field names + suffixes), exactly like scalar fields. A sub-property with
       # no `index_keys:` is display-only (rendered from the json blob, not its
       # own searchable field). `display: false` would omit it from the blob.
       title: { type: string }
@@ -30,7 +30,7 @@ attributes:
         type: string
         required: true
         index_keys: [participant_name_sim, participant_name_tesim]
-      # A controlled sub-field can take its options from an inline list (below)
+      # A controlled sub-property can take its options from an inline list (below)
       # or from an existing QA local authority (`authority: <name>`).
       participant_role:
         type: controlled
@@ -51,7 +51,7 @@ attributes:
     predicate: http://purl.org/dc/terms/identifier
     form:
       primary: false
-    subfields:
+    subproperties:
       identifier:
         type: string
         required: true
@@ -64,7 +64,7 @@ attributes:
     view:
       render_as: compound
       html_dl: true
-  # A rights grouping demonstrating controlled sub-fields backed by *existing*
+  # A rights grouping demonstrating controlled sub-properties backed by *existing*
   # QA local authorities (rather than inline `values:`), alongside an
   # open-ended note.
   compound_rights:
@@ -75,7 +75,7 @@ attributes:
       default: Rights
     form:
       primary: false
-    subfields:
+    subproperties:
       rights_statement:
         type: controlled
         authority: rights_statements
@@ -90,7 +90,7 @@ attributes:
     view:
       render_as: compound
       html_dl: true
-  # A related-item grouping demonstrating the `work_or_url` sub-field: the user
+  # A related-item grouping demonstrating the `work_or_url` sub-property: the user
   # searches for an internal work (typeahead) OR types an external URL. The
   # stored value is a work id or a URL; show pages link to the internal work
   # (by title) or auto-link the external URL.
@@ -100,7 +100,7 @@ attributes:
     predicate: http://purl.org/dc/terms/relation
     form:
       primary: false
-    subfields:
+    subproperties:
       related_item:
         type: work_or_url
         required: true
diff --git a/config/metadata_profiles/m3_profile.yaml b/config/metadata_profiles/m3_profile.yaml
index 1bb100d144..3d1acb5a21 100644
--- a/config/metadata_profiles/m3_profile.yaml
+++ b/config/metadata_profiles/m3_profile.yaml
@@ -954,7 +954,7 @@ properties:
     property_uri: http://vocabulary.samvera.org/ns#transcriptIds
   # Sample compound (hierarchical) metadata shipped with Hyrax. Each is a
   # `type: hash, multiple: true` property whose entries are hashes of the
-  # `subfields:` keys, rendered/populated/indexed generically by the compound
+  # `subproperties:` keys, rendered/populated/indexed generically by the compound
   # foundation. See documentation/forms/compound_fields.md.
   participants:
     available_on:
@@ -969,8 +969,8 @@ properties:
     form:
       primary: false
     property_uri: http://id.loc.gov/vocabulary/relators/asn
-    subfields:
-      # Indexing per sub-field via `indexing:` (literal Solr field names), the
+    subproperties:
+      # Indexing per sub-property via `indexing:` (literal Solr field names), the
       # same mechanism scalar properties use. No `indexing:` => display-only.
       title: { type: string }
       participant_name:
@@ -1000,7 +1000,7 @@ properties:
     form:
       primary: false
     property_uri: http://purl.org/dc/terms/identifier
-    subfields:
+    subproperties:
       identifier:
         type: string
         required: true
@@ -1026,7 +1026,7 @@ properties:
     form:
       primary: false
     property_uri: http://purl.org/dc/terms/rights
-    subfields:
+    subproperties:
       rights_statement:
         type: controlled
         authority: rights_statements
@@ -1054,7 +1054,7 @@ properties:
     form:
       primary: false
     property_uri: http://purl.org/dc/terms/relation
-    subfields:
+    subproperties:
       related_item:
         type: work_or_url
         required: true
diff --git a/documentation/forms/compound_fields.md b/documentation/forms/compound_fields.md
index 6d0cb5d8e7..50b0b5829e 100644
--- a/documentation/forms/compound_fields.md
+++ b/documentation/forms/compound_fields.md
@@ -1,7 +1,7 @@
 # Compound (hierarchical) metadata fields
 
 A **compound field** is a metadata attribute whose value is a list of entries,
-where each entry is itself a small set of named **sub-fields**. It is the
+where each entry is itself a small set of named **sub-properties**. It is the
 Hyrax foundation for hierarchical metadata: contributors with a name, role and
 identifier; dates with a value and type; funding references with a funder name
 and award number; and so on.
@@ -15,14 +15,14 @@ and behave identically in both flex modes.
 ## Declaring a compound
 
 A compound is a `type: hash, multiple: true` attribute that also carries a
-`subfields:` map:
+`subproperties:` map:
 
 ```yaml
 contributors:
   type: hash
   multiple: true
   predicate: https://prvoices.org/terms/contributor
-  subfields:
+  subproperties:
     given_name:
       type: string
       index_keys: [contributors_given_name_sim, contributors_given_name_tesim]
@@ -42,7 +42,7 @@ contributors:
 
 In the m3 profile the same declaration uses `data_type: array`, `type: hash`,
 and `available_on: class:` to scope the property, with the identical
-`subfields:` / `groups:` keys; sub-field index targets are declared with
+`subproperties:` / `groups:` keys; sub-property index targets are declared with
 `indexing:` (the flexible-mode spelling of `index_keys:`).
 
 > **Flexible mode:** the active schema is the `Hyrax::FlexibleSchema` row in the
@@ -53,9 +53,9 @@ and `available_on: class:` to scope the property, with the identical
 > singleton class at load time, so a stale running process serves the old
 > attribute set even when the profile YAML is current.
 
-### `subfields:`
+### `subproperties:`
 
-An ordered map of `sub_field_key => { type:, ... }`. Supported `type:` values:
+An ordered map of `sub_property_key => { type:, ... }`. Supported `type:` values:
 
 | `type:`      | Renders as          | Notes |
 |--------------|---------------------|-------|
@@ -64,10 +64,10 @@ An ordered map of `sub_field_key => { type:, ... }`. Supported `type:` values:
 | `work_or_url` | select2 typeahead → linked on show | Searches internal works (via the `compound_works` QA authority, backed by `Hyrax::CompoundWorkPickerBuilder`) **or** accepts a typed external URL. The stored value is a work id or a URL; on show, a work id links to the work's show page with its title (resolved by `Hyrax::CompoundWorkResolver`), a URL is auto-linked. |
 | `controlled` | `<select>` dropdown | Options come from either an inline `values:` list or a QA local authority named by `authority:` (see below). The row's stored value is preserved even if it is no longer offered, matching the `include_current_value` convention of the ordinary controlled-field partials. |
 
-A `controlled` sub-field sources its options one of two ways:
+A `controlled` sub-property sources its options one of two ways:
 
 ```yaml
-subfields:
+subproperties:
   # (a) inline list — no authority file needed
   agent_role:
     type: controlled
@@ -91,7 +91,7 @@ both are given, `values:` wins. Authority options are read through
 `Hyrax::TolerantSelectService`, so an authority file that omits the `active:`
 key behaves the same as it does for ordinary fields (terms default to active).
 
-A `work_or_url` sub-field's work search is broader than the stock "my works"
+A `work_or_url` sub-property's work search is broader than the stock "my works"
 picker: `Hyrax::CompoundWorkPickerBuilder` matches a typed term against any
 indexed query field **or** a partial/prefix title (so "jour" matches "Journal
 of …"), restricted to works. It subclasses `Hyrax::SearchBuilder`, so the
@@ -101,44 +101,44 @@ can read. The picker is mounted as the `compound_works` QA authority at
 
 `db_table` (a typeahead backed by an ActiveRecord lookup table, with
 add-new) and `geocode` (a Geonames/coordinate lookup, like `based_near`) are
-planned additional sub-field types; the form's row partial has an explicit
+planned additional sub-property types; the form's row partial has an explicit
 extension point for them.
 
 ### `groups:` (optional)
 
-Visual clustering of sub-fields within each entry's card. Each group is
+Visual clustering of sub-properties within each entry's card. Each group is
 `{ label:, cols:, fields: [...] }`, where `cols` is the Bootstrap column width
-(out of 12) for each field in the group. When omitted, all sub-fields render in
+(out of 12) for each field in the group. When omitted, all sub-properties render in
 a single unlabeled group.
 
-### Indexing sub-fields (`index_keys:` / `indexing:`)
+### Indexing sub-properties (`index_keys:` / `indexing:`)
 
-Indexing is declared **per sub-field**, exactly as for scalar fields: list the
-literal Solr field names the sub-field's value should be written to, under
+Indexing is declared **per sub-property**, exactly as for scalar fields: list the
+literal Solr field names the sub-property's value should be written to, under
 `index_keys:` (non-flexible mode) or `indexing:` (flexible mode). The Solr
 suffix on each name chooses the behavior — `_tesim` (stored + searchable,
 multi-valued), `_sim` (facetable, not stored), `_ssim` (stored + facetable),
 etc. — the same conventions scalar fields use. The author picks both the field
 names and the suffixes.
 
-A sub-field with no `index_keys:`/`indexing:` is **not** written to a Solr field
+A sub-property with no `index_keys:`/`indexing:` is **not** written to a Solr field
 of its own; it can still appear on the show page (see below). As with scalar
 fields, the non-field control tokens (`facetable`, `stored_searchable`,
 `admin_only`, `editor_only`) are filtered out if present.
 
-Indexing a sub-field makes it **searchable/facetable** in Solr; it does **not**
+Indexing a sub-property makes it **searchable/facetable** in Solr; it does **not**
 make it appear as a column on the catalog/search-results page. The catalog
 renders only the fields explicitly registered with Blacklight
-(`config.add_index_field`) — compound sub-fields are not registered by default.
-To show a sub-field in search results, register its Solr field name in your
+(`config.add_index_field`) — compound sub-properties are not registered by default.
+To show a sub-property in search results, register its Solr field name in your
 `CatalogController` (e.g.
 `config.add_index_field 'agent_name_tesim', label: 'Agent'`). The show page and
 edit form render compounds regardless.
 
 ### `display:` (optional, default true)
 
-Controls whether a sub-field is included in the `<compound>_json_ss` blob that
-the show page renders from. Combined with indexing, each sub-field can be:
+Controls whether a sub-property is included in the `<compound>_json_ss` blob that
+the show page renders from. Combined with indexing, each sub-property can be:
 
 - **display + searchable** — has `index_keys:` and `display` not false
 - **display-only** — no `index_keys:` (renders on show, not separately searchable)
@@ -147,14 +147,14 @@ the show page renders from. Combined with indexing, each sub-field can be:
 
 ### `required:` (optional, default false)
 
-Marks a sub-field as required within each populated row, or — when set on the
+Marks a sub-property as required within each populated row, or — when set on the
 compound itself — marks the whole compound as required. See
-[Required sub-fields](#required-sub-fields) below.
+[Required sub-properties](#required-sub-properties) below.
 
 ## Persisted shape
 
 A compound persists as an array of plain string-keyed hashes — exactly the
-keys declared in `subfields:`:
+keys declared in `subproperties:`:
 
 ```ruby
 work.contributors
@@ -182,13 +182,13 @@ per-compound code:
 - **Form → storage conversion** — `Hyrax::CompoundFieldBehavior` registers a
   virtual `<name>_attributes` property per compound and a shared populator that
   builds the persisted array, dropping `_destroy` and all-blank rows and
-  keeping only declared sub-field keys.
+  keeping only declared sub-property keys.
 - **Read-path defense** — `Hyrax::CompoundNormalization`, included on the
   resource, guards against Valkyrie's single-element-array key-splay quirk on
   reload.
 - **Indexing** — `Hyrax::Indexers::CompoundIndexer`, included on the indexer,
-  writes each sub-field's value to the Solr field names it declares
-  (`index_keys:`/`indexing:`) and stores the displayable sub-fields as a
+  writes each sub-property's value to the Solr field names it declares
+  (`index_keys:`/`indexing:`) and stores the displayable sub-properties as a
   `<compound>_json_ss` blob for the show page.
 
 A resource and its indexer opt in with one include each:
@@ -208,7 +208,7 @@ end
 ## Sample compounds shipped with Hyrax
 
 Hyrax ships sample compounds on **works and collections** by default,
-demonstrating the supported sub-field types:
+demonstrating the supported sub-property types:
 
 - **`participants`** — `title`, `participant_name`, and a controlled
   `participant_role` (inline `values:`). A person or organization associated
@@ -234,22 +234,22 @@ or override the samples.
 ## Show-page rendering
 
 Because the show page renders from Solr (not the live resource), the indexer
-also stores each compound's ordered rows (limited to sub-fields with `display:`
+also stores each compound's ordered rows (limited to sub-properties with `display:`
 not false) as a single JSON field (`<compound>_json_ss`). The SolrDocument
 defines a `<compound>` reader for each such blob it carries — so an
 application's own compounds work with no per-document declaration — that
 parses it back into an array of hashes, and the generic
 `Hyrax::Renderers::CompoundAttributeRenderer` (selected by `view: render_as:
-compound`) renders each entry's populated sub-fields as a small definition
+compound`) renders each entry's populated sub-properties as a small definition
 list. Works render compounds through the standard `attribute_to_html` /
 `render_as` path; collections render them through the same shared renderer,
 invoked from the collection show view for terms the presenter reports as
-compounds. Sub-field labels come from the `hyrax.compound_fields.<compound>.<subfield>`
+compounds. Sub-property labels come from the `hyrax.compound_fields.<compound>.<subproperty>`
 i18n keys (humanized fallback).
 
-For a `controlled` sub-field, the show page displays the authority/value-list
-**term**, not the stored id — `Hyrax::CompoundSubfieldLabeler` resolves the id
-through the sub-field's inline `values:` list or its QA `authority:` (falling
+For a `controlled` sub-property, the show page displays the authority/value-list
+**term**, not the stored id — `Hyrax::CompoundSubpropertyLabeler` resolves the id
+through the sub-property's inline `values:` list or its QA `authority:` (falling
 back to the id when no term matches), the same way scalar controlled fields
 display their term.
 
@@ -267,7 +267,7 @@ relationships:
   view:
     render_as: compound
     display: card
-  subfields:
+  subproperties:
     related_item:      { type: work_or_url }
     relationship_type: { type: controlled, authority: relationship_type }
 ```
@@ -292,24 +292,24 @@ path resolves on a collection as on a work.
 In flexible mode, `Hyrax::FlexibleSchemaValidators::CompoundValidator` checks
 compound declarations when an m3 profile is saved/uploaded, so a
 misconfiguration fails with a clear message instead of producing dead Solr
-fields or unrenderable values. It enforces: `subfields:` is a mapping; each
-sub-field config is a mapping; a `type: controlled` sub-field declares an
+fields or unrenderable values. It enforces: `subproperties:` is a mapping; each
+sub-property config is a mapping; a `type: controlled` sub-property declares an
 option source (`authority:` or `values:`); and the compound does **not** carry
-a top-level `indexing:` (indexing is declared per sub-field — a top-level
+a top-level `indexing:` (indexing is declared per sub-property — a top-level
 `indexing:` would point the catalog at a `<compound>_tesim` field the indexer
 never writes).
 
-## Required sub-fields
+## Required sub-properties
 
 A compound declares requiredness at two levels:
 
-- **Sub-field level** — `required: true` on a sub-field means every populated
+- **Sub-property level** — `required: true` on a sub-property means every populated
   row must fill it. A row that fills some-but-not-all of its required
-  sub-fields blocks save (e.g. a relationship row with a related item but no
+  sub-properties blocks save (e.g. a relationship row with a related item but no
   type).
 - **Compound level** — `required: true` on the compound (or, in flexible mode,
   a minimum cardinality of 1) means at least one row must be present to save.
-  An optional compound with no rows is always valid; the sub-field rules only
+  An optional compound with no rows is always valid; the sub-property rules only
   apply to rows the user actually adds.
 
 ```yaml
@@ -317,13 +317,13 @@ relationships:
   type: hash
   multiple: true
   required: true            # the work must have at least one relationship
-  subfields:
+  subproperties:
     related_item:      { type: work_or_url, required: true }
     relationship_type: { type: controlled, authority: relationship_type, required: true }
     note:              { type: string }   # optional
 ```
 
-Required sub-fields and required compounds render a `*` marker on the form
+Required sub-properties and required compounds render a `*` marker on the form
 label. On save, `Hyrax::CompoundEntryValidator` (wired on the resource form,
 gated by `compound_metadata_enabled?`) adds one error per compound, keyed on the
 compound's attribute name, so the failure is reported against that field. The
@@ -333,12 +333,12 @@ The decision logic lives in `Hyrax::CompoundEntryValidation`, a plain object
 decoupled from ActiveModel and Reform — given a compound's definition and its
 rows it returns the violations. That seam keeps the rules reusable (e.g. a
 future Bulkrax-side check) and unit-testable without a form. Note: Bulkrax
-import does not currently run this validation, so a required sub-field can be
+import does not currently run this validation, so a required sub-property can be
 left empty by an import.
 
 ## Validation
 
-Sub-field format and controlled-vocabulary correctness belong in an
+Sub-property format and controlled-vocabulary correctness belong in an
 `ActiveModel::EachValidator` wired through the form's `validation` block — not
 in the populator, whose only job is shape conversion. This mirrors the
 `field_behaviors.md` guidance.
@@ -348,7 +348,7 @@ in the populator, whose only job is shape conversion. This mirrors the
 A compound round-trips through Bulkrax import and export with no additional
 code, using Bulkrax's declarative `nested_attributes: true` field-mapping flag
 (Bulkrax v9.4.3+). Declare the flag on every sibling mapping that shares the
-compound's `object:` value, and keep each mapping key equal to the sub-field
+compound's `object:` value, and keep each mapping key equal to the sub-property
 key. See `field_behaviors.md` for the column conventions. Note: Bulkrax's
 controlled-URI sanitization does not currently descend into compound
-sub-fields.
+sub-properties.
diff --git a/documentation/forms/field_behaviors.md b/documentation/forms/field_behaviors.md
index e150959eb1..95c6d3856c 100644
--- a/documentation/forms/field_behaviors.md
+++ b/documentation/forms/field_behaviors.md
@@ -5,7 +5,7 @@ A **Field Behavior** is a Ruby module mixed into `Hyrax::Forms::ResourceForm` (a
 Use a Field Behavior when you have a property that:
 
 - Is rendered through `accepts_nested_attributes_for` semantics (`<name>_attributes` payload from the form).
-- Persists in a shape the view can't render directly (a hash of sub-fields, a URI string the view wants as a `ControlledVocabulary` instance, a triple of values, etc.).
+- Persists in a shape the view can't render directly (a hash of sub-properties, a URI string the view wants as a `ControlledVocabulary` instance, a triple of values, etc.).
 - Needs the same wiring on every form subclass.
 
 Two examples ship with Hyrax:
@@ -15,8 +15,8 @@ Two examples ship with Hyrax:
 
 This document covers the contract a Field Behavior must satisfy, the decision points for a new behavior, and the worked examples.
 
-> **For new multi-sub-field compounds, prefer the generic, schema-driven path.**
-> A field whose entries are a hash of named sub-fields (each an open-entry
+> **For new multi-sub-property compounds, prefer the generic, schema-driven path.**
+> A field whose entries are a hash of named sub-properties (each an open-entry
 > string or a controlled-vocabulary lookup) can be declared entirely in the
 > schema YAML / m3 profile and rendered, populated, and indexed with no
 > per-field Ruby or ERB — see [`compound_fields.md`](compound_fields.md). The
@@ -138,12 +138,12 @@ When adding a Field Behavior, work through these:
 ### 1. What does each entry look like?
 
 - **Single value per entry** (URI string, scalar): see `BasedNearFieldBehavior`.
-- **Multiple sub-fields per entry** (path + is_display_url; or label + value + lang): see `RedirectsFieldBehavior`.
+- **Multiple sub-properties per entry** (path + is_display_url; or label + value + lang): see `RedirectsFieldBehavior`.
 
 ### 2. Persisted as what?
 
 - **Plain string / scalar** — fine for single-value entries.
-- **Plain hash** with string keys — for multi-field entries. Add the `hash` shortcut to your YAML schema (`type: hash, multiple: true`). Use this *instead* of nesting a Valkyrie::Resource subclass; nested resources round-trip badly through Postgres JSONB (sub-fields strip, parent fields leak).
+- **Plain hash** with string keys — for multi-field entries. Add the `hash` shortcut to your YAML schema (`type: hash, multiple: true`). Use this *instead* of nesting a Valkyrie::Resource subclass; nested resources round-trip badly through Postgres JSONB (sub-properties strip, parent fields leak).
 
 ### 3. Does the view need a presenter?
 
@@ -248,7 +248,7 @@ The populator folds a sibling `redirects_display_url_index` scalar (a single rad
 
 - **Persisted shape:** array of plain hashes (`'path'`, `'is_display_url'`). Declared with `type: hash, multiple: true` in `config/metadata/redirects.yaml`.
 - **View-side shape:** array of `Hyrax::Redirect` presenters, exposing `.path` and `.is_display_url`. The form partial wraps each persisted hash inline rather than via a prepopulator.
-- **Diff from BasedNear:** entries carry multiple sub-fields, so the persisted shape is a hash rather than a string. The populator normalizes paths up front (canonical form lives in storage). The behavior is feature-gated — every callback consults `Hyrax.config.redirects_active?`.
+- **Diff from BasedNear:** entries carry multiple sub-properties, so the persisted shape is a hash rather than a string. The populator normalizes paths up front (canonical form lives in storage). The behavior is feature-gated — every callback consults `Hyrax.config.redirects_active?`.
 
 ## Wiring on `ResourceForm`
 
diff --git a/lib/hyrax/form_fields.rb b/lib/hyrax/form_fields.rb
index a6a823f2be..a0b26880df 100644
--- a/lib/hyrax/form_fields.rb
+++ b/lib/hyrax/form_fields.rb
@@ -47,16 +47,16 @@ def inspect
     private
 
     # Full attribute config per field — carries keys beyond `form:` (e.g.
-    # `subfields:`), unlike form_field_definitions.
+    # `subproperties:`), unlike form_field_definitions.
     def attribute_configs
       @definition_loader.attributes_for(schema: name, version:, contexts:)
     end
 
-    # @return [Boolean] whether the named field declares `subfields:`.
+    # @return [Boolean] whether the named field declares `subproperties:`.
     def compound_field?(configs, field_name)
       type = configs[field_name.to_sym] || configs[field_name.to_s]
       meta = type.respond_to?(:meta) ? type.meta : {}
-      meta.with_indifferent_access['subfields'].present?
+      meta.with_indifferent_access['subproperties'].present?
     rescue StandardError
       false
     end
@@ -70,7 +70,7 @@ def included(descendant)
         descendant.property field_name.to_sym, options.merge(display: options.fetch(:display, true), default: [])
         is_compound = compound_field?(configs, field_name)
         # A compound's requiredness is enforced by Hyrax::CompoundEntryValidator
-        # (which understands per-row sub-field rules); a plain `presence` check
+        # (which understands per-row sub-property rules); a plain `presence` check
         # on the array would both duplicate that and pass on a present-but-empty
         # row. So only scalar fields get the generic presence validator.
         descendant.validates field_name.to_sym, presence: true if options.fetch(:required, false) && !is_compound
diff --git a/spec/forms/concerns/hyrax/compound_field_behavior_spec.rb b/spec/forms/concerns/hyrax/compound_field_behavior_spec.rb
index a416d935fd..01bcc87090 100644
--- a/spec/forms/concerns/hyrax/compound_field_behavior_spec.rb
+++ b/spec/forms/concerns/hyrax/compound_field_behavior_spec.rb
@@ -9,7 +9,7 @@ def self.name
 
       attribute :contributors,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
-                  subfields: {
+                  subproperties: {
                     'given_name' => { 'type' => 'string' },
                     'family_name' => { 'type' => 'string' }
                   }
@@ -55,7 +55,7 @@ def deserialize!(params)
   subject(:form) { form_class.new(model) }
 
   describe '#compound_attributes_populator' do
-    it 'builds plain string-keyed hashes with only declared sub-fields' do
+    it 'builds plain string-keyed hashes with only declared sub-properties' do
       fragment = {
         '0' => { 'given_name' => 'Ada', 'family_name' => 'Lovelace', 'unknown' => 'drop me' },
         '1' => { 'given_name' => 'Alan', 'family_name' => 'Turing' }
diff --git a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
index f955af1f6b..d480c8ceb1 100644
--- a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
+++ b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
@@ -102,10 +102,10 @@
     end
   end
 
-  describe 'required-subfield validation blocks save' do
+  describe 'required-subproperty validation blocks save' do
     # Exercises the real form + Hyrax::CompoundEntryValidator end to end against
     # the *shipped* compound schema (no stub). The shipped samples require
-    # sub-fields within a row (e.g. participants needs participant_name + participant_role,
+    # sub-properties within a row (e.g. participants needs participant_name + participant_role,
     # relationships needs related_item + relationship_type) but none is required
     # at the compound level, so an empty compound is valid. Asserting through the
     # real schema is what catches a validator that reads the form wrapper instead
@@ -123,22 +123,22 @@ def base_errors(form)
       expect(base_errors(form)).to be_empty
     end
 
-    it 'flags a participants row that omits a required sub-field' do
+    it 'flags a participants row that omits a required sub-property' do
       form.validate('participants_attributes' => { '0' => { 'participant_role' => 'Author' } })
       expect(base_errors(form)).to include(a_string_including('Participants'))
     end
 
-    it 'flags a relationships row that omits a required sub-field' do
+    it 'flags a relationships row that omits a required sub-property' do
       form.validate('relationships_attributes' => { '0' => { 'relationship_type' => 'References' } })
       expect(base_errors(form)).to include(a_string_including('Relationships'))
     end
 
-    it 'does not flag participants when its required sub-fields are filled' do
+    it 'does not flag participants when its required sub-properties are filled' do
       form.validate('participants_attributes' => { '0' => { 'participant_name' => 'Ada', 'participant_role' => 'Author' } })
       expect(base_errors(form)).not_to include(a_string_including('Participants'))
     end
 
-    it 'never flags `compound_rights` (no required sub-fields)' do
+    it 'never flags `compound_rights` (no required sub-properties)' do
       form.validate('participants_attributes' => { '0' => { 'participant_name' => 'Ada', 'participant_role' => 'Author' } })
       expect(base_errors(form)).not_to include(a_string_including('Rights'))
     end
diff --git a/spec/helpers/hyrax/compound_fields_helper_spec.rb b/spec/helpers/hyrax/compound_fields_helper_spec.rb
index e73986d934..e68eefb27d 100644
--- a/spec/helpers/hyrax/compound_fields_helper_spec.rb
+++ b/spec/helpers/hyrax/compound_fields_helper_spec.rb
@@ -1,46 +1,46 @@
 # frozen_string_literal: true
 
 RSpec.describe Hyrax::CompoundFieldsHelper, type: :helper do
-  describe '#compound_subfield_options' do
+  describe '#compound_subproperty_options' do
     let(:spec) { { type: 'controlled', authority: nil, values: [%w[Author Author], %w[Editor ed]] } }
 
     it 'returns the inline values list' do
-      expect(helper.compound_subfield_options(spec)).to eq([%w[Author Author], %w[Editor ed]])
+      expect(helper.compound_subproperty_options(spec)).to eq([%w[Author Author], %w[Editor ed]])
     end
 
     it 'leaves the list unchanged when the current value is already offered' do
-      expect(helper.compound_subfield_options(spec, 'ed')).to eq([%w[Author Author], %w[Editor ed]])
+      expect(helper.compound_subproperty_options(spec, 'ed')).to eq([%w[Author Author], %w[Editor ed]])
     end
 
     it 'appends a stored value that is not among the offered options' do
-      expect(helper.compound_subfield_options(spec, 'Legacy'))
+      expect(helper.compound_subproperty_options(spec, 'Legacy'))
         .to eq([%w[Author Author], %w[Editor ed], %w[Legacy Legacy]])
     end
 
-    it 'returns an empty list for a controlled sub-field with neither values nor authority' do
-      expect(helper.compound_subfield_options({ type: 'controlled', authority: nil, values: nil })).to eq([])
+    it 'returns an empty list for a controlled sub-property with neither values nor authority' do
+      expect(helper.compound_subproperty_options({ type: 'controlled', authority: nil, values: nil })).to eq([])
     end
   end
 
-  describe '#compound_subfield_forced?' do
+  describe '#compound_subproperty_forced?' do
     let(:spec) { { type: 'controlled', authority: nil, values: [%w[Author Author]] } }
 
     it 'is false when the value is blank' do
-      expect(helper.compound_subfield_forced?(spec, '')).to be false
+      expect(helper.compound_subproperty_forced?(spec, '')).to be false
     end
 
     it 'is false when the value is among the offered options' do
-      expect(helper.compound_subfield_forced?(spec, 'Author')).to be false
+      expect(helper.compound_subproperty_forced?(spec, 'Author')).to be false
     end
 
     it 'is true when the value is not among the offered options' do
-      expect(helper.compound_subfield_forced?(spec, 'Legacy')).to be true
+      expect(helper.compound_subproperty_forced?(spec, 'Legacy')).to be true
     end
   end
 
-  describe '#compound_subfield_label' do
-    it 'falls back to a humanized sub-field key when no translation exists' do
-      expect(helper.compound_subfield_label(:nonexistent_compound, :some_field)).to eq('Some field')
+  describe '#compound_subproperty_label' do
+    it 'falls back to a humanized sub-property key when no translation exists' do
+      expect(helper.compound_subproperty_label(:nonexistent_compound, :some_field)).to eq('Some field')
     end
   end
 
diff --git a/spec/indexers/hyrax/indexers/compound_indexer_spec.rb b/spec/indexers/hyrax/indexers/compound_indexer_spec.rb
index da6bfbfc9c..81c0b9d38f 100644
--- a/spec/indexers/hyrax/indexers/compound_indexer_spec.rb
+++ b/spec/indexers/hyrax/indexers/compound_indexer_spec.rb
@@ -9,9 +9,9 @@ def self.name
 
       attribute :contributors,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
-                  subfields: {
+                  subproperties: {
                     # searchable + facetable, via the literal field names the
-                    # sub-field declares
+                    # sub-property declares
                     'given_name' => { 'type' => 'string',
                                       'index_keys' => %w[contributors_given_name_tesim contributors_given_name_sim] },
                     # searchable only
@@ -42,14 +42,14 @@ def self.name
                          ])
     end
 
-    it 'writes each sub-field value to the literal Solr field names it declares' do
+    it 'writes each sub-property value to the literal Solr field names it declares' do
       doc = indexer.to_solr
       expect(doc['contributors_given_name_tesim']).to contain_exactly('Ada', 'Alan')
       expect(doc['contributors_given_name_sim']).to contain_exactly('Ada', 'Alan')
       expect(doc['contributors_family_name_tesim']).to contain_exactly('Lovelace', 'Turing')
     end
 
-    it 'does not write a Solr field for a sub-field with no index_keys' do
+    it 'does not write a Solr field for a sub-property with no index_keys' do
       # role_label declares no index_keys; it has no field of its own.
       expect(indexer.to_solr.keys.grep(/role_label/)).to be_empty
     end
@@ -60,7 +60,7 @@ def self.name
       expect(doc['contributors_given_name_tesim']).to contain_exactly('Grace')
     end
 
-    it 'stores the displayable sub-fields as a JSON blob for the show page' do
+    it 'stores the displayable sub-properties as a JSON blob for the show page' do
       parsed = JSON.parse(indexer.to_solr['contributors_json_ss'])
       # role_label (display-only) is included; note (display: false) is omitted.
       expect(parsed).to eq([
@@ -69,7 +69,7 @@ def self.name
                            ])
     end
 
-    it 'omits display: false sub-fields from the blob even though they are indexed' do
+    it 'omits display: false sub-properties from the blob even though they are indexed' do
       parsed = JSON.parse(indexer.to_solr['contributors_json_ss'])
       expect(parsed.first).not_to have_key('note')
       # ...but `note` is still written to its own searchable field
diff --git a/spec/models/concerns/hyrax/compound_normalization_spec.rb b/spec/models/concerns/hyrax/compound_normalization_spec.rb
index 6afdb157b6..53f6f035e3 100644
--- a/spec/models/concerns/hyrax/compound_normalization_spec.rb
+++ b/spec/models/concerns/hyrax/compound_normalization_spec.rb
@@ -9,7 +9,7 @@ def self.name
 
       attribute :contributors,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
-                  subfields: { 'given_name' => { 'type' => 'string' } }
+                  subproperties: { 'given_name' => { 'type' => 'string' } }
                 )
 
       include Hyrax::CompoundNormalization
diff --git a/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb b/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
index 8d505874dc..8c4fada149 100644
--- a/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
+++ b/spec/renderers/hyrax/renderers/compound_attribute_renderer_spec.rb
@@ -18,12 +18,12 @@
       expect(markup.scan('class="hyrax-compound-entry"').count).to eq(2)
     end
 
-    it 'renders each populated sub-field as a labeled value' do
+    it 'renders each populated sub-property as a labeled value' do
       expect(markup).to include('Ada Lovelace').and include('Author')
       expect(markup).to include('Alan Turing')
     end
 
-    it 'uses the i18n sub-field labels (humanized fallback)' do
+    it 'uses the i18n sub-property labels (humanized fallback)' do
       # `title` has no compound_fields.agent.title key in the engine locale by
       # default for an arbitrary compound, so it humanizes; agent_name maps to
       # the shipped label "Name".
@@ -36,10 +36,10 @@
       expect(entries).not_to include('<dd')
     end
 
-    it 'omits blank sub-fields' do
-      # The second entry has only agent_name; it should not emit empty subfield blocks.
+    it 'omits blank sub-properties' do
+      # The second entry has only agent_name; it should not emit empty subproperty blocks.
       second_entry = markup.split('hyrax-compound-entry').last
-      expect(second_entry.scan('hyrax-compound-subfield"').count).to eq(1)
+      expect(second_entry.scan('hyrax-compound-subproperty"').count).to eq(1)
     end
   end
 
@@ -58,13 +58,13 @@
     end
   end
 
-  describe 'controlled sub-field term translation' do
+  describe 'controlled sub-property term translation' do
     let(:values) { [{ 'role' => 'ed', 'name' => 'Ada' }] }
-    let(:subfields) do
+    let(:subproperties) do
       { 'role' => { type: 'controlled', authority: nil, values: [%w[Author author], %w[Editor ed]] },
         'name' => { type: 'string', authority: nil, values: nil } }
     end
-    let(:renderer) { described_class.new(:agent, values, label: 'Agent', html_dl: true, subfields: subfields) }
+    let(:renderer) { described_class.new(:agent, values, label: 'Agent', html_dl: true, subproperties: subproperties) }
 
     it 'displays the controlled term, not the stored id' do
       markup = renderer.render_dl_row
@@ -72,27 +72,27 @@
       expect(markup).not_to match(/>ed</)
     end
 
-    it 'leaves non-controlled sub-fields unchanged' do
+    it 'leaves non-controlled sub-properties unchanged' do
       expect(renderer.render_dl_row).to include('Ada')
     end
 
-    it 'renders the raw id when no subfields specs are provided' do
+    it 'renders the raw id when no subproperties specs are provided' do
       markup = described_class.new(:agent, values, label: 'Agent', html_dl: true).render_dl_row
       expect(markup).to include('ed')
     end
   end
 
-  describe 'controlled sub-field with a linkable URI value' do
+  describe 'controlled sub-property with a linkable URI value' do
     let(:uri) { 'http://rightsstatements.org/vocab/InC/1.0/' }
     let(:values) { [{ 'rights_statement' => uri }] }
-    let(:subfields) do
+    let(:subproperties) do
       { 'rights_statement' => { type: 'controlled', authority: 'rights_statements', values: nil } }
     end
-    let(:renderer) { described_class.new(:compound_rights, values, label: 'Rights', html_dl: true, subfields: subfields) }
+    let(:renderer) { described_class.new(:compound_rights, values, label: 'Rights', html_dl: true, subproperties: subproperties) }
 
     before do
-      allow(Hyrax::CompoundSubfieldLabeler).to receive(:label_for)
-        .with(subfields['rights_statement'], uri).and_return('In Copyright')
+      allow(Hyrax::CompoundSubpropertyLabeler).to receive(:label_for)
+        .with(subproperties['rights_statement'], uri).and_return('In Copyright')
     end
 
     it 'links the resolved term to its URI' do
@@ -101,31 +101,31 @@
     end
   end
 
-  describe 'url sub-field auto-linking' do
+  describe 'url sub-property auto-linking' do
     let(:values) { [{ 'related_item_url' => 'https://example.org/item/42', 'note' => 'see also' }] }
-    let(:subfields) do
+    let(:subproperties) do
       { 'related_item_url' => { type: 'url', authority: nil, values: nil },
         'note' => { type: 'string', authority: nil, values: nil } }
     end
-    let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subfields: subfields) }
+    let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subproperties: subproperties) }
 
-    it 'renders a url sub-field as an anchor' do
+    it 'renders a url sub-property as an anchor' do
       expect(renderer.render_dl_row).to include('<a href="https://example.org/item/42"')
     end
 
-    it 'leaves non-url sub-fields as plain escaped text' do
+    it 'leaves non-url sub-properties as plain escaped text' do
       markup = renderer.render_dl_row
       expect(markup).to include('see also')
       expect(markup).not_to include('<a href="see also"')
     end
   end
 
-  describe 'work_or_url sub-field' do
-    let(:subfields) { { 'related_item' => { type: 'work_or_url', authority: nil, values: nil } } }
+  describe 'work_or_url sub-property' do
+    let(:subproperties) { { 'related_item' => { type: 'work_or_url', authority: nil, values: nil } } }
 
     context 'when the value is an external URL' do
       let(:values) { [{ 'related_item' => 'https://example.org/x' }] }
-      let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subfields: subfields) }
+      let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subproperties: subproperties) }
 
       it 'auto-links the URL' do
         expect(renderer.render_dl_row).to include('<a href="https://example.org/x"')
@@ -134,7 +134,7 @@
 
     context 'when the value resolves to an indexed work' do
       let(:values) { [{ 'related_item' => 'work-123' }] }
-      let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subfields: subfields) }
+      let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subproperties: subproperties) }
 
       before do
         allow(Hyrax::CompoundWorkResolver).to receive(:resolve)
@@ -150,7 +150,7 @@
 
     context 'when the value is neither a URL nor a resolvable work' do
       let(:values) { [{ 'related_item' => 'not-a-real-id' }] }
-      let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subfields: subfields) }
+      let(:renderer) { described_class.new(:relationships, values, label: 'Relationships', html_dl: true, subproperties: subproperties) }
 
       before { allow(Hyrax::CompoundWorkResolver).to receive(:resolve).with('not-a-real-id').and_return(nil) }
 
diff --git a/spec/services/hyrax/compound_entry_validation_spec.rb b/spec/services/hyrax/compound_entry_validation_spec.rb
index 2e6c01cf8c..9b1d0810c9 100644
--- a/spec/services/hyrax/compound_entry_validation_spec.rb
+++ b/spec/services/hyrax/compound_entry_validation_spec.rb
@@ -2,16 +2,16 @@
 
 RSpec.describe Hyrax::CompoundEntryValidation do
   # A definition shaped like Hyrax::CompoundSchema#definition_for produces.
-  def build_definition(required: false, subfields: {})
-    { required: required, subfields: subfields }
+  def build_definition(required: false, subproperties: {})
+    { required: required, subproperties: subproperties }
   end
 
   def sub(required: false)
     { type: 'string', required: required }
   end
 
-  describe 'a compound with no required sub-fields and not required itself' do
-    let(:definition) { build_definition(subfields: { 'a' => sub, 'b' => sub }) }
+  describe 'a compound with no required sub-properties and not required itself' do
+    let(:definition) { build_definition(subproperties: { 'a' => sub, 'b' => sub }) }
 
     it 'is valid with no rows' do
       expect(described_class.new(definition, []).violations).to be_empty
@@ -22,21 +22,21 @@ def sub(required: false)
     end
   end
 
-  describe 'a compound with required sub-fields (optional compound)' do
-    let(:definition) { build_definition(subfields: { 'item' => sub(required: true), 'type' => sub(required: true), 'note' => sub }) }
+  describe 'a compound with required sub-properties (optional compound)' do
+    let(:definition) { build_definition(subproperties: { 'item' => sub(required: true), 'type' => sub(required: true), 'note' => sub }) }
 
     it 'is valid with no rows (compound itself is optional)' do
       expect(described_class.new(definition, []).violations).to be_empty
     end
 
-    it 'is valid when every populated row fills all required sub-fields' do
+    it 'is valid when every populated row fills all required sub-properties' do
       entries = [{ 'item' => 'a', 'type' => 't' }, { 'item' => 'b', 'type' => 't', 'note' => 'n' }]
       expect(described_class.new(definition, entries).violations).to be_empty
     end
 
-    it 'flags a row missing a required sub-field' do
+    it 'flags a row missing a required sub-property' do
       violations = described_class.new(definition, [{ 'item' => 'a' }]).violations
-      expect(violations).to contain_exactly(type: :missing_required_subfields, missing: ['type'])
+      expect(violations).to contain_exactly(type: :missing_required_subproperties, missing: ['type'])
     end
 
     it 'reports one violation per distinct missing-key set (deduped)' do
@@ -51,7 +51,7 @@ def sub(required: false)
   end
 
   describe 'a required compound' do
-    let(:definition) { build_definition(required: true, subfields: { 'a' => sub(required: true) }) }
+    let(:definition) { build_definition(required: true, subproperties: { 'a' => sub(required: true) }) }
 
     it 'flags an empty compound' do
       expect(described_class.new(definition, []).violations)
@@ -71,7 +71,7 @@ def sub(required: false)
 
   describe '#valid?' do
     it 'is true when there are no violations' do
-      expect(described_class.new(build_definition(subfields: { 'a' => sub }), []).valid?).to be true
+      expect(described_class.new(build_definition(subproperties: { 'a' => sub }), []).valid?).to be true
     end
   end
 end
diff --git a/spec/services/hyrax/compound_schema_spec.rb b/spec/services/hyrax/compound_schema_spec.rb
index 43661427a3..5d97dcfbbc 100644
--- a/spec/services/hyrax/compound_schema_spec.rb
+++ b/spec/services/hyrax/compound_schema_spec.rb
@@ -10,7 +10,7 @@ def self.name
       attribute :title, Valkyrie::Types::Array.of(Valkyrie::Types::String)
       attribute :contributors,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
-                  subfields: {
+                  subproperties: {
                     'given_name' => { 'type' => 'string', 'index_keys' => %w[contributors_given_name_sim contributors_given_name_tesim] },
                     'family_name' => { 'type' => 'string', 'index_keys' => %w[contributors_family_name_tesim] },
                     'role_label' => { 'type' => 'controlled', 'authority' => 'contributor_role', 'display' => false }
@@ -22,21 +22,21 @@ def self.name
                 )
       attribute :identifiers,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
-                  subfields: {
+                  subproperties: {
                     'value' => { 'type' => 'string' },
                     'identifier_type' => { 'type' => 'controlled', 'authority' => 'identifier_type' }
                   }
                 )
       attribute :agent,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
-                  subfields: {
+                  subproperties: {
                     'agent_name' => { 'type' => 'string' },
                     'agent_role' => { 'type' => 'controlled', 'values' => ['Author', { 'id' => 'ed', 'label' => 'Editor' }] }
                   }
                 )
       attribute :relationships,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
-                  subfields: {
+                  subproperties: {
                     'related_item' => { 'type' => 'work_or_url' },
                     'relationship_type' => { 'type' => 'controlled', 'authority' => 'relationship_type' }
                   },
@@ -44,11 +44,11 @@ def self.name
                   view: { 'display' => 'card' }
                 )
       # Required at the compound level (non-flexible `required: true`) with two
-      # required sub-fields and one optional.
+      # required sub-properties and one optional.
       attribute :required_compound,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
                   required: true,
-                  subfields: {
+                  subproperties: {
                     'item' => { 'type' => 'string', 'required' => true },
                     'kind' => { 'type' => 'string', 'required' => true },
                     'note' => { 'type' => 'string' }
@@ -58,7 +58,7 @@ def self.name
       attribute :cardinality_compound,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
                   cardinality: { 'minimum' => 1 },
-                  subfields: { 'value' => { 'type' => 'string' } }
+                  subproperties: { 'value' => { 'type' => 'string' } }
                 )
     end
   end
@@ -66,7 +66,7 @@ def self.name
   subject(:schema) { described_class.for(resource_class) }
 
   describe '#compound_names' do
-    it 'returns only the attributes that declare subfields' do
+    it 'returns only the attributes that declare subproperties' do
       expect(schema.compound_names).to contain_exactly(:contributors, :identifiers, :agent, :relationships,
                                                        :required_compound, :cardinality_compound)
     end
@@ -140,25 +140,25 @@ def self.name
       end
     end
 
-    describe '#required_subfield_keys' do
-      it 'returns the sub-fields declared required: true' do
-        expect(schema.required_subfield_keys(:required_compound)).to eq(%w[item kind])
+    describe '#required_subproperty_keys' do
+      it 'returns the sub-properties declared required: true' do
+        expect(schema.required_subproperty_keys(:required_compound)).to eq(%w[item kind])
       end
 
-      it 'is empty when no sub-field is required' do
-        expect(schema.required_subfield_keys(:relationships)).to eq([])
+      it 'is empty when no sub-property is required' do
+        expect(schema.required_subproperty_keys(:relationships)).to eq([])
       end
 
       it 'is empty for a non-compound' do
-        expect(schema.required_subfield_keys(:title)).to eq([])
+        expect(schema.required_subproperty_keys(:title)).to eq([])
       end
     end
 
-    it 'records required on the definition (subfield + compound level)' do
+    it 'records required on the definition (subproperty + compound level)' do
       definition = schema.definition_for(:required_compound)
       expect(definition[:required]).to be true
-      expect(definition[:subfields]['item'][:required]).to be true
-      expect(definition[:subfields]['note'][:required]).to be false
+      expect(definition[:subproperties]['item'][:required]).to be true
+      expect(definition[:subproperties]['note'][:required]).to be false
     end
   end
 
@@ -173,42 +173,42 @@ def self.name
     end
   end
 
-  describe '#subfield_keys' do
-    it 'returns the ordered sub-field keys' do
-      expect(schema.subfield_keys(:contributors)).to eq(%w[given_name family_name role_label])
+  describe '#subproperty_keys' do
+    it 'returns the ordered sub-property keys' do
+      expect(schema.subproperty_keys(:contributors)).to eq(%w[given_name family_name role_label])
     end
 
     it 'is empty for a non-compound' do
-      expect(schema.subfield_keys(:title)).to eq([])
+      expect(schema.subproperty_keys(:title)).to eq([])
     end
   end
 
   describe '#definition_for' do
-    it 'normalizes subfields with type, authority, index_keys and display' do
+    it 'normalizes subproperties with type, authority, index_keys and display' do
       definition = schema.definition_for(:contributors)
-      expect(definition[:subfields]['role_label'])
+      expect(definition[:subproperties]['role_label'])
         .to eq(type: 'controlled', authority: 'contributor_role', values: nil, index_keys: [], display: false, required: false)
-      expect(definition[:subfields]['given_name'])
+      expect(definition[:subproperties]['given_name'])
         .to eq(type: 'string', authority: nil, values: nil,
                index_keys: %w[contributors_given_name_sim contributors_given_name_tesim], display: true, required: false)
     end
 
-    it 'reads per-sub-field index_keys (literal Solr field names)' do
-      expect(schema.definition_for(:contributors)[:subfields]['family_name'][:index_keys])
+    it 'reads per-sub-property index_keys (literal Solr field names)' do
+      expect(schema.definition_for(:contributors)[:subproperties]['family_name'][:index_keys])
         .to eq(%w[contributors_family_name_tesim])
     end
 
-    it 'defaults a sub-field with no index declaration to no index_keys' do
-      expect(schema.definition_for(:agent)[:subfields]['agent_name'][:index_keys]).to eq([])
+    it 'defaults a sub-property with no index declaration to no index_keys' do
+      expect(schema.definition_for(:agent)[:subproperties]['agent_name'][:index_keys]).to eq([])
     end
 
     it 'defaults display to true and honors display: false' do
-      expect(schema.definition_for(:contributors)[:subfields]['given_name'][:display]).to be true
-      expect(schema.definition_for(:contributors)[:subfields]['role_label'][:display]).to be false
+      expect(schema.definition_for(:contributors)[:subproperties]['given_name'][:display]).to be true
+      expect(schema.definition_for(:contributors)[:subproperties]['role_label'][:display]).to be false
     end
 
     it 'normalizes an inline controlled-vocabulary values list to [label, id] pairs' do
-      values = schema.definition_for(:agent)[:subfields]['agent_role'][:values]
+      values = schema.definition_for(:agent)[:subproperties]['agent_role'][:values]
       expect(values).to eq([%w[Author Author], %w[Editor ed]])
     end
 
diff --git a/spec/services/hyrax/compound_subfield_labeler_spec.rb b/spec/services/hyrax/compound_subproperty_labeler_spec.rb
similarity index 93%
rename from spec/services/hyrax/compound_subfield_labeler_spec.rb
rename to spec/services/hyrax/compound_subproperty_labeler_spec.rb
index ed5af5ade2..c400dde88b 100644
--- a/spec/services/hyrax/compound_subfield_labeler_spec.rb
+++ b/spec/services/hyrax/compound_subproperty_labeler_spec.rb
@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-RSpec.describe Hyrax::CompoundSubfieldLabeler do
+RSpec.describe Hyrax::CompoundSubpropertyLabeler do
   describe '.label_for' do
-    it 'returns the value unchanged for a non-controlled sub-field' do
+    it 'returns the value unchanged for a non-controlled sub-property' do
       spec = { type: 'string', authority: nil, values: nil }
       expect(described_class.label_for(spec, 'plain text')).to eq('plain text')
     end
diff --git a/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb b/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb
index fa7d5134d5..4c1a9287d5 100644
--- a/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb
+++ b/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb
@@ -15,7 +15,7 @@ def t(key, **opts)
           'properties' => {
             'agent' => {
               'type' => 'hash',
-              'subfields' => {
+              'subproperties' => {
                 'title' => { 'type' => 'string' },
                 'agent_name' => { 'type' => 'string', 'indexing' => %w[agent_name_tesim] },
                 'agent_role' => { 'type' => 'controlled', 'values' => %w[Author Editor], 'indexing' => %w[agent_role_sim] }
@@ -31,13 +31,13 @@ def t(key, **opts)
       end
     end
 
-    context 'with a controlled sub-field that uses an authority instead of inline values' do
+    context 'with a controlled sub-property that uses an authority instead of inline values' do
       let(:profile) do
         {
           'properties' => {
             'agent' => {
               'type' => 'hash',
-              'subfields' => { 'role' => { 'type' => 'controlled', 'authority' => 'agent_role' } }
+              'subproperties' => { 'role' => { 'type' => 'controlled', 'authority' => 'agent_role' } }
             }
           }
         }
@@ -49,13 +49,13 @@ def t(key, **opts)
       end
     end
 
-    context 'with a controlled sub-field that declares neither authority nor values' do
+    context 'with a controlled sub-property that declares neither authority nor values' do
       let(:profile) do
         {
           'properties' => {
             'agent' => {
               'type' => 'hash',
-              'subfields' => { 'role' => { 'type' => 'controlled' } }
+              'subproperties' => { 'role' => { 'type' => 'controlled' } }
             }
           }
         }
@@ -63,7 +63,7 @@ def t(key, **opts)
 
       it 'records an error' do
         validator.validate!
-        expect(errors).to include(t('controlled_without_source', property: 'agent', subfield: 'role'))
+        expect(errors).to include(t('controlled_without_source', property: 'agent', subproperty: 'role'))
       end
     end
 
@@ -74,41 +74,41 @@ def t(key, **opts)
             'agent' => {
               'type' => 'hash',
               'indexing' => %w[agent_tesim],
-              'subfields' => { 'agent_name' => { 'type' => 'string' } }
+              'subproperties' => { 'agent_name' => { 'type' => 'string' } }
             }
           }
         }
       end
 
-      it 'records an error that indexing belongs on sub-fields' do
+      it 'records an error that indexing belongs on sub-properties' do
         validator.validate!
         expect(errors).to include(t('top_level_indexing', property: 'agent'))
       end
     end
 
-    context 'when subfields is not a mapping' do
+    context 'when subproperties is not a mapping' do
       let(:profile) do
-        { 'properties' => { 'agent' => { 'type' => 'hash', 'subfields' => %w[a b] } } }
+        { 'properties' => { 'agent' => { 'type' => 'hash', 'subproperties' => %w[a b] } } }
       end
 
       it 'records an error' do
         validator.validate!
-        expect(errors).to include(t('subfields_not_hash', property: 'agent'))
+        expect(errors).to include(t('subproperties_not_hash', property: 'agent'))
       end
     end
 
-    context 'when a sub-field config is not a mapping' do
+    context 'when a sub-property config is not a mapping' do
       let(:profile) do
-        { 'properties' => { 'agent' => { 'type' => 'hash', 'subfields' => { 'name' => 'string' } } } }
+        { 'properties' => { 'agent' => { 'type' => 'hash', 'subproperties' => { 'name' => 'string' } } } }
       end
 
       it 'records an error' do
         validator.validate!
-        expect(errors).to include(t('subfield_not_hash', property: 'agent', subfield: 'name', actual: 'String'))
+        expect(errors).to include(t('subproperty_not_hash', property: 'agent', subproperty: 'name', actual: 'String'))
       end
     end
 
-    context 'with a hash property that is not a compound (no subfields, e.g. redirects)' do
+    context 'with a hash property that is not a compound (no subproperties, e.g. redirects)' do
       let(:profile) do
         { 'properties' => { 'redirects' => { 'type' => 'hash' } } }
       end
diff --git a/spec/validators/hyrax/compound_entry_validator_spec.rb b/spec/validators/hyrax/compound_entry_validator_spec.rb
index afce3841f7..2d024a3edd 100644
--- a/spec/validators/hyrax/compound_entry_validator_spec.rb
+++ b/spec/validators/hyrax/compound_entry_validator_spec.rb
@@ -11,12 +11,12 @@
   let(:record) { record_class.new.tap { |r| r.relationships = entries } }
   let(:entries) { [] }
 
-  # A schema with one required-sub-field compound (`relationships`), optional
+  # A schema with one required-sub-property compound (`relationships`), optional
   # at the compound level.
   let(:definition) do
     { required: false,
-      subfields: { 'related_item' => { type: 'work_or_url', required: true },
-                   'relationship_type' => { type: 'controlled', required: true } } }
+      subproperties: { 'related_item' => { type: 'work_or_url', required: true },
+                       'relationship_type' => { type: 'controlled', required: true } } }
   end
   let(:schema) { instance_double(Hyrax::CompoundSchema, definitions: { relationships: definition }) }
 
@@ -54,7 +54,7 @@
     end
   end
 
-  context 'with a row missing a required sub-field' do
+  context 'with a row missing a required sub-property' do
     let(:entries) { [{ 'related_item' => 'work-1' }] }
 
     it 'adds one base error' do
@@ -62,7 +62,7 @@
       expect(record.errors[:base].size).to eq(1)
     end
 
-    it 'names the compound and the missing sub-field in the message' do
+    it 'names the compound and the missing sub-property in the message' do
       # Assert the English wording under :en, so the test is independent of the
       # suite's default locale (other locales need only the same key structure).
       I18n.with_locale(:en) do

From e0766b3019e14cd6e99205db98ee2ea8e9ad047c Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Sat, 6 Jun 2026 01:10:00 -0400
Subject: [PATCH 22/32] Declare compound subproperties as composable properties
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A compound's members are now declared as separate top-level properties
that point back to the parent with `subproperty_of: <parent>`, rather
than nested in a `subproperties:` block. Each subproperty carries its
own group membership (`group:`) and form placement (`form: { cols: }`),
and a parent's `groups:` block names the groups. Subproperties are not
standalone resource attributes — the schema loaders fold them into the
parent, so storage, indexing, and rendering are unchanged.

This is the foundation for deeper nesting and for subproperties that
carry their own form/display options. The previous nested `subproperties:`
format is replaced (not kept for back-compat); both flex modes use the
same flat declaration.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../config/metadata_profiles/m3_profile.yaml  | 138 ++++++++-----
 app/services/hyrax/compound_schema.rb         |  99 +++++++---
 .../compound_validator.rb                     |  57 +++---
 app/services/hyrax/m3_schema_loader.rb        |  37 +++-
 app/services/hyrax/schema_loader.rb           |  48 ++++-
 app/services/hyrax/simple_schema_loader.rb    |  19 +-
 .../hyrax/compounds/_compound_row.html.erb    |   7 +-
 config/locales/hyrax.en.yml                   |   7 +-
 config/metadata/compound_metadata.yaml        | 178 +++++++++++------
 config/metadata_profiles/m3_profile.yaml      | 142 +++++++++-----
 documentation/forms/compound_fields.md        | 183 ++++++++++++------
 spec/services/hyrax/compound_schema_spec.rb   |  47 +++--
 .../compound_validator_spec.rb                |  76 +++-----
 13 files changed, 677 insertions(+), 361 deletions(-)

diff --git a/.koppie/config/metadata_profiles/m3_profile.yaml b/.koppie/config/metadata_profiles/m3_profile.yaml
index d8f58af69f..4159201425 100644
--- a/.koppie/config/metadata_profiles/m3_profile.yaml
+++ b/.koppie/config/metadata_profiles/m3_profile.yaml
@@ -929,8 +929,12 @@ properties:
     range: http://www.w3.org/2001/XMLSchema#string
     property_uri: http://vocabulary.samvera.org/ns#transcriptIds
   # Sample compound (hierarchical) metadata, demonstrating the Hyrax compound
-  # foundation in flexible mode. See documentation/forms/compound_fields.md.
-  agents:
+  # foundation in flexible mode. A compound is a `type: hash, multiple: true`
+  # parent; its members are declared as separate properties pointing back with
+  # `subproperty_of: <parent>`, each carrying its own `available_on`, indexing,
+  # and form placement. `subproperty_of` entries are not standalone resource
+  # attributes. See documentation/forms/compound_fields.md.
+  participants:
     available_on:
       class:
         - GenericWork
@@ -939,26 +943,42 @@ properties:
     type: hash
     range: http://www.w3.org/2001/XMLSchema#string
     display_label:
-      default: Agents
+      default: Participants
     form:
-      primary: false
+      primary: true
     property_uri: http://id.loc.gov/vocabulary/relators/asn
-    subproperties:
-      title: { type: string }
-      agent_name:
-        type: string
-        required: true
-        indexing: [agent_name_sim, agent_name_tesim]
-      agent_role:
-        type: controlled
-        required: true
-        values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
-        indexing: [agent_role_sim, agent_role_tesim]
+    # Group metadata (label) for subproperties declaring `group: <key>`.
     groups:
-      - { label: ~, cols: 4, fields: [title, agent_name, agent_role] }
+      identity:
+        label: Identity
     view:
       render_as: compound
       html_dl: true
+  # Subproperties omit `available_on`/`range`/`display_label`: they inherit the
+  # parent compound's class scope and are folded into it by the schema loader.
+  participant_title:
+    type: string
+    subproperty_of: participants
+    group: identity
+    form:
+      cols: 4
+  participant_name:
+    type: string
+    subproperty_of: participants
+    group: identity
+    required: true
+    indexing: [participant_name_sim, participant_name_tesim]
+    form:
+      cols: 4
+  participant_role:
+    type: controlled
+    subproperty_of: participants
+    group: identity
+    required: true
+    values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
+    indexing: [participant_role_sim, participant_role_tesim]
+    form:
+      cols: 4
   identifiers:
     available_on:
       class:
@@ -972,19 +992,24 @@ properties:
     form:
       primary: false
     property_uri: http://purl.org/dc/terms/identifier
-    subproperties:
-      identifier:
-        type: string
-        required: true
-        indexing: [identifier_value_sim, identifier_value_tesim]
-      identifier_type:
-        type: controlled
-        required: true
-        values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
-        indexing: [identifier_type_sim]
     view:
       render_as: compound
       html_dl: true
+  identifier_value:
+    type: string
+    subproperty_of: identifiers
+    required: true
+    indexing: [identifier_value_sim, identifier_value_tesim]
+    form:
+      cols: 6
+  identifier_type:
+    type: controlled
+    subproperty_of: identifiers
+    required: true
+    values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
+    indexing: [identifier_type_sim]
+    form:
+      cols: 6
   compound_rights:
     available_on:
       class:
@@ -998,21 +1023,29 @@ properties:
     form:
       primary: false
     property_uri: http://purl.org/dc/terms/rights
-    subproperties:
-      rights_statement:
-        type: controlled
-        authority: rights_statements
-        indexing: [compound_rights_statement_sim, compound_rights_statement_tesim]
-      license:
-        type: controlled
-        authority: licenses
-        indexing: [compound_rights_license_sim, compound_rights_license_tesim]
-      rights_notes:
-        type: string
-        indexing: [compound_rights_notes_tesim]
     view:
       render_as: compound
       html_dl: true
+  compound_rights_statement:
+    type: controlled
+    subproperty_of: compound_rights
+    authority: rights_statements
+    indexing: [compound_rights_statement_sim, compound_rights_statement_tesim]
+    form:
+      cols: 6
+  compound_rights_license:
+    type: controlled
+    subproperty_of: compound_rights
+    authority: licenses
+    indexing: [compound_rights_license_sim, compound_rights_license_tesim]
+    form:
+      cols: 6
+  compound_rights_notes:
+    type: string
+    subproperty_of: compound_rights
+    indexing: [compound_rights_notes_tesim]
+    form:
+      cols: 12
   relationships:
     available_on:
       class:
@@ -1024,19 +1057,24 @@ properties:
     display_label:
       default: Relationships
     form:
-      primary: false
+      primary: true
     property_uri: http://purl.org/dc/terms/relation
-    subproperties:
-      related_item:
-        type: work_or_url
-        required: true
-        indexing: [relationships_item_ssim]
-      relationship_type:
-        type: controlled
-        required: true
-        values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
-        indexing: [relationships_type_sim]
     view:
       render_as: compound
       html_dl: true
-      display: card
\ No newline at end of file
+      display: card
+  relationship_item:
+    type: work_or_url
+    subproperty_of: relationships
+    required: true
+    indexing: [relationships_item_ssim]
+    form:
+      cols: 6
+  relationship_type:
+    type: controlled
+    subproperty_of: relationships
+    required: true
+    values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
+    indexing: [relationships_type_sim]
+    form:
+      cols: 6
\ No newline at end of file
diff --git a/app/services/hyrax/compound_schema.rb b/app/services/hyrax/compound_schema.rb
index 51a63ea8c4..3c7f415452 100644
--- a/app/services/hyrax/compound_schema.rb
+++ b/app/services/hyrax/compound_schema.rb
@@ -5,14 +5,16 @@ module Hyrax
   # @api public
   #
   # Reads the compound metadata declarations off a resource's schema. A compound
-  # is a `type: hash, multiple: true` attribute carrying a `subproperties:` map;
-  # the declaration drives the generic form, indexer, and renderer so a
-  # hierarchical field can be defined in YAML alone. See
-  # documentation/forms/compound_fields.md.
+  # is a `type: hash, multiple: true` parent property; its members are declared
+  # as separate properties pointing back with `subproperty_of: <parent>`. The
+  # declaration drives the generic form, indexer, and renderer so a hierarchical
+  # field can be defined in YAML alone. See documentation/forms/compound_fields.md.
   #
-  # Declarations are read from each attribute's Dry type `meta`, which both
-  # schema loaders populate identically, so the result is the same in both flex
-  # modes.
+  # The schema loaders exclude subproperties from a resource's real attributes
+  # (so they get no accessor of their own) but fold each compound's members into
+  # the parent's Dry type `meta` (`subproperties:`). This class reads that meta —
+  # off the resource's own schema — so resolution is identical in both flex
+  # modes and needs no knowledge of which schema file the resource used.
   class CompoundSchema # rubocop:disable Metrics/ClassLength
     ##
     # Build a CompoundSchema for a resource instance or class.
@@ -51,8 +53,9 @@ def self.solr_document_schema_sources(document)
     end
     private_class_method :solr_document_schema_sources
 
-    # The `{ name => dry_type }` attribute map for a class at a flexible schema
-    # version; nil when the loader is unavailable (non-flexible installs).
+    # The `{ name => dry_type }` attribute map (with folded subproperties in
+    # meta) for a class at a flexible schema version; nil when the loader is
+    # unavailable (non-flexible installs).
     def self.flexible_attributes_for(klass, version)
       loader = Hyrax::Schema.m3_schema_loader
       loader.attributes_for(schema: klass.name, version: version, contexts: [])
@@ -80,14 +83,15 @@ def self.schema_sources_for(resource)
     attr_reader :schema_sources
 
     # @param [Array<#each>] schema_sources one or more Dry schemas (each a
-    #   collection of property types responding to `name` and `meta`).
+    #   collection of property types responding to `name` and `meta`), or a
+    #   `{ name => dry_type }` Hash (the loader's `attributes_for` output).
     def initialize(*schema_sources)
       @schema_sources = schema_sources.flatten.compact
     end
 
     ##
-    # @return [Boolean] whether the given attribute is a compound (declares
-    #   `subproperties:`)
+    # @return [Boolean] whether the given attribute is a compound (a `type: hash`
+    #   parent with at least one subproperty)
     def compound?(attribute_name)
       definitions.key?(attribute_name.to_sym)
     end
@@ -147,6 +151,13 @@ def required?(attribute_name)
       definition_for(attribute_name)&.dig(:required) || false
     end
 
+    ##
+    # @return [Boolean] whether the compound declares `form: { primary: true }`
+    #   (shown in the form's primary section rather than "Additional fields").
+    def primary?(attribute_name)
+      definition_for(attribute_name)&.dig(:primary) || false
+    end
+
     ##
     # @return [Array<String>] the sub-property keys declared `required: true` for
     #   the compound (each must be filled in every populated row).
@@ -165,23 +176,28 @@ def definitions
 
     private
 
+    # Assemble one normalized definition per compound parent. A parent is an
+    # attribute whose type meta carries a folded `subproperties:` map (the
+    # loaders fold each compound's `subproperty_of` members into the parent's
+    # meta; see {SchemaLoader#attributes_for}). A `type: hash` with no
+    # subproperties (e.g. redirects) is not a compound and is skipped.
     def build_definitions
       schema_sources.each_with_object({}) do |schema, memo|
         name_meta_pairs(schema).each do |name, meta|
           next if meta.nil? || memo.key?(name)
 
           config = meta.with_indifferent_access
-          subproperties = config['subproperties']
-          next if subproperties.blank?
+          children = config['subproperties']
+          next if children.blank?
 
-          memo[name] = normalize(config, subproperties)
+          memo[name] = normalize(config, children)
         end
       end
     end
 
     # `[name, meta]` pairs for a schema source, which is either a Dry schema (an
     # iterable of properties with `name`/`meta`) or a `{ name => dry_type }` Hash
-    # (the `SchemaLoader#attributes_for` output used for version resolution).
+    # (the loader's `attributes_for` output).
     def name_meta_pairs(schema)
       if schema.is_a?(::Hash)
         schema.map { |name, type| [name.to_sym, (type.meta if type.respond_to?(:meta))] }
@@ -192,22 +208,30 @@ def name_meta_pairs(schema)
       end
     end
 
-    # Normalizes the raw declaration into the symbol-keyed shape the form,
-    # indexer, and renderer consume. See documentation/forms/compound_fields.md
-    # for the meaning of each sub-property key.
-    def normalize(config, subproperties)
-      sub = subproperties.each_with_object({}) { |(key, opts), memo| memo[key.to_s] = normalize_subproperty(opts) }
+    # Normalizes a parent config plus its (folded) child configs into the
+    # symbol-keyed shape the form, indexer, and renderer consume. See
+    # documentation/forms/compound_fields.md for the meaning of each key.
+    def normalize(config, children)
+      sub = children.each_with_object({}) { |(key, opts), memo| memo[key.to_s] = normalize_subproperty(opts) }
 
       view = config['view']
       display_mode = view.is_a?(Hash) && view['display'].to_s == 'card' ? :card : :inline
 
       { subproperties: sub,
-        groups: normalize_groups(config['groups'], sub.keys),
+        groups: normalize_groups(config['groups'], children),
         display_mode: display_mode,
         required: compound_required?(config),
+        primary: compound_primary?(config),
         display_label: normalize_display_label(config) }
     end
 
+    # Whether the compound declares `form: { primary: true }` (renders in the
+    # form's primary section rather than "Additional fields"). Default false.
+    def compound_primary?(config)
+      form = config['form']
+      form.is_a?(Hash) && truthy?(form['primary'])
+    end
+
     # The declared display label as `{ locale => String }` (the m3
     # `display_label` shape), or nil when none is declared.
     def normalize_display_label(config)
@@ -218,12 +242,16 @@ def normalize_display_label(config)
 
     def normalize_subproperty(opts)
       opts = (opts.is_a?(Hash) ? opts : {}).with_indifferent_access
+      form = opts['form'].is_a?(Hash) ? opts['form'] : {}
       { type: (opts['type'] || 'string').to_s,
         authority: opts['authority']&.to_s,
         values: normalize_values(opts['values']),
         index_keys: normalize_index_keys(opts),
         display: opts.fetch('display', true) != false,
-        required: truthy?(opts['required']) }
+        required: truthy?(opts['required']),
+        group: opts['group']&.to_s,
+        cols: (form['cols'] || DEFAULT_COLS).to_i,
+        as: form['as']&.to_s }
     end
 
     # Whether the compound itself is required (at least one row must exist).
@@ -262,14 +290,25 @@ def normalize_values(values)
       end
     end
 
-    def normalize_groups(groups, all_keys)
-      return [{ label: nil, cols: 6, fields: all_keys }] if groups.blank?
+    DEFAULT_COLS = 6
+
+    # Builds the ordered group list for a compound from its children's `group:`
+    # membership and the parent's `groups:` label metadata. Groups appear in the
+    # order their first member is declared (document order); a child with no
+    # `group:` falls in a leading default (unlabeled) group. Field order within a
+    # group is document order. `group_meta` is `{ key => { label: } }`.
+    def normalize_groups(group_meta, children)
+      labels = (group_meta.is_a?(Hash) ? group_meta : {}).with_indifferent_access
+      ordered = {}
+      children.each_key do |child_name|
+        key = (children[child_name]['group'] if children[child_name].is_a?(Hash)).to_s
+        (ordered[key] ||= []) << child_name.to_s
+      end
 
-      Array(groups).map do |group|
-        group = group.with_indifferent_access
-        { label: group['label'],
-          cols: (group['cols'] || 6).to_i,
-          fields: Array(group['fields']).map(&:to_s) }
+      ordered.map do |key, fields|
+        { key: key.presence,
+          label: key.present? ? (labels.dig(key, 'label') || key.to_s.humanize) : nil,
+          fields: fields }
       end
     end
   end
diff --git a/app/services/hyrax/flexible_schema_validators/compound_validator.rb b/app/services/hyrax/flexible_schema_validators/compound_validator.rb
index 0089f2de06..a5d2447347 100644
--- a/app/services/hyrax/flexible_schema_validators/compound_validator.rb
+++ b/app/services/hyrax/flexible_schema_validators/compound_validator.rb
@@ -5,10 +5,11 @@ module FlexibleSchemaValidators
     ##
     # @api private
     #
-    # Validates compound metadata properties (a `type: hash` property declaring
-    # `subproperties:` — see {Hyrax::CompoundSchema}) in an m3 profile at save
-    # time, so a misconfiguration fails with a clear message instead of producing
-    # dead Solr fields or unrenderable values. See
+    # Validates compound metadata in an m3 profile at save time, so a
+    # misconfiguration fails with a clear message instead of producing dead Solr
+    # fields or unrenderable values. A compound is a `type: hash` parent with
+    # members declared as separate properties pointing back via
+    # `subproperty_of: <parent>` — see {Hyrax::CompoundSchema}. See
     # documentation/forms/compound_fields.md for the rules.
     class CompoundValidator
       ##
@@ -21,45 +22,45 @@ def initialize(profile:, errors:)
 
       # @return [void]
       def validate!
-        compound_properties.each do |name, config|
-          validate_subproperties(name, config['subproperties'])
-          validate_no_top_level_indexing(name, config)
-        end
+        subproperties.each { |name, config| validate_subproperty(name, config) }
+        compound_parents.each { |name, config| validate_no_top_level_indexing(name, config) }
       end
 
       private
 
-      # Compounds are detected by `subproperties:` presence (not `type`), so
-      # other hash fields like redirects stay out of scope.
-      def compound_properties
-        (@profile&.dig('properties') || {}).select do |_name, config|
-          config.is_a?(Hash) && config['subproperties'].present?
-        end
+      def properties
+        @properties ||= (@profile&.dig('properties') || {})
       end
 
-      def validate_subproperties(name, subproperties)
-        unless subproperties.is_a?(Hash)
-          @errors << t('subproperties_not_hash', property: name)
-          return
-        end
+      # Entries that declare `subproperty_of:` — the compound members.
+      def subproperties
+        properties.select { |_name, config| config.is_a?(Hash) && config['subproperty_of'].present? }
+      end
 
-        subproperties.each { |sub_name, sub_config| validate_subproperty(name, sub_name, sub_config) }
+      # `type: hash` parents that have at least one subproperty pointing at them.
+      # (A `type: hash` with no children — e.g. redirects — is not a compound.)
+      def compound_parents
+        parent_names = subproperties.values.filter_map { |c| c['subproperty_of'].to_s }.to_set
+        properties.select { |name, config| parent_names.include?(name.to_s) && config.is_a?(Hash) && config['type'].to_s == 'hash' }
       end
 
-      def validate_subproperty(name, sub_name, sub_config)
-        unless sub_config.is_a?(Hash)
-          @errors << t('subproperty_not_hash', property: name, subproperty: sub_name, actual: sub_config.class.to_s)
+      def validate_subproperty(name, config)
+        parent_name = config['subproperty_of'].to_s
+        parent = properties[parent_name]
+        if parent.nil? || !parent.is_a?(Hash) || parent['type'].to_s != 'hash'
+          @errors << t('unknown_parent', property: name, parent: parent_name)
           return
         end
 
-        return unless sub_config['type'].to_s == 'controlled'
-        return if sub_config['authority'].present? || sub_config['values'].present?
+        return unless config['type'].to_s == 'controlled'
+        return if config['authority'].present? || config['values'].present?
 
-        @errors << t('controlled_without_source', property: name, subproperty: sub_name)
+        @errors << t('controlled_without_source', property: name)
       end
 
-      # A top-level `indexing:` would point the catalog at a `<compound>_tesim`
-      # field the indexer never writes; indexing is per sub-property.
+      # A top-level `indexing:` on a parent would point the catalog at a
+      # `<compound>_tesim` field the indexer never writes; indexing is declared
+      # per subproperty.
       def validate_no_top_level_indexing(name, config)
         return if config['indexing'].blank?
         @errors << t('top_level_indexing', property: name)
diff --git a/app/services/hyrax/m3_schema_loader.rb b/app/services/hyrax/m3_schema_loader.rb
index 07554e1137..a5d7cd35ba 100644
--- a/app/services/hyrax/m3_schema_loader.rb
+++ b/app/services/hyrax/m3_schema_loader.rb
@@ -39,10 +39,38 @@ def current_version
     # @param [#to_s] schema_name
     # @return [Enumerable<AttributeDefinition]
     def definitions(schema_name, version, contexts = nil)
+      contextual_attributes(schema_name, version, contexts).map do |name, config|
+        # Compound subproperties (entries declaring `subproperty_of:`) are not
+        # standalone resource attributes — they are gathered into their parent
+        # compound by Hyrax::CompoundSchema. Exclude them here so they get no
+        # accessor, form input, or index rule of their own.
+        next if subproperty_config?(config)
+
+        M3AttributeDefinition.new(name, config)
+      end.compact
+    rescue ActiveRecord::StatementInvalid
+      Rails.logger.error "Skipping definition load for migrations to run"
+      []
+    end
+
+    ##
+    # @return [Hash{String => Hash}] all attribute configs for the schema,
+    #   INCLUDING subproperties (see {SchemaLoader#raw_attribute_configs}), with
+    #   the same context filtering {#definitions} applies.
+    def raw_definitions(schema_name, version, contexts = nil)
+      contextual_attributes(schema_name, version, contexts).to_h
+    rescue ActiveRecord::StatementInvalid
+      Rails.logger.error "Skipping definition load for migrations to run"
+      {}
+    end
+
+    # The schema's attributes after context filtering (but before the
+    # subproperty exclusion {#definitions} applies). Yields `[name, config]`.
+    def contextual_attributes(schema_name, version, contexts = nil)
       schema = Hyrax::FlexibleSchema.find_by(id: version) || Hyrax::FlexibleSchema.create_default_schema
       attributes = schema.attributes_for(schema_name)
       attributes ||= fallback_schema_for(schema_name)
-      attributes.map do |name, config|
+      attributes.filter_map do |name, config|
         # We might be able to consolidate these conditions, but they have been kept separate to make it easier to reason about
         # If there is a context filter on the metadata field and no context is set, skip it
         next if contexts.blank? && config['context'].present?
@@ -51,11 +79,8 @@ def definitions(schema_name, version, contexts = nil)
         next if contexts.present? && config['context'].present? && !(Array(contexts) & Array(config['context'])).any?
 
         # Wew, we are in the clear to use this field
-        M3AttributeDefinition.new(name, config)
-      end.compact
-    rescue ActiveRecord::StatementInvalid
-      Rails.logger.error "Skipping definition load for migrations to run"
-      []
+        [name, config]
+      end
     end
 
     # rubocop:disable Metrics/MethodLength
diff --git a/app/services/hyrax/schema_loader.rb b/app/services/hyrax/schema_loader.rb
index 9641f1a115..6133be3a01 100644
--- a/app/services/hyrax/schema_loader.rb
+++ b/app/services/hyrax/schema_loader.rb
@@ -16,8 +16,16 @@ class UndefinedSchemaError < ArgumentError; end
     # @return [Hash<Symbol, Dry::Types::Type>] a map from attribute names to
     #   types
     def attributes_for(schema:, version: 1, contexts: nil)
+      children = subproperties_by_parent(schema, version, contexts)
       definitions(schema, version, contexts).each_with_object({}) do |definition, hash|
-        hash[definition.name] = definition.type.meta(definition.config)
+        # Fold a compound parent's subproperties (which are excluded from the
+        # real attributes) into the parent's type metadata, so the resource's
+        # own schema carries them for Hyrax::CompoundSchema to read — without
+        # the subproperties becoming standalone attributes.
+        config = definition.config
+        subs = children[definition.name.to_s]
+        config = config.merge('subproperties' => subs) if subs.present?
+        hash[definition.name] = definition.type.meta(config)
       end
     end
 
@@ -45,6 +53,44 @@ def index_rules_for(schema:, version: 1, contexts: nil)
       end
     end
 
+    ##
+    # The raw per-attribute configs for a schema, INCLUDING compound
+    # subproperties (entries declaring `subproperty_of:`). Unlike
+    # {#attributes_for} et al. — which exclude subproperties so they never become
+    # standalone resource attributes — this returns everything declared, so
+    # {Hyrax::CompoundSchema} can gather each parent compound's subproperties.
+    #
+    # @return [Hash{Symbol => Hash}] `{ attribute_name => raw_config_hash }`
+    def raw_attribute_configs(schema:, version: 1, contexts: nil)
+      raw_definitions(schema, version, contexts).each_with_object({}) do |(name, config), hash|
+        hash[(config['name'] || name).to_sym] = config
+      end
+    end
+
+    # @return [Boolean] whether a raw per-attribute config is a compound
+    #   subproperty (declares `subproperty_of:`), which must be excluded from the
+    #   resource's real attributes.
+    def subproperty_config?(config)
+      config.is_a?(Hash) && config['subproperty_of'].present?
+    end
+
+    # Subproperty configs grouped under their parent compound, in document
+    # order: `{ parent_name => { child_name => child_config } }`. Used to fold
+    # each compound's members into its parent's type metadata (see
+    # {#attributes_for}).
+    def subproperties_by_parent(schema, version, contexts)
+      raw_definitions(schema, version, contexts).each_with_object({}) do |(name, config), memo|
+        next unless subproperty_config?(config)
+
+        parent = config['subproperty_of'].to_s
+        child_name = (config['name'] || name).to_s
+        (memo[parent] ||= {})[child_name] = config
+      end
+    rescue StandardError => e
+      Hyrax.logger.debug("subproperties_by_parent(#{schema}): #{e.message}")
+      {}
+    end
+
     def current_version
       1
     end
diff --git a/app/services/hyrax/simple_schema_loader.rb b/app/services/hyrax/simple_schema_loader.rb
index 9138ad5ddf..c9ce31dff9 100644
--- a/app/services/hyrax/simple_schema_loader.rb
+++ b/app/services/hyrax/simple_schema_loader.rb
@@ -27,11 +27,23 @@ def permissive_schema_for_valkrie_adapter
     # @param [#to_s] schema_name
     # @return [Enumerable<AttributeDefinition]
     def definitions(schema_name, _version, _contexts = nil)
-      schema_config(schema_name)['attributes'].map do |name, config|
+      # Compound subproperties (entries declaring `subproperty_of:`) are not
+      # standalone resource attributes — they are gathered into their parent
+      # compound by Hyrax::CompoundSchema. Exclude them here so they get no
+      # accessor, form input, or index rule of their own.
+      schema_config(schema_name)['attributes'].reject { |_name, config| subproperty_config?(config) }.map do |name, config|
         AttributeDefinition.new(name, config)
       end
     end
 
+    ##
+    # @param [#to_s] schema_name
+    # @return [Hash{String => Hash}] all attribute configs, INCLUDING
+    #   subproperties (see {SchemaLoader#raw_attribute_configs}).
+    def raw_definitions(schema_name, _version, _contexts = nil)
+      schema_config(schema_name)['attributes']
+    end
+
     ##
     # @param [#to_s] schema_name
     # @return [Hash]
@@ -70,6 +82,11 @@ def disabled_schemas
 
     def predicate_pairs(ret_hsh, schema_name)
       schema_config(schema_name)['attributes'].each do |name, config|
+        # Compound subproperties are not standalone resource attributes (see
+        # SchemaLoader#definitions), so they have no predicate of their own and
+        # are excluded from the permissive Valkyrie schema.
+        next if subproperty_config?(config)
+
         predicate = RDF::URI(config['predicate'])
         if ret_hsh[name].blank?
           ret_hsh[name.to_sym] = predicate
diff --git a/app/views/hyrax/compounds/_compound_row.html.erb b/app/views/hyrax/compounds/_compound_row.html.erb
index c3bdf0bd3c..b771fa36d3 100644
--- a/app/views/hyrax/compounds/_compound_row.html.erb
+++ b/app/views/hyrax/compounds/_compound_row.html.erb
@@ -15,12 +15,11 @@
 %>
 <% subproperties = definition[:subproperties] %>
 <% groups = definition[:groups] %>
-<% row_position = index.is_a?(String) ? '' : (index.to_i + 1).to_s %>
 <% row_value = ->(key) { row.is_a?(Hash) ? (row[key] || row[key.to_sym]) : nil } %>
 
-<div class="card mb-3 hyrax-compound-row" data-hyrax-compound-row role="group" aria-label="<%= row_label_singular %> <%= row_position %>">
+<div class="card mb-3 hyrax-compound-row" data-hyrax-compound-row role="group" aria-label="<%= row_label_singular %>">
   <div class="card-header bg-light d-flex justify-content-between align-items-center py-2 h6 mb-0">
-    <span><%= row_label_singular %> <%= row_position %></span>
+    <span><%= row_label_singular %></span>
     <button type="button"
             class="close py-0 px-2"
             aria-label="<%= t('hyrax.compound_fields.remove_row_with_label', label: row_label_singular, default: t('hyrax.compound_fields.remove_row')) %>"
@@ -39,7 +38,7 @@
           <% input_id = "#{f.object_name}_#{compound_name}_attributes_#{index}_#{sub_property}" %>
           <% input_name = "#{f.object_name}[#{compound_name}_attributes][#{index}][#{sub_property}]" %>
           <% value = row_value.call(sub_property) %>
-          <div class="form-group col-md-<%= group.fetch(:cols, 6) %>">
+          <div class="form-group col-md-<%= spec[:cols] || 6 %>">
             <%= label_tag input_id, class: 'form-label small text-muted' do %>
               <%= compound_subproperty_label(compound_name, sub_property) %><%
                 if spec[:required] %><abbr title="<%= t('simple_form.required.text', default: 'required') %>" class="required text-danger">*</abbr><% end %>
diff --git a/config/locales/hyrax.en.yml b/config/locales/hyrax.en.yml
index 98d9f54139..1398ec48b2 100644
--- a/config/locales/hyrax.en.yml
+++ b/config/locales/hyrax.en.yml
@@ -1417,10 +1417,9 @@ en:
     flexible_schema_validators:
       compound_validator:
         errors:
-          subproperties_not_hash: "m3 profile compound property `%{property}` must declare `subproperties` as a mapping of sub-property name to its configuration"
-          subproperty_not_hash: "m3 profile compound property `%{property}` sub-property `%{subproperty}` must be a mapping (got `%{actual}`)"
-          controlled_without_source: "m3 profile compound property `%{property}` sub-property `%{subproperty}` is `type: controlled` but declares neither `authority` nor `values`"
-          top_level_indexing: "m3 profile compound property `%{property}` must not declare top-level `indexing`; declare `indexing` (or `index_keys`) on each sub-property instead"
+          unknown_parent: "m3 profile subproperty `%{property}` declares `subproperty_of: %{parent}`, but `%{parent}` is not a declared `type: hash` compound property"
+          controlled_without_source: "m3 profile compound subproperty `%{property}` is `type: controlled` but declares neither `authority` nor `values`"
+          top_level_indexing: "m3 profile compound property `%{property}` must not declare top-level `indexing`; declare `indexing` (or `index_keys`) on each subproperty instead"
       redirects_validator:
         errors:
           invalid_available_on: "m3 profile `redirects` property must be available on at least one work or collection class declared in this profile"
diff --git a/config/metadata/compound_metadata.yaml b/config/metadata/compound_metadata.yaml
index 5f091cf1d8..3db05d949f 100644
--- a/config/metadata/compound_metadata.yaml
+++ b/config/metadata/compound_metadata.yaml
@@ -1,9 +1,14 @@
 # Sample compound (hierarchical) metadata that ships with Hyrax.
 #
-# Each attribute here is a compound: a `type: hash, multiple: true` field whose
-# entries are plain hashes of named sub-properties. The sub-properties are declared in
-# `subproperties:` and rendered, populated, and indexed generically by the compound
-# foundation — no per-field Ruby or ERB. See
+# A compound is a `type: hash, multiple: true` parent property. Its members are
+# declared as separate top-level properties that point back to the parent with
+# `subproperty_of: <parent>`. Sibling order follows document order here; each
+# subproperty optionally names a `group:` and sets its form width via
+# `form: { cols: }`.
+#
+# `subproperty_of` entries are NOT registered as standalone resource attributes
+# — their data lives only as keys inside the parent compound's row hashes. Every
+# key under `attributes:` must be globally unique. See
 # `documentation/forms/compound_fields.md`.
 #
 # These are intentionally generic examples demonstrating the supported
@@ -19,53 +24,83 @@ attributes:
     multiple: true
     predicate: http://id.loc.gov/vocabulary/relators/asn
     form:
-      primary: false
-    subproperties:
-      # Indexing is declared per sub-property via `index_keys:` (the literal Solr
-      # field names + suffixes), exactly like scalar fields. A sub-property with
-      # no `index_keys:` is display-only (rendered from the json blob, not its
-      # own searchable field). `display: false` would omit it from the blob.
-      title: { type: string }
-      participant_name:
-        type: string
-        required: true
-        index_keys: [participant_name_sim, participant_name_tesim]
-      # A controlled sub-property can take its options from an inline list (below)
-      # or from an existing QA local authority (`authority: <name>`).
-      participant_role:
-        type: controlled
-        required: true
-        values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
-        index_keys: [participant_role_sim, participant_role_tesim]
+      primary: true
+    # Group metadata (label) for the subproperties that declare `group: <key>`.
+    # Membership lives on each subproperty; this block only names the groups (no
+    # field lists). Sequencing follows document order — subproperties within a
+    # group by YAML position, groups by first-member appearance. Groups cluster
+    # fields on the form row and can drive structured show-page sections.
     groups:
-      - { label: ~, cols: 4, fields: [title, participant_name, participant_role] }
+      identity:
+        label: Identity
     view:
       render_as: compound
       html_dl: true
+  # A subproperty declares its group membership inline (`group:`) and its data
+  # `type:`. Under `form:`, `cols` sets how wide the input is on the row using
+  # Bootstrap's 12-column grid: 4 fits three across a row, 6 two across, 12 the
+  # full width. `as` (optional) overrides the input widget (e.g. `as: text` for
+  # a textarea); without it the widget follows `type:`.
+  participant_title:
+    type: string
+    subproperty_of: participants
+    group: identity
+    form:
+      cols: 4
+  # Indexing is declared per sub-property via `index_keys:` (the literal Solr
+  # field names + suffixes), exactly like scalar fields. A sub-property with no
+  # `index_keys:` is display-only (rendered from the json blob, not its own
+  # searchable field). `display: false` would omit it from the blob.
+  participant_name:
+    type: string
+    subproperty_of: participants
+    group: identity
+    required: true
+    index_keys: [participant_name_sim, participant_name_tesim]
+    form:
+      cols: 4
+  # A controlled sub-property can take its options from an inline list (below)
+  # or from an existing QA local authority (`authority: <name>`).
+  participant_role:
+    type: controlled
+    subproperty_of: participants
+    group: identity
+    required: true
+    values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
+    index_keys: [participant_role_sim, participant_role_tesim]
+    form:
+      cols: 4
+
   # A typed identifier: an open-entry value plus a controlled identifier type.
-  # Named `identifiers` (plural) to avoid colliding with the scalar
-  # `identifier` defined in basic_metadata / the default m3 profile.
+  # Named `identifiers` (plural) to avoid colliding with the scalar `identifier`
+  # defined in basic_metadata / the default m3 profile.
   identifiers:
     type: hash
     multiple: true
     predicate: http://purl.org/dc/terms/identifier
     form:
       primary: false
-    subproperties:
-      identifier:
-        type: string
-        required: true
-        index_keys: [identifier_value_sim, identifier_value_tesim]
-      identifier_type:
-        type: controlled
-        required: true
-        values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
-        index_keys: [identifier_type_sim]
     view:
       render_as: compound
       html_dl: true
-  # A rights grouping demonstrating controlled sub-properties backed by *existing*
-  # QA local authorities (rather than inline `values:`), alongside an
+  identifier_value:
+    type: string
+    subproperty_of: identifiers
+    required: true
+    index_keys: [identifier_value_sim, identifier_value_tesim]
+    form:
+      cols: 6
+  identifier_type:
+    type: controlled
+    subproperty_of: identifiers
+    required: true
+    values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
+    index_keys: [identifier_type_sim]
+    form:
+      cols: 6
+
+  # A rights grouping demonstrating controlled sub-properties backed by
+  # *existing* QA local authorities (rather than inline `values:`), alongside an
   # open-ended note.
   compound_rights:
     type: hash
@@ -75,42 +110,57 @@ attributes:
       default: Rights
     form:
       primary: false
-    subproperties:
-      rights_statement:
-        type: controlled
-        authority: rights_statements
-        index_keys: [compound_rights_statement_sim, compound_rights_statement_tesim]
-      license:
-        type: controlled
-        authority: licenses
-        index_keys: [compound_rights_license_sim, compound_rights_license_tesim]
-      rights_notes:
-        type: string
-        index_keys: [compound_rights_notes_tesim]
     view:
       render_as: compound
       html_dl: true
-  # A related-item grouping demonstrating the `work_or_url` sub-property: the user
-  # searches for an internal work (typeahead) OR types an external URL. The
-  # stored value is a work id or a URL; show pages link to the internal work
-  # (by title) or auto-link the external URL.
+  compound_rights_statement:
+    type: controlled
+    subproperty_of: compound_rights
+    authority: rights_statements
+    index_keys: [compound_rights_statement_sim, compound_rights_statement_tesim]
+    form:
+      cols: 6
+  compound_rights_license:
+    type: controlled
+    subproperty_of: compound_rights
+    authority: licenses
+    index_keys: [compound_rights_license_sim, compound_rights_license_tesim]
+    form:
+      cols: 6
+  compound_rights_notes:
+    type: string
+    subproperty_of: compound_rights
+    index_keys: [compound_rights_notes_tesim]
+    form:
+      cols: 12
+
+  # A related-item grouping demonstrating the `work_or_url` sub-property: the
+  # user searches for an internal work (typeahead) OR types an external URL. The
+  # stored value is a work id or a URL; show pages link to the internal work (by
+  # title) or auto-link the external URL. Displayed as its own card
+  # (`view: { display: card }`).
   relationships:
     type: hash
     multiple: true
     predicate: http://purl.org/dc/terms/relation
     form:
-      primary: false
-    subproperties:
-      related_item:
-        type: work_or_url
-        required: true
-        index_keys: [relationships_item_ssim]
-      relationship_type:
-        type: controlled
-        required: true
-        values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
-        index_keys: [relationships_type_sim]
+      primary: true
     view:
       render_as: compound
       html_dl: true
       display: card
+  relationship_item:
+    type: work_or_url
+    subproperty_of: relationships
+    required: true
+    index_keys: [relationships_item_ssim]
+    form:
+      cols: 6
+  relationship_type:
+    type: controlled
+    subproperty_of: relationships
+    required: true
+    values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
+    index_keys: [relationships_type_sim]
+    form:
+      cols: 6
diff --git a/config/metadata_profiles/m3_profile.yaml b/config/metadata_profiles/m3_profile.yaml
index 3d1acb5a21..ae11e31d63 100644
--- a/config/metadata_profiles/m3_profile.yaml
+++ b/config/metadata_profiles/m3_profile.yaml
@@ -952,10 +952,12 @@ properties:
       primary: false
     range: http://www.w3.org/2001/XMLSchema#string
     property_uri: http://vocabulary.samvera.org/ns#transcriptIds
-  # Sample compound (hierarchical) metadata shipped with Hyrax. Each is a
-  # `type: hash, multiple: true` property whose entries are hashes of the
-  # `subproperties:` keys, rendered/populated/indexed generically by the compound
-  # foundation. See documentation/forms/compound_fields.md.
+  # Sample compound (hierarchical) metadata shipped with Hyrax. A compound is a
+  # `type: hash, multiple: true` parent property; its members are declared as
+  # separate properties pointing back with `subproperty_of: <parent>`, each
+  # carrying its own `available_on`, indexing, and form placement. Sibling order
+  # follows document order. `subproperty_of` entries are not standalone resource
+  # attributes. See documentation/forms/compound_fields.md.
   participants:
     available_on:
       class:
@@ -967,26 +969,42 @@ properties:
     display_label:
       default: Participants
     form:
-      primary: false
+      primary: true
     property_uri: http://id.loc.gov/vocabulary/relators/asn
-    subproperties:
-      # Indexing per sub-property via `indexing:` (literal Solr field names), the
-      # same mechanism scalar properties use. No `indexing:` => display-only.
-      title: { type: string }
-      participant_name:
-        type: string
-        required: true
-        indexing: [participant_name_sim, participant_name_tesim]
-      participant_role:
-        type: controlled
-        required: true
-        values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
-        indexing: [participant_role_sim, participant_role_tesim]
+    # Group metadata (label) for subproperties declaring `group: <key>`.
     groups:
-      - { label: ~, cols: 4, fields: [title, participant_name, participant_role] }
+      identity:
+        label: Identity
     view:
       render_as: compound
       html_dl: true
+  # Subproperties omit `available_on`/`range`/`display_label`: they inherit the
+  # parent compound's class scope and are folded into it by the schema loader.
+  # Indexing per sub-property via `indexing:` (literal Solr field names), the
+  # same mechanism scalar properties use. No `indexing:` => display-only.
+  participant_title:
+    type: string
+    subproperty_of: participants
+    group: identity
+    form:
+      cols: 4
+  participant_name:
+    type: string
+    subproperty_of: participants
+    group: identity
+    required: true
+    indexing: [participant_name_sim, participant_name_tesim]
+    form:
+      cols: 4
+  participant_role:
+    type: controlled
+    subproperty_of: participants
+    group: identity
+    required: true
+    values: [Author, Editor, Contributor, Creator, Data Collector, Funder, Publisher, Other]
+    indexing: [participant_role_sim, participant_role_tesim]
+    form:
+      cols: 4
   identifiers:
     available_on:
       class:
@@ -1000,19 +1018,24 @@ properties:
     form:
       primary: false
     property_uri: http://purl.org/dc/terms/identifier
-    subproperties:
-      identifier:
-        type: string
-        required: true
-        indexing: [identifier_value_sim, identifier_value_tesim]
-      identifier_type:
-        type: controlled
-        required: true
-        values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
-        indexing: [identifier_type_sim]
     view:
       render_as: compound
       html_dl: true
+  identifier_value:
+    type: string
+    subproperty_of: identifiers
+    required: true
+    indexing: [identifier_value_sim, identifier_value_tesim]
+    form:
+      cols: 6
+  identifier_type:
+    type: controlled
+    subproperty_of: identifiers
+    required: true
+    values: [DOI, Handle, ISBN, ISSN, URL, URN, ARK, Other]
+    indexing: [identifier_type_sim]
+    form:
+      cols: 6
   compound_rights:
     available_on:
       class:
@@ -1026,21 +1049,29 @@ properties:
     form:
       primary: false
     property_uri: http://purl.org/dc/terms/rights
-    subproperties:
-      rights_statement:
-        type: controlled
-        authority: rights_statements
-        indexing: [compound_rights_statement_sim, compound_rights_statement_tesim]
-      license:
-        type: controlled
-        authority: licenses
-        indexing: [compound_rights_license_sim, compound_rights_license_tesim]
-      rights_notes:
-        type: string
-        indexing: [compound_rights_notes_tesim]
     view:
       render_as: compound
       html_dl: true
+  compound_rights_statement:
+    type: controlled
+    subproperty_of: compound_rights
+    authority: rights_statements
+    indexing: [compound_rights_statement_sim, compound_rights_statement_tesim]
+    form:
+      cols: 6
+  compound_rights_license:
+    type: controlled
+    subproperty_of: compound_rights
+    authority: licenses
+    indexing: [compound_rights_license_sim, compound_rights_license_tesim]
+    form:
+      cols: 6
+  compound_rights_notes:
+    type: string
+    subproperty_of: compound_rights
+    indexing: [compound_rights_notes_tesim]
+    form:
+      cols: 12
   relationships:
     available_on:
       class:
@@ -1052,19 +1083,24 @@ properties:
     display_label:
       default: Relationships
     form:
-      primary: false
+      primary: true
     property_uri: http://purl.org/dc/terms/relation
-    subproperties:
-      related_item:
-        type: work_or_url
-        required: true
-        indexing: [relationships_item_ssim]
-      relationship_type:
-        type: controlled
-        required: true
-        values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
-        indexing: [relationships_type_sim]
     view:
       render_as: compound
       html_dl: true
-      display: card
\ No newline at end of file
+      display: card
+  relationship_item:
+    type: work_or_url
+    subproperty_of: relationships
+    required: true
+    indexing: [relationships_item_ssim]
+    form:
+      cols: 6
+  relationship_type:
+    type: controlled
+    subproperty_of: relationships
+    required: true
+    values: [References, Is Referenced By, Is Part Of, Has Part, Is Version Of, Replaces, Requires, Other]
+    indexing: [relationships_type_sim]
+    form:
+      cols: 6
\ No newline at end of file
diff --git a/documentation/forms/compound_fields.md b/documentation/forms/compound_fields.md
index 50b0b5829e..7df4cc2677 100644
--- a/documentation/forms/compound_fields.md
+++ b/documentation/forms/compound_fields.md
@@ -14,35 +14,62 @@ and behave identically in both flex modes.
 
 ## Declaring a compound
 
-A compound is a `type: hash, multiple: true` attribute that also carries a
-`subproperties:` map:
+A compound is a `type: hash, multiple: true` **parent** property. Its members
+are declared as separate top-level properties that point back to the parent
+with `subproperty_of: <parent>`. Every property key (parent and subproperty)
+must be globally unique, so subproperties are conventionally named with a
+parent-derived prefix:
 
 ```yaml
 contributors:
   type: hash
   multiple: true
   predicate: https://prvoices.org/terms/contributor
-  subproperties:
-    given_name:
-      type: string
-      index_keys: [contributors_given_name_sim, contributors_given_name_tesim]
-    family_name:
-      type: string
-      index_keys: [contributors_family_name_sim, contributors_family_name_tesim]
-    name_type:       { type: controlled, authority: name_type }
-    role_label:      { type: controlled, authority: contributor_role }
-    name_identifier:
-      type: string
-      index_keys: [contributors_name_identifier_ssim]
-    affiliation:     { type: string }   # display-only (no index_keys)
+  # Optional group metadata (label only) for subproperties that name a `group:`.
   groups:
-    - { label: Identity, cols: 4, fields: [given_name, family_name, name_type] }
-    - { label: Role,     cols: 4, fields: [role_label, name_identifier, affiliation] }
+    identity: { label: Identity }
+    role:     { label: Role }
+
+contributor_given_name:
+  type: string
+  subproperty_of: contributors
+  group: identity
+  form: { cols: 4 }
+  index_keys: [contributors_given_name_sim, contributors_given_name_tesim]
+contributor_family_name:
+  type: string
+  subproperty_of: contributors
+  group: identity
+  form: { cols: 4 }
+  index_keys: [contributors_family_name_sim, contributors_family_name_tesim]
+contributor_name_type:
+  type: controlled
+  subproperty_of: contributors
+  group: identity
+  authority: name_type
+contributor_role_label:
+  type: controlled
+  subproperty_of: contributors
+  group: role
+  authority: contributor_role
+contributor_affiliation:
+  type: string
+  subproperty_of: contributors   # display-only (no index_keys)
+  group: role
 ```
 
+`subproperty_of` is a declaration hint only: a subproperty does **not** become a
+standalone resource attribute (no accessor, Solr index rule, or RDF predicate of
+its own). Its data lives only as a key inside the parent compound's row hashes;
+the schema loaders fold the subproperties into the parent's type metadata for
+the form, indexer, and renderer to read.
+
+Ordering is document order: subproperties render in the order they are declared,
+and groups in the order their first member appears.
+
 In the m3 profile the same declaration uses `data_type: array`, `type: hash`,
-and `available_on: class:` to scope the property, with the identical
-`subproperties:` / `groups:` keys; sub-property index targets are declared with
+and `available_on: class:` to scope each property (a subproperty repeats its
+parent's `available_on`); sub-property index targets are declared with
 `indexing:` (the flexible-mode spelling of `index_keys:`).
 
 > **Flexible mode:** the active schema is the `Hyrax::FlexibleSchema` row in the
@@ -53,9 +80,13 @@ and `available_on: class:` to scope the property, with the identical
 > singleton class at load time, so a stale running process serves the old
 > attribute set even when the profile YAML is current.
 
-### `subproperties:`
+### Subproperties
 
-An ordered map of `sub_property_key => { type:, ... }`. Supported `type:` values:
+Each subproperty is a top-level property declaring `subproperty_of: <parent>`,
+its data `type:`, and — under `form:` — its layout: `cols` (Bootstrap column
+width out of 12; 4 fits three across a row, 6 two across, 12 full width) and an
+optional `as` widget override (SimpleForm's `as:`, e.g. `as: text` for a
+textarea). Supported `type:` values:
 
 | `type:`      | Renders as          | Notes |
 |--------------|---------------------|-------|
@@ -67,21 +98,23 @@ An ordered map of `sub_property_key => { type:, ... }`. Supported `type:` values
 A `controlled` sub-property sources its options one of two ways:
 
 ```yaml
-subproperties:
-  # (a) inline list — no authority file needed
-  agent_role:
-    type: controlled
-    values: [Author, Editor, Contributor]
-  # (a') inline list with distinct id and label
-  status:
-    type: controlled
-    values:
-      - { id: pub, label: Published }
-      - { id: dft, label: Draft }
-  # (b) an existing QA local authority (config/authorities/<name>.yml)
-  identifier_type:
-    type: controlled
-    authority: identifier_type
+# (a) inline list — no authority file needed
+participant_role:
+  type: controlled
+  subproperty_of: participants
+  values: [Author, Editor, Contributor]
+# (a') inline list with distinct id and label
+participant_status:
+  type: controlled
+  subproperty_of: participants
+  values:
+    - { id: pub, label: Published }
+    - { id: dft, label: Draft }
+# (b) an existing QA local authority (config/authorities/<name>.yml)
+identifier_type:
+  type: controlled
+  subproperty_of: identifiers
+  authority: identifier_type
 ```
 
 Inline `values:` is convenient for small, stable lists and keeps the whole
@@ -104,12 +137,32 @@ add-new) and `geocode` (a Geonames/coordinate lookup, like `based_near`) are
 planned additional sub-property types; the form's row partial has an explicit
 extension point for them.
 
-### `groups:` (optional)
+### Grouping (`group:` + `groups:`, optional)
 
-Visual clustering of sub-properties within each entry's card. Each group is
-`{ label:, cols:, fields: [...] }`, where `cols` is the Bootstrap column width
-(out of 12) for each field in the group. When omitted, all sub-properties render in
-a single unlabeled group.
+Sub-properties can be clustered into labeled groups within each entry's card.
+Membership is declared inline on each sub-property with `group: <key>`; the
+parent compound declares the groups' display metadata in a `groups:` block keyed
+by that key (label only — no field lists):
+
+```yaml
+participants:
+  type: hash
+  multiple: true
+  groups:
+    identity: { label: Identity }
+    role:     { label: Role }
+
+participant_name:
+  type: string
+  subproperty_of: participants
+  group: identity
+  form: { cols: 4 }
+```
+
+A sub-property with no `group:` falls in a single leading unlabeled group.
+Groups appear in the order their first member is declared; sub-properties appear
+in document order within their group. Per-field width is `form: { cols: }` (out
+of 12), not a group-level setting.
 
 ### Indexing sub-properties (`index_keys:` / `indexing:`)
 
@@ -132,8 +185,8 @@ renders only the fields explicitly registered with Blacklight
 (`config.add_index_field`) — compound sub-properties are not registered by default.
 To show a sub-property in search results, register its Solr field name in your
 `CatalogController` (e.g.
-`config.add_index_field 'agent_name_tesim', label: 'Agent'`). The show page and
-edit form render compounds regardless.
+`config.add_index_field 'participant_name_tesim', label: 'Participant'`). The
+show page and edit form render compounds regardless.
 
 ### `display:` (optional, default true)
 
@@ -153,8 +206,8 @@ compound itself — marks the whole compound as required. See
 
 ## Persisted shape
 
-A compound persists as an array of plain string-keyed hashes — exactly the
-keys declared in `subproperties:`:
+A compound persists as an array of plain string-keyed hashes — one key per
+declared sub-property:
 
 ```ruby
 work.contributors
@@ -267,9 +320,14 @@ relationships:
   view:
     render_as: compound
     display: card
-  subproperties:
-    related_item:      { type: work_or_url }
-    relationship_type: { type: controlled, authority: relationship_type }
+
+relationship_item:
+  type: work_or_url
+  subproperty_of: relationships
+relationship_type:
+  type: controlled
+  subproperty_of: relationships
+  authority: relationship_type
 ```
 
 `Hyrax::CompoundSchema` reports each compound's `display_mode` (`:inline` or
@@ -292,12 +350,12 @@ path resolves on a collection as on a work.
 In flexible mode, `Hyrax::FlexibleSchemaValidators::CompoundValidator` checks
 compound declarations when an m3 profile is saved/uploaded, so a
 misconfiguration fails with a clear message instead of producing dead Solr
-fields or unrenderable values. It enforces: `subproperties:` is a mapping; each
-sub-property config is a mapping; a `type: controlled` sub-property declares an
-option source (`authority:` or `values:`); and the compound does **not** carry
-a top-level `indexing:` (indexing is declared per sub-property — a top-level
-`indexing:` would point the catalog at a `<compound>_tesim` field the indexer
-never writes).
+fields or unrenderable values. It enforces: a `subproperty_of:` points at a
+declared `type: hash` compound property; a `type: controlled` sub-property
+declares an option source (`authority:` or `values:`); and a compound parent
+does **not** carry a top-level `indexing:` (indexing is declared per
+sub-property — a top-level `indexing:` would point the catalog at a
+`<compound>_tesim` field the indexer never writes).
 
 ## Required sub-properties
 
@@ -317,10 +375,19 @@ relationships:
   type: hash
   multiple: true
   required: true            # the work must have at least one relationship
-  subproperties:
-    related_item:      { type: work_or_url, required: true }
-    relationship_type: { type: controlled, authority: relationship_type, required: true }
-    note:              { type: string }   # optional
+
+relationship_item:
+  type: work_or_url
+  subproperty_of: relationships
+  required: true
+relationship_type:
+  type: controlled
+  subproperty_of: relationships
+  authority: relationship_type
+  required: true
+relationship_note:
+  type: string
+  subproperty_of: relationships   # optional
 ```
 
 Required sub-properties and required compounds render a `*` marker on the form
diff --git a/spec/services/hyrax/compound_schema_spec.rb b/spec/services/hyrax/compound_schema_spec.rb
index 5d97dcfbbc..88d42e07ef 100644
--- a/spec/services/hyrax/compound_schema_spec.rb
+++ b/spec/services/hyrax/compound_schema_spec.rb
@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 RSpec.describe Hyrax::CompoundSchema do
+  # These resources stand in for what the schema loaders produce: each compound
+  # parent is a `hash` attribute whose meta carries the folded `subproperties:`
+  # map (the loaders fold each compound's `subproperty_of` members into the
+  # parent's meta) plus optional `groups:` label metadata. Each subproperty spec
+  # carries its own `group`, `form` (cols/as), index_keys, etc.
   let(:resource_class) do
     Class.new(Hyrax::Resource) do
       def self.name
@@ -11,14 +16,13 @@ def self.name
       attribute :contributors,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
                   subproperties: {
-                    'given_name' => { 'type' => 'string', 'index_keys' => %w[contributors_given_name_sim contributors_given_name_tesim] },
-                    'family_name' => { 'type' => 'string', 'index_keys' => %w[contributors_family_name_tesim] },
-                    'role_label' => { 'type' => 'controlled', 'authority' => 'contributor_role', 'display' => false }
+                    'given_name' => { 'type' => 'string', 'group' => 'identity', 'form' => { 'cols' => 6 },
+                                      'index_keys' => %w[contributors_given_name_sim contributors_given_name_tesim] },
+                    'family_name' => { 'type' => 'string', 'group' => 'identity', 'form' => { 'cols' => 6 },
+                                       'index_keys' => %w[contributors_family_name_tesim] },
+                    'role_label' => { 'type' => 'controlled', 'authority' => 'contributor_role', 'group' => 'role', 'display' => false }
                   },
-                  groups: [
-                    { 'label' => 'Identity', 'cols' => 6, 'fields' => %w[given_name family_name] },
-                    { 'label' => 'Role', 'cols' => 6, 'fields' => %w[role_label] }
-                  ]
+                  groups: { 'identity' => { 'label' => 'Identity' }, 'role' => { 'label' => 'Role' } }
                 )
       attribute :identifiers,
                 Valkyrie::Types::Array.of(Dry::Types['hash']).meta(
@@ -184,13 +188,15 @@ def self.name
   end
 
   describe '#definition_for' do
-    it 'normalizes subproperties with type, authority, index_keys and display' do
+    it 'normalizes subproperties with type, authority, index_keys, display, group, cols and as' do
       definition = schema.definition_for(:contributors)
       expect(definition[:subproperties]['role_label'])
-        .to eq(type: 'controlled', authority: 'contributor_role', values: nil, index_keys: [], display: false, required: false)
+        .to eq(type: 'controlled', authority: 'contributor_role', values: nil, index_keys: [],
+               display: false, required: false, group: 'role', cols: 6, as: nil)
       expect(definition[:subproperties]['given_name'])
         .to eq(type: 'string', authority: nil, values: nil,
-               index_keys: %w[contributors_given_name_sim contributors_given_name_tesim], display: true, required: false)
+               index_keys: %w[contributors_given_name_sim contributors_given_name_tesim],
+               display: true, required: false, group: 'identity', cols: 6, as: nil)
     end
 
     it 'reads per-sub-property index_keys (literal Solr field names)' do
@@ -207,22 +213,26 @@ def self.name
       expect(schema.definition_for(:contributors)[:subproperties]['role_label'][:display]).to be false
     end
 
+    it 'defaults cols to 6 when no form placement is declared' do
+      expect(schema.definition_for(:identifiers)[:subproperties]['value'][:cols]).to eq(6)
+    end
+
     it 'normalizes an inline controlled-vocabulary values list to [label, id] pairs' do
       values = schema.definition_for(:agent)[:subproperties]['agent_role'][:values]
       expect(values).to eq([%w[Author Author], %w[Editor ed]])
     end
 
-    it 'carries the declared groups' do
+    it 'reconstructs groups from subproperty membership and the parent group labels' do
       groups = schema.definition_for(:contributors)[:groups]
       expect(groups).to eq([
-                             { label: 'Identity', cols: 6, fields: %w[given_name family_name] },
-                             { label: 'Role', cols: 6, fields: %w[role_label] }
+                             { key: 'identity', label: 'Identity', fields: %w[given_name family_name] },
+                             { key: 'role', label: 'Role', fields: %w[role_label] }
                            ])
     end
 
-    it 'defaults groups to a single all-fields group when none declared' do
+    it 'puts subproperties with no group in a single default (unlabeled) group' do
       groups = schema.definition_for(:identifiers)[:groups]
-      expect(groups).to eq([{ label: nil, cols: 6, fields: %w[value identifier_type] }])
+      expect(groups).to eq([{ key: nil, label: nil, fields: %w[value identifier_type] }])
     end
   end
 
@@ -236,9 +246,10 @@ def self.name
 
   describe '.for_solr_document' do
     # The attribute map a flexible schema loader returns for a version:
-    # `{ name => dry_type_with_meta }` — the same shape SchemaLoader#attributes_for
-    # produces. Show pages resolve compounds from this (via schema_version)
-    # without loading the resource.
+    # `{ name => dry_type_with_meta }` (with subproperties folded into the
+    # parent meta) — the same shape SchemaLoader#attributes_for produces. Show
+    # pages resolve compounds from this (via schema_version) without loading the
+    # resource.
     let(:version_attributes) do
       resource_class.schema.index_by(&:name)
     end
diff --git a/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb b/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb
index 4c1a9287d5..e1bd0e5cfc 100644
--- a/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb
+++ b/spec/services/hyrax/flexible_schema_validators/compound_validator_spec.rb
@@ -9,18 +9,15 @@ def t(key, **opts)
   end
 
   describe '#validate!' do
-    context 'with a well-formed compound property' do
+    context 'with a well-formed compound (parent + flat subproperties)' do
       let(:profile) do
         {
           'properties' => {
-            'agent' => {
-              'type' => 'hash',
-              'subproperties' => {
-                'title' => { 'type' => 'string' },
-                'agent_name' => { 'type' => 'string', 'indexing' => %w[agent_name_tesim] },
-                'agent_role' => { 'type' => 'controlled', 'values' => %w[Author Editor], 'indexing' => %w[agent_role_sim] }
-              }
-            }
+            'participants' => { 'type' => 'hash' },
+            'participant_title' => { 'type' => 'string', 'subproperty_of' => 'participants' },
+            'participant_name' => { 'type' => 'string', 'subproperty_of' => 'participants', 'indexing' => %w[participant_name_tesim] },
+            'participant_role' => { 'type' => 'controlled', 'subproperty_of' => 'participants',
+                                    'values' => %w[Author Editor], 'indexing' => %w[participant_role_sim] }
           }
         }
       end
@@ -31,14 +28,12 @@ def t(key, **opts)
       end
     end
 
-    context 'with a controlled sub-property that uses an authority instead of inline values' do
+    context 'with a controlled subproperty that uses an authority instead of inline values' do
       let(:profile) do
         {
           'properties' => {
-            'agent' => {
-              'type' => 'hash',
-              'subproperties' => { 'role' => { 'type' => 'controlled', 'authority' => 'agent_role' } }
-            }
+            'participants' => { 'type' => 'hash' },
+            'participant_role' => { 'type' => 'controlled', 'subproperty_of' => 'participants', 'authority' => 'participant_role' }
           }
         }
       end
@@ -49,62 +44,55 @@ def t(key, **opts)
       end
     end
 
-    context 'with a controlled sub-property that declares neither authority nor values' do
+    context 'with a controlled subproperty that declares neither authority nor values' do
       let(:profile) do
         {
           'properties' => {
-            'agent' => {
-              'type' => 'hash',
-              'subproperties' => { 'role' => { 'type' => 'controlled' } }
-            }
+            'participants' => { 'type' => 'hash' },
+            'participant_role' => { 'type' => 'controlled', 'subproperty_of' => 'participants' }
           }
         }
       end
 
-      it 'records an error' do
+      it 'records an error keyed on the subproperty' do
         validator.validate!
-        expect(errors).to include(t('controlled_without_source', property: 'agent', subproperty: 'role'))
+        expect(errors).to include(t('controlled_without_source', property: 'participant_role'))
       end
     end
 
-    context 'with a top-level indexing declaration on the compound' do
+    context 'with a top-level indexing declaration on the compound parent' do
       let(:profile) do
         {
           'properties' => {
-            'agent' => {
-              'type' => 'hash',
-              'indexing' => %w[agent_tesim],
-              'subproperties' => { 'agent_name' => { 'type' => 'string' } }
-            }
+            'participants' => { 'type' => 'hash', 'indexing' => %w[participants_tesim] },
+            'participant_name' => { 'type' => 'string', 'subproperty_of' => 'participants' }
           }
         }
       end
 
-      it 'records an error that indexing belongs on sub-properties' do
+      it 'records an error that indexing belongs on subproperties' do
         validator.validate!
-        expect(errors).to include(t('top_level_indexing', property: 'agent'))
+        expect(errors).to include(t('top_level_indexing', property: 'participants'))
       end
     end
 
-    context 'when subproperties is not a mapping' do
+    context 'with a subproperty whose parent is not a declared type: hash compound' do
       let(:profile) do
-        { 'properties' => { 'agent' => { 'type' => 'hash', 'subproperties' => %w[a b] } } }
-      end
-
-      it 'records an error' do
-        validator.validate!
-        expect(errors).to include(t('subproperties_not_hash', property: 'agent'))
-      end
-    end
-
-    context 'when a sub-property config is not a mapping' do
-      let(:profile) do
-        { 'properties' => { 'agent' => { 'type' => 'hash', 'subproperties' => { 'name' => 'string' } } } }
+        {
+          'properties' => {
+            # parent missing entirely
+            'participant_name' => { 'type' => 'string', 'subproperty_of' => 'participants' },
+            # parent exists but is not a hash
+            'note' => { 'type' => 'string' },
+            'note_detail' => { 'type' => 'string', 'subproperty_of' => 'note' }
+          }
+        }
       end
 
-      it 'records an error' do
+      it 'records an unknown_parent error for each' do
         validator.validate!
-        expect(errors).to include(t('subproperty_not_hash', property: 'agent', subproperty: 'name', actual: 'String'))
+        expect(errors).to include(t('unknown_parent', property: 'participant_name', parent: 'participants'))
+        expect(errors).to include(t('unknown_parent', property: 'note_detail', parent: 'note'))
       end
     end
 

From 5505a46a9141771618bcb635017133dddd960f92 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Sat, 6 Jun 2026 01:14:37 -0400
Subject: [PATCH 23/32] Support flat compound subproperties in flexible schemas

Flexible (m3 profile) compound subproperties may omit `display_label`,
`available_on`, and `range`: the profile JSON schema exempts entries
declaring `subproperty_of`, and a subproperty inherits its parent
compound's class scope. The flexible schema model no longer requires a
`range` (keeping the declared `type:` when absent) and skips registering
subproperties as standalone class attributes.

Without this, a profile using the flat compound format fails validation
and the app raises on boot building attributes for a subproperty.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app/models/hyrax/flexible_schema.rb          | 34 +++++++++++++++++---
 config/metadata_profiles/m3_json_schema.json | 26 ++++++++++++++-
 2 files changed, 54 insertions(+), 6 deletions(-)

diff --git a/app/models/hyrax/flexible_schema.rb b/app/models/hyrax/flexible_schema.rb
index 069d67cb41..af4b5fd7ba 100644
--- a/app/models/hyrax/flexible_schema.rb
+++ b/app/models/hyrax/flexible_schema.rb
@@ -152,19 +152,41 @@ def class_names
     profile['classes'].keys.each do |class_name|
       @class_names[class_name] = {}
     end
-    profile['properties'].each do |key, values|
+    all_properties = profile['properties'] || {}
+    all_properties.each do |key, values|
       property_name = values['name'] || key
-      values['available_on']['class'].each do |property_class|
+      # A compound subproperty may omit `available_on`; it inherits the class
+      # scope of its parent compound. (It still appears in each class's attribute
+      # map so the schema loader can fold it into the parent; the loader excludes
+      # it from the resource's real attributes.)
+      classes = property_classes(values, all_properties)
+      next if classes.blank?
+
+      classes.each do |property_class|
         # map some m3 items to what Hyrax expects
-        values = values_map(values)
-        @class_names[property_class][property_name] = values
+        mapped = values_map(values)
+        @class_names[property_class] ||= {}
+        @class_names[property_class][property_name] = mapped
       end
     end
     @class_names
   end
 
+  # The classes a property is available on: its own `available_on`, or — for a
+  # compound subproperty that omits it — its parent compound's `available_on`.
+  def property_classes(values, all_properties)
+    own = values.dig('available_on', 'class')
+    return Array(own) if own.present?
+
+    parent = values['subproperty_of'] && all_properties[values['subproperty_of'].to_s]
+    Array(parent&.dig('available_on', 'class'))
+  end
+
   def values_map(values)
-    values['type'] = lookup_type(values['range'])
+    # Derive the Dry type from the XSD `range` when present; otherwise keep the
+    # declared `type:` (compound subproperties declare `type:` directly and have
+    # no `range` of their own).
+    values['type'] = lookup_type(values['range']) if values['range'].present?
     values['predicate'] = values['property_uri']
     values['index_keys'] = values['indexing']
     values['context'] = values.dig('available_on', 'context')
@@ -209,6 +231,8 @@ def assign_required_flag(values)
 
   def lookup_type(range)
     case range
+    when nil, ''
+      nil
     when "http://www.w3.org/2001/XMLSchema#dateTime"
       'date_time'
     else
diff --git a/config/metadata_profiles/m3_json_schema.json b/config/metadata_profiles/m3_json_schema.json
index 32dd9e4453..9b56cc35e7 100644
--- a/config/metadata_profiles/m3_json_schema.json
+++ b/config/metadata_profiles/m3_json_schema.json
@@ -185,9 +185,33 @@
       },
       "additionalProperties": {
         "type": "object",
-        "required": ["display_label", "available_on", "range"],
+        "comment": "A compound subproperty (declares `subproperty_of`) is a hierarchical member, not a standalone property: it inherits its class scope from its parent and has no label/range of its own, so it is exempt from the display_label/available_on/range requirements. All other properties require display_label, available_on, and range.",
+        "if": {
+          "properties": { "subproperty_of": { "type": "string" } },
+          "required": ["subproperty_of"]
+        },
+        "then": {},
+        "else": {
+          "required": ["display_label", "available_on", "range"]
+        },
         "properties": {
 
+          "subproperty_of": {
+            "type": "string",
+            "description": "Names the parent compound (`type: hash`) property this is a subproperty of. Such an entry is a hierarchical member, not a standalone resource attribute."
+          },
+
+          "group": {
+            "type": "string",
+            "description": "Optional group key clustering this subproperty with its siblings on the form/show; the parent compound's `groups:` block supplies the group's label."
+          },
+
+          "form": {
+            "type": "object",
+            "description": "Form placement for a subproperty: `cols` (Bootstrap column width out of 12) and an optional `as` widget override.",
+            "additionalProperties": true
+          },
+
           "display_label": {
             "type": "object",
             "description": "Human-readable label for the property.  Class or context specific display_labels provided as a list using the class and value.",

From ccea414e89846a41304434e850e9fd6c6331209b Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Sat, 6 Jun 2026 01:15:53 -0400
Subject: [PATCH 24/32] Link and search collections in work_or_url compounds
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A `work_or_url` subproperty now resolves an internal id to the right
show page — a work to its work page, a collection to its collection
page — instead of the model-agnostic catalog route, using the
document's Wings-aware model resolution. The picker search also returns
collections alongside works, so a related item can be either.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../hyrax/compound_work_picker_builder.rb     | 16 ++--
 app/services/hyrax/compound_work_resolver.rb  | 75 +++++++++++++------
 .../compound_work_picker_builder_spec.rb      | 10 ++-
 .../hyrax/compound_work_resolver_spec.rb      | 69 ++++++++++-------
 4 files changed, 110 insertions(+), 60 deletions(-)

diff --git a/app/search_builders/hyrax/compound_work_picker_builder.rb b/app/search_builders/hyrax/compound_work_picker_builder.rb
index 7c215df118..ff9470b296 100644
--- a/app/search_builders/hyrax/compound_work_picker_builder.rb
+++ b/app/search_builders/hyrax/compound_work_picker_builder.rb
@@ -2,10 +2,14 @@
 
 module Hyrax
   ##
-  # Search builder for the compound `work_or_url` sub-property's work picker. Finds
-  # works the current user can read (it subclasses {Hyrax::SearchBuilder}, so
-  # permission filtering is retained), matching any indexed query term OR a
-  # partial/prefix title.
+  # Search builder for the compound `work_or_url` sub-property's picker. Finds
+  # works *and* collections the current user can read (it subclasses
+  # {Hyrax::SearchBuilder}, so permission filtering is retained), matching any
+  # indexed query term OR a partial/prefix title.
+  #
+  # {Hyrax::FilterByType#models} already includes both work and collection
+  # classes, so no `only_works?`/`only_collections?` override is needed — the
+  # default type filter admits both.
   class CompoundWorkPickerBuilder < Hyrax::SearchBuilder
     include Hyrax::FilterByType
 
@@ -16,10 +20,6 @@ def initialize(context)
       @q = context.params[:q]
     end
 
-    def only_works?
-      true
-    end
-
     # ORs a multi-field term match with a prefix-wildcard title match. The rest
     # of the processor chain still applies the permission and type filters.
     def filter_on_any_term_or_partial_title(solr_parameters)
diff --git a/app/services/hyrax/compound_work_resolver.rb b/app/services/hyrax/compound_work_resolver.rb
index b4cdec0a18..450df55222 100644
--- a/app/services/hyrax/compound_work_resolver.rb
+++ b/app/services/hyrax/compound_work_resolver.rb
@@ -19,46 +19,75 @@ def self.url?(value)
     # @return [Array(String, String)] the work's title (falling back to the id)
     #   and its show path
     def self.title_and_path(id)
-      [title_for(id), path_for(id)]
+      doc = indexed_doc_for(id)
+      [doc ? title_from(doc, id) : id.to_s, path_for_doc(doc, id)]
     end
 
     ##
-    # Resolve an internal work id to its display title and show path, but only
-    # when a matching work is actually indexed. Returns nil when nothing
-    # matches, so callers can render a bare, unlinked value rather than a broken
-    # link to a non-existent work.
+    # Resolve an internal id to its display title and show path, but only when a
+    # matching record is actually indexed. Returns nil when nothing matches, so
+    # callers can render a bare, unlinked value rather than a broken link to a
+    # non-existent record.
     #
     # @param id [String]
     # @return [Array(String, String), nil] `[title, path]`, or nil when unresolved
     def self.resolve(id)
-      title = indexed_title_for(id)
-      return nil if title.nil?
-      [title, path_for(id)]
+      doc = indexed_doc_for(id)
+      return nil if doc.nil?
+      [title_from(doc, id), path_for_doc(doc, id)]
     end
 
     def self.title_for(id)
-      indexed_title_for(id) || id.to_s
+      doc = indexed_doc_for(id)
+      doc ? title_from(doc, id) : id.to_s
     end
 
-    # The indexed title for a work id, or nil when no such work is indexed
-    # (distinguishes "resolved to a real work" from "no match").
-    def self.indexed_title_for(id)
-      doc = Hyrax::SolrService.query("{!field f=id}#{id}", fl: 'title_tesim', rows: 1).first
-      return nil if doc.nil?
-      Array(doc['title_tesim']).first.presence || id.to_s
+    def self.path_for(id)
+      doc = indexed_doc_for(id)
+      path_for_doc(doc, id)
+    end
+
+    # The indexed Solr document for an id (as a {SolrDocument} so it carries the
+    # Wings-aware model resolution), or nil when none is indexed (distinguishes
+    # "resolved to a real record" from "no match").
+    def self.indexed_doc_for(id)
+      raw = Hyrax::SolrService.query("{!field f=id}#{id}", fl: 'id,title_tesim,has_model_ssim', rows: 1).first
+      raw && ::SolrDocument.new(raw)
     rescue StandardError => e
-      Hyrax.logger.debug("CompoundWorkResolver.indexed_title_for(#{id}): #{e.message}")
+      Hyrax.logger.debug("CompoundWorkResolver.indexed_doc_for(#{id}): #{e.message}")
       nil
     end
-    private_class_method :indexed_title_for
+    private_class_method :indexed_doc_for
 
-    # The model-agnostic Blacklight show route (`/catalog/:id`) links any
-    # indexed work without knowing its class.
-    def self.path_for(id)
-      Rails.application.routes.url_helpers.solr_document_path(id)
+    def self.title_from(doc, id)
+      Array(doc['title_tesim']).first.presence || id.to_s
+    end
+    private_class_method :title_from
+
+    # The show path for an indexed record. Classification uses the document's
+    # own Wings-aware predicates (`collection?`/`work?`, which resolve through
+    # `hydra_model` and so honor the `valkyrie_transition` mapping):
+    #   * a collection -> the engine collection show route (`/collections/:id`);
+    #   * a work -> its work show route, named by the routed model's
+    #     `singular_route_key` (e.g. `hyrax_generic_work_path` ->
+    #     `/concern/generic_works/:id`);
+    #   * anything else -> the model-agnostic catalog route.
+    def self.path_for_doc(doc, id)
+      app = Rails.application.routes.url_helpers
+      return app.solr_document_path(id) if doc.nil?
+
+      if doc.collection?
+        Hyrax::Engine.routes.url_helpers.collection_path(id)
+      elsif doc.work?
+        helper = "#{doc.hydra_model.model_name.singular_route_key}_path"
+        app.respond_to?(helper) ? app.public_send(helper, id) : app.solr_document_path(id)
+      else
+        app.solr_document_path(id)
+      end
     rescue StandardError => e
-      Hyrax.logger.debug("CompoundWorkResolver.path_for(#{id}): #{e.message}")
-      "/catalog/#{id}"
+      Hyrax.logger.debug("CompoundWorkResolver.path_for_doc(#{id}): #{e.message}")
+      Rails.application.routes.url_helpers.solr_document_path(id)
     end
+    private_class_method :path_for_doc
   end
 end
diff --git a/spec/search_builders/hyrax/compound_work_picker_builder_spec.rb b/spec/search_builders/hyrax/compound_work_picker_builder_spec.rb
index e200ed4f23..06dce25241 100644
--- a/spec/search_builders/hyrax/compound_work_picker_builder_spec.rb
+++ b/spec/search_builders/hyrax/compound_work_picker_builder_spec.rb
@@ -18,11 +18,15 @@
     end
   end
 
-  describe "#only_works?" do
+  describe "#filter_models" do
     let(:q) { "foo" }
 
-    it "restricts to works" do
-      expect(builder.only_works?).to be true
+    it "admits both works and collections (no only_works? restriction)" do
+      builder.send(:filter_models, solr_params)
+      clause = Array(solr_params[:fq]).find { |fq| fq.include?('has_model_ssim') }
+      models = clause.to_s.sub('{!terms f=has_model_ssim}', '').split(',')
+      expect(models).to include(*Hyrax::ModelRegistry.work_rdf_representations)
+      expect(models).to include(*Hyrax::ModelRegistry.collection_rdf_representations)
     end
   end
 
diff --git a/spec/services/hyrax/compound_work_resolver_spec.rb b/spec/services/hyrax/compound_work_resolver_spec.rb
index 5681520ba2..844dd18767 100644
--- a/spec/services/hyrax/compound_work_resolver_spec.rb
+++ b/spec/services/hyrax/compound_work_resolver_spec.rb
@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 RSpec.describe Hyrax::CompoundWorkResolver do
+  # Stub a Solr hit for `id` with the given fields (e.g. has_model_ssim/title).
+  def stub_solr(fields)
+    allow(Hyrax::SolrService).to receive(:query).and_return([fields].compact)
+  end
+
   describe '.url?' do
     it 'is true for http(s) URLs' do
       expect(described_class.url?('https://example.org/x')).to be true
@@ -18,48 +23,60 @@
     end
   end
 
-  describe '.title_and_path' do
-    let(:id) { 'work-123' }
+  describe '.resolve' do
+    let(:id) { 'rec-123' }
 
-    it 'resolves the title from Solr and the model-agnostic show path' do
-      allow(Hyrax::SolrService).to receive(:query)
-        .and_return([{ 'title_tesim' => ['Resolved Title'] }])
+    it 'links a work to its work show page' do
+      stub_solr('id' => id, 'title_tesim' => ['A Work'], 'has_model_ssim' => ['GenericWork'])
+      title, path = described_class.resolve(id)
+      expect(title).to eq('A Work')
+      expect(path).to eq("/concern/generic_works/#{id}")
+    end
 
-      title, path = described_class.title_and_path(id)
-      expect(title).to eq('Resolved Title')
-      expect(path).to eq('/catalog/work-123')
+    it 'links a collection to its collection show page' do
+      stub_solr('id' => id, 'title_tesim' => ['A Collection'], 'has_model_ssim' => [Hyrax.config.collection_model])
+      title, path = described_class.resolve(id)
+      expect(title).to eq('A Collection')
+      expect(path).to eq("/collections/#{id}")
     end
 
-    it 'falls back to the id when no title is indexed' do
-      allow(Hyrax::SolrService).to receive(:query).and_return([])
-      title, = described_class.title_and_path(id)
-      expect(title).to eq('work-123')
+    it 'falls back to the catalog route when the model is not a routable work/collection' do
+      stub_solr('id' => id, 'title_tesim' => ['Mystery'])
+      _title, path = described_class.resolve(id)
+      expect(path).to eq("/catalog/#{id}")
     end
 
-    it 'falls back to the id when the Solr lookup raises' do
+    it 'returns nil when nothing matches (so the caller renders plain text)' do
+      stub_solr(nil)
+      expect(described_class.resolve(id)).to be_nil
+    end
+
+    it 'returns nil when the Solr lookup raises' do
       allow(Hyrax::SolrService).to receive(:query).and_raise(StandardError)
-      title, = described_class.title_and_path(id)
-      expect(title).to eq('work-123')
+      expect(described_class.resolve(id)).to be_nil
     end
   end
 
-  describe '.resolve' do
-    let(:id) { 'work-123' }
+  describe '.title_and_path' do
+    let(:id) { 'rec-123' }
 
-    it 'returns [title, path] when a matching work is indexed' do
-      allow(Hyrax::SolrService).to receive(:query)
-        .and_return([{ 'title_tesim' => ['Resolved Title'] }])
-      expect(described_class.resolve(id)).to eq(['Resolved Title', '/catalog/work-123'])
+    it 'resolves the title and the work show path' do
+      stub_solr('id' => id, 'title_tesim' => ['Resolved Title'], 'has_model_ssim' => ['GenericWork'])
+      title, path = described_class.title_and_path(id)
+      expect(title).to eq('Resolved Title')
+      expect(path).to eq("/concern/generic_works/#{id}")
     end
 
-    it 'returns nil when no work matches (so the caller renders plain text)' do
-      allow(Hyrax::SolrService).to receive(:query).and_return([])
-      expect(described_class.resolve(id)).to be_nil
+    it 'falls back to the id when no record is indexed' do
+      stub_solr(nil)
+      title, = described_class.title_and_path(id)
+      expect(title).to eq(id)
     end
 
-    it 'returns nil when the Solr lookup raises' do
+    it 'falls back to the id when the Solr lookup raises' do
       allow(Hyrax::SolrService).to receive(:query).and_raise(StandardError)
-      expect(described_class.resolve(id)).to be_nil
+      title, = described_class.title_and_path(id)
+      expect(title).to eq(id)
     end
   end
 end

From 57ceb21b86bc512d24d678a25d5ec839c284e6b9 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Sat, 6 Jun 2026 01:17:49 -0400
Subject: [PATCH 25/32] Place compounds by their form primary flag
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A compound now renders in the form's primary section when it declares
`form: { primary: true }`, and in "Additional fields" otherwise —
matching how scalar terms split. The work and collection forms render
`primary_compound_terms` up top and `secondary_compound_terms` in the
collapsible section. The shipped samples demonstrate both: participants
and relationships are primary; identifiers and compound_rights are
additional.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app/forms/hyrax/forms/resource_form.rb        | 27 ++++++++++++++++++-
 app/views/hyrax/base/_form_metadata.html.erb  | 11 ++++++--
 .../dashboard/collections/_form.html.erb      | 11 ++++++--
 .../forms/compound_metadata_form_spec.rb      | 24 +++++++++++------
 4 files changed, 60 insertions(+), 13 deletions(-)

diff --git a/app/forms/hyrax/forms/resource_form.rb b/app/forms/hyrax/forms/resource_form.rb
index d0c2c4adff..39fa1aa44b 100644
--- a/app/forms/hyrax/forms/resource_form.rb
+++ b/app/forms/hyrax/forms/resource_form.rb
@@ -268,16 +268,41 @@ def compound_terms
         []
       end
 
+      ##
+      # @return [Array<Symbol>] compounds whose `form: { primary: true }`, shown
+      #   in the primary form section alongside the primary scalar terms.
+      def primary_compound_terms
+        compound_terms.select { |term| compound_primary?(term) }
+      end
+
+      ##
+      # @return [Array<Symbol>] compounds that are not primary (the default),
+      #   shown in the "Additional fields" section.
+      def secondary_compound_terms
+        compound_terms.reject { |term| compound_primary?(term) }
+      end
+
       ##
       # @return [Boolean] whether there are terms to display 'below-the-fold'
+      #   (secondary scalar terms or non-primary compounds)
       def display_additional_fields?
-        secondary_terms.any?
+        secondary_terms.any? || secondary_compound_terms.any?
       end
 
       delegate :flexible?, to: :model
 
       private
 
+      # Whether a compound declares `form: { primary: true }`. Defaults to false
+      # (compounds render in "Additional fields" unless explicitly primary),
+      # mirroring how secondary scalar terms are derived. Read from the compound
+      # definition, which carries the flag in both flex modes.
+      def compound_primary?(term)
+        Hyrax::CompoundSchema.for(model).primary?(term)
+      rescue StandardError
+        false
+      end
+
       def _form_field_definitions
         if model.flexible?
           singleton_class.schema_definitions
diff --git a/app/views/hyrax/base/_form_metadata.html.erb b/app/views/hyrax/base/_form_metadata.html.erb
index acd80ce473..bbf883d693 100644
--- a/app/views/hyrax/base/_form_metadata.html.erb
+++ b/app/views/hyrax/base/_form_metadata.html.erb
@@ -3,8 +3,10 @@
             <%= render_edit_field_partial(term, f: f) %>
           <% end %>
         </div>
-        <% if f.object.respond_to?(:compound_terms) %>
-          <% f.object.compound_terms.each do |term| %>
+        <%# Primary compounds (form: { primary: true }) render in the primary
+            section; non-primary compounds render in "Additional fields" below. %>
+        <% if f.object.respond_to?(:primary_compound_terms) %>
+          <% f.object.primary_compound_terms.each do |term| %>
             <%= render_compound_field(f, term) %>
           <% end %>
         <% end %>
@@ -21,5 +23,10 @@
             <% f.object.secondary_terms.each do |term| %>
               <%= render_edit_field_partial(term, f: f) %>
             <% end %>
+            <% if f.object.respond_to?(:secondary_compound_terms) %>
+              <% f.object.secondary_compound_terms.each do |term| %>
+                <%= render_compound_field(f, term) %>
+              <% end %>
+            <% end %>
           </div>
         <% end %>
diff --git a/app/views/hyrax/dashboard/collections/_form.html.erb b/app/views/hyrax/dashboard/collections/_form.html.erb
index 7b6b2c1488..a5c73f6946 100644
--- a/app/views/hyrax/dashboard/collections/_form.html.erb
+++ b/app/views/hyrax/dashboard/collections/_form.html.erb
@@ -49,8 +49,10 @@
                 <%= render_edit_field_partial(term, f: f) %>
               <% end %>
 
-              <% if f.object.respond_to?(:compound_terms) %>
-                <% f.object.compound_terms.each do |term| %>
+              <%# Primary compounds (form: { primary: true }) render here;
+                  non-primary compounds render in "Additional fields" below. %>
+              <% if f.object.respond_to?(:primary_compound_terms) %>
+                <% f.object.primary_compound_terms.each do |term| %>
                   <%= render_compound_field(f, term) %>
                 <% end %>
               <% end %>
@@ -74,6 +76,11 @@
                 <% f.object.secondary_terms.each do |term| %>
                   <%= render_edit_field_partial(term, f: f) %>
                 <% end %>
+                <% if f.object.respond_to?(:secondary_compound_terms) %>
+                  <% f.object.secondary_compound_terms.each do |term| %>
+                    <%= render_compound_field(f, term) %>
+                  <% end %>
+                <% end %>
               </div>
             <% end %>
             <%= hidden_field_tag :type, params[:type] %>
diff --git a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
index d480c8ceb1..5eea5d390d 100644
--- a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
+++ b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
@@ -56,6 +56,14 @@
       expect(form.secondary_terms).not_to include(:participants, :identifiers, :compound_rights)
     end
 
+    it 'partitions compounds by their form: { primary: } flag' do
+      # The shipped samples declare `participants` and `relationships` primary;
+      # `identifiers` and `compound_rights` are non-primary ("Additional fields").
+      expect(form.primary_compound_terms).to contain_exactly(:participants, :relationships)
+      expect(form.secondary_compound_terms).to contain_exactly(:identifiers, :compound_rights)
+      expect(form.display_additional_fields?).to be true
+    end
+
     it 'registers `participants_attributes` as a real Reform property (not just method-missing)' do
       # This is the property that has to exist in Reform's schema *before*
       # validate runs; if it is registered too late the populator never fires.
@@ -70,35 +78,35 @@
   describe 'validate + sync writes the compound to the model' do
     let(:params) do
       { 'participants_attributes' =>
-          { '0' => { 'title' => 'Dr', 'participant_name' => 'Ada Lovelace', 'participant_role' => 'Author' } },
+          { '0' => { 'participant_title' => 'Dr', 'participant_name' => 'Ada Lovelace', 'participant_role' => 'Author' } },
         'identifiers_attributes' =>
-          { '0' => { 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' } } }
+          { '0' => { 'identifier_value' => '10.1234/x', 'identifier_type' => 'DOI' } } }
     end
 
     it 'populates the compound on the form during validate' do
       form.validate(params)
       expect(form.participants)
-        .to eq([{ 'title' => 'Dr', 'participant_name' => 'Ada Lovelace', 'participant_role' => 'Author' }])
+        .to eq([{ 'participant_title' => 'Dr', 'participant_name' => 'Ada Lovelace', 'participant_role' => 'Author' }])
       expect(form.identifiers)
-        .to eq([{ 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' }])
+        .to eq([{ 'identifier_value' => '10.1234/x', 'identifier_type' => 'DOI' }])
     end
 
     it 'writes the compound through to the model on sync' do
       form.validate(params)
       form.sync
       expect(form.model.participants)
-        .to eq([{ 'title' => 'Dr', 'participant_name' => 'Ada Lovelace', 'participant_role' => 'Author' }])
+        .to eq([{ 'participant_title' => 'Dr', 'participant_name' => 'Ada Lovelace', 'participant_role' => 'Author' }])
       expect(form.model.identifiers)
-        .to eq([{ 'identifier' => '10.1234/x', 'identifier_type' => 'DOI' }])
+        .to eq([{ 'identifier_value' => '10.1234/x', 'identifier_type' => 'DOI' }])
     end
 
     it 'drops `_destroy` and all-blank rows' do
       form.validate('participants_attributes' =>
         { '0' => { 'participant_name' => 'Keep', 'participant_role' => 'Author' },
           '1' => { 'participant_name' => 'Remove', '_destroy' => 'true' },
-          '2' => { 'title' => '', 'participant_name' => '', 'participant_role' => '' } })
+          '2' => { 'participant_title' => '', 'participant_name' => '', 'participant_role' => '' } })
       form.sync
-      expect(form.model.participants).to eq([{ 'title' => nil, 'participant_name' => 'Keep', 'participant_role' => 'Author' }])
+      expect(form.model.participants).to eq([{ 'participant_title' => nil, 'participant_name' => 'Keep', 'participant_role' => 'Author' }])
     end
   end
 

From d2f95a7f63083527ccd6b3e120be80f6a862f9a2 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Sat, 6 Jun 2026 01:43:50 -0400
Subject: [PATCH 26/32] Guard nil flexible schema when resolving attributes

The m3 schema loader could call `attributes_for` on a nil schema:
`find_by(id: version)` misses on an unknown version and
`create_default_schema` returns nil when a row already exists, so on a
fresh database or early boot the loader raised `NoMethodError`. It now
falls back to the latest schema and, failing that, the default attribute
set.
---
 app/services/hyrax/m3_schema_loader.rb | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/app/services/hyrax/m3_schema_loader.rb b/app/services/hyrax/m3_schema_loader.rb
index a5d7cd35ba..78ff74183d 100644
--- a/app/services/hyrax/m3_schema_loader.rb
+++ b/app/services/hyrax/m3_schema_loader.rb
@@ -67,8 +67,7 @@ def raw_definitions(schema_name, version, contexts = nil)
     # The schema's attributes after context filtering (but before the
     # subproperty exclusion {#definitions} applies). Yields `[name, config]`.
     def contextual_attributes(schema_name, version, contexts = nil)
-      schema = Hyrax::FlexibleSchema.find_by(id: version) || Hyrax::FlexibleSchema.create_default_schema
-      attributes = schema.attributes_for(schema_name)
+      attributes = resolve_schema(version)&.attributes_for(schema_name)
       attributes ||= fallback_schema_for(schema_name)
       attributes.filter_map do |name, config|
         # We might be able to consolidate these conditions, but they have been kept separate to make it easier to reason about
@@ -83,6 +82,17 @@ def contextual_attributes(schema_name, version, contexts = nil)
       end
     end
 
+    # The flexible schema to read attributes from: the requested version, else a
+    # freshly-created default, else the latest existing row. Any of these may be
+    # nil during early boot or on a fresh DB, so callers must guard with `&.`.
+    # (`create_default_schema` returns nil when a row already exists; `find_by`
+    # misses when `version` is unknown.)
+    def resolve_schema(version)
+      Hyrax::FlexibleSchema.find_by(id: version) ||
+        Hyrax::FlexibleSchema.create_default_schema ||
+        Hyrax::FlexibleSchema.order(:created_at).last
+    end
+
     # rubocop:disable Metrics/MethodLength
     def fallback_schema_for(_schema_name)
       { "title" =>

From 845551f49ba966c8a8a29a4867a999041518f334 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Sat, 6 Jun 2026 14:14:53 -0400
Subject: [PATCH 27/32] Share row-coercion plumbing across field behaviors

The redirects and compound form populators read their submitted
nested-attributes fragment through a shared
Hyrax::CompoundRowPlumbing module rather than each defining its own
identical fragment-coercion helpers.

Each populator keeps its own row-drop rule and value normalization;
only the shape coercion (unwrapping ActionController::Parameters) is
shared, so form behavior is unchanged in both flex modes.
---
 .../concerns/hyrax/compound_field_behavior.rb | 13 ++++------
 .../concerns/hyrax/compound_row_plumbing.rb   | 24 +++++++++++++++++++
 .../hyrax/redirects_field_behavior.rb         | 11 ++++-----
 3 files changed, 33 insertions(+), 15 deletions(-)
 create mode 100644 app/forms/concerns/hyrax/compound_row_plumbing.rb

diff --git a/app/forms/concerns/hyrax/compound_field_behavior.rb b/app/forms/concerns/hyrax/compound_field_behavior.rb
index 1897f53ef6..f018b9127b 100644
--- a/app/forms/concerns/hyrax/compound_field_behavior.rb
+++ b/app/forms/concerns/hyrax/compound_field_behavior.rb
@@ -8,6 +8,8 @@ module Hyrax
   # model and wires each one's virtual `<name>_attributes` property and
   # populator from the schema, in both flex modes.
   module CompoundFieldBehavior
+    include Hyrax::CompoundRowPlumbing
+
     # Register the virtual `<name>_attributes` populator properties on the
     # singleton class for every compound on the resource. Must run before Reform
     # builds the deserialization schema; the flexible-mode init path calls this,
@@ -30,7 +32,7 @@ def register_compound_fields!(resource)
 
     # Strip each compound's renamed bare key so the `<name>_attributes`
     # populator is the single write entry point (the Field Behavior contract;
-    # see documentation/forms/field_behaviors.md).
+    # see documentation/field_behaviors.md).
     def deserialize!(params)
       result = super
       return result unless result.respond_to?(:delete)
@@ -64,21 +66,16 @@ def compound_attributes_populator(fragment:, as:, **_options)
     end
 
     def build_compound_rows(fragment, allowed_keys)
-      compound_fragment_pairs(fragment)
+      fragment_pairs(fragment)
         .sort_by { |key, _row| key.to_i }
         .map { |_key, row| compound_row_from(row, allowed_keys) }
         .compact
     end
 
-    def compound_fragment_pairs(fragment)
-      return {} if fragment.nil?
-      fragment.respond_to?(:to_unsafe_h) ? fragment.to_unsafe_h : fragment.to_h
-    end
-
     # Returns nil for a row marked for destruction or whose declared sub-properties
     # are all blank, otherwise the persisted hash for that row.
     def compound_row_from(row, allowed_keys)
-      row = row.respond_to?(:to_unsafe_h) ? row.to_unsafe_h : row.to_h
+      row = row_hash(row)
       return nil if %w[true 1].include?(row['_destroy'].to_s)
 
       entry = allowed_keys.each_with_object({}) do |key, memo|
diff --git a/app/forms/concerns/hyrax/compound_row_plumbing.rb b/app/forms/concerns/hyrax/compound_row_plumbing.rb
new file mode 100644
index 0000000000..3be52ab776
--- /dev/null
+++ b/app/forms/concerns/hyrax/compound_row_plumbing.rb
@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hyrax
+  # Shared coercion of a nested-attributes fragment into plain Ruby hashes,
+  # used by both {Hyrax::CompoundFieldBehavior} and
+  # {Hyrax::RedirectsFieldBehavior}. It only normalizes shape (unwrapping
+  # `ActionController::Parameters` via `to_unsafe_h`); the row-drop rules
+  # (`_destroy`, blank paths, all-blank rows) and any value normalization stay
+  # in each populator.
+  module CompoundRowPlumbing
+    private
+
+    # The submitted `<name>_attributes` payload as a `{ index => row }` hash.
+    def fragment_pairs(fragment)
+      return {} if fragment.nil?
+      fragment.respond_to?(:to_unsafe_h) ? fragment.to_unsafe_h : fragment.to_h
+    end
+
+    # A single row as a plain hash.
+    def row_hash(row)
+      row.respond_to?(:to_unsafe_h) ? row.to_unsafe_h : row.to_h
+    end
+  end
+end
diff --git a/app/forms/concerns/hyrax/redirects_field_behavior.rb b/app/forms/concerns/hyrax/redirects_field_behavior.rb
index dbe30d17f9..b55565c85d 100644
--- a/app/forms/concerns/hyrax/redirects_field_behavior.rb
+++ b/app/forms/concerns/hyrax/redirects_field_behavior.rb
@@ -28,6 +28,8 @@ module Hyrax
   # `Flipflop.redirects?` directly is unsafe when the config is off
   # because the feature isn't registered in that case.
   module RedirectsFieldBehavior
+    include Hyrax::CompoundRowPlumbing
+
     def self.included(descendant)
       return unless Hyrax.config.redirects_enabled?
       # Declare the radio-group scalar before redirects_attributes so Reform
@@ -66,19 +68,14 @@ def deserialize!(params)
     def redirects_attributes_populator(fragment:, **_options)
       return unless respond_to?(:redirects)
       return unless Hyrax.config.redirects_active?
-      pairs = redirects_fragment_pairs(fragment)
+      pairs = fragment_pairs(fragment)
       self.redirects = pairs.sort_by { |k, _row| k.to_i }
                             .map { |k, row| redirects_entry_from(k, row) }
                             .compact
     end
 
-    def redirects_fragment_pairs(fragment)
-      return {} if fragment.nil?
-      fragment.respond_to?(:to_unsafe_h) ? fragment.to_unsafe_h : fragment.to_h
-    end
-
     def redirects_entry_from(key, row)
-      row = row.respond_to?(:to_unsafe_h) ? row.to_unsafe_h : row
+      row = row_hash(row)
       return nil if row['_destroy'].to_s == 'true' || row['path'].to_s.strip.empty?
       { 'path' => Hyrax::RedirectPathNormalizer.call(row['path']),
         'is_display_url' => redirects_is_display_url_flag_for(key, row) }

From 654c03d01f8eca0fb1d66f776f9d2a5179f580c0 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Sat, 6 Jun 2026 14:16:13 -0400
Subject: [PATCH 28/32] Clean up compound vs. field-behavior documentation

The compound and field-behavior docs now live at documentation/ (no
longer under forms/) and spell out when to declare a compound versus
hand-write a field behavior: redirects and based_near stay field
behaviors because moving them onto the compound machinery would
change persisted shape or behavior, not refactor it.

References to the two docs areupdated to the new paths.
---
 app/helpers/hyrax/collections_helper.rb       |  2 +-
 app/helpers/hyrax/compound_fields_helper.rb   |  2 +-
 .../hyrax/indexers/compound_indexer.rb        |  2 +-
 .../hyrax/indexers/pcdm_collection_indexer.rb |  2 +-
 .../hyrax/indexers/pcdm_object_indexer.rb     |  2 +-
 .../concerns/hyrax/solr_document/metadata.rb  |  2 +-
 app/models/hyrax/pcdm_collection.rb           |  2 +-
 app/models/hyrax/work.rb                      |  2 +-
 app/presenters/hyrax/collection_presenter.rb  |  2 +-
 .../hyrax/compound_entry_validation.rb        |  2 +-
 app/services/hyrax/compound_schema.rb         |  4 +-
 .../compound_validator.rb                     |  2 +-
 .../hyrax/compound_entry_validator.rb         |  2 +-
 .../compounds/_compound_section.html.erb      |  2 +-
 documentation/{forms => }/compound_fields.md  | 31 +++++++++--
 documentation/{forms => }/field_behaviors.md  | 53 +++++++++++++++----
 documentation/redirects.md                    |  4 +-
 lib/hyrax/configuration.rb                    |  2 +-
 spec/models/solr_document_spec.rb             |  2 +-
 19 files changed, 90 insertions(+), 32 deletions(-)
 rename documentation/{forms => }/compound_fields.md (92%)
 rename documentation/{forms => }/field_behaviors.md (84%)

diff --git a/app/helpers/hyrax/collections_helper.rb b/app/helpers/hyrax/collections_helper.rb
index 70cfbc3307..ba90fdb738 100644
--- a/app/helpers/hyrax/collections_helper.rb
+++ b/app/helpers/hyrax/collections_helper.rb
@@ -45,7 +45,7 @@ def collection_metadata_value(collection, field)
       # Compounds render through the shared CompoundAttributeRenderer, resolving
       # the definition from the presenter's document (correct in flexible mode).
       # Collection scalar values render as bare spans (no `ul.tabular`), so the
-      # entries render flush to match. See documentation/forms/compound_fields.md.
+      # entries render flush to match. See documentation/compound_fields.md.
       if collection.respond_to?(:compound_term?) && collection.compound_term?(field)
         definition = compound_schema_for(collection).definition_for(field)
         return Hyrax::Renderers::CompoundAttributeRenderer
diff --git a/app/helpers/hyrax/compound_fields_helper.rb b/app/helpers/hyrax/compound_fields_helper.rb
index aac4e5722b..effc34590e 100644
--- a/app/helpers/hyrax/compound_fields_helper.rb
+++ b/app/helpers/hyrax/compound_fields_helper.rb
@@ -2,7 +2,7 @@
 
 module Hyrax
   # View helpers for rendering compound (hierarchical) metadata fields on forms
-  # and show pages. See documentation/forms/compound_fields.md.
+  # and show pages. See documentation/compound_fields.md.
   module CompoundFieldsHelper
     ##
     # Renders one compound section (a repeatable stack of sub-property rows) for the
diff --git a/app/indexers/hyrax/indexers/compound_indexer.rb b/app/indexers/hyrax/indexers/compound_indexer.rb
index 33fd72e80f..257f42ae82 100644
--- a/app/indexers/hyrax/indexers/compound_indexer.rb
+++ b/app/indexers/hyrax/indexers/compound_indexer.rb
@@ -7,7 +7,7 @@ module Indexers
     # every compound on the resource (see {Hyrax::CompoundSchema}), it writes
     # each sub-property's declared `index_keys:`/`indexing:` Solr fields and
     # stores the displayable rows as a `<compound>_json_ss` blob the show page
-    # renders from. See documentation/forms/compound_fields.md.
+    # renders from. See documentation/compound_fields.md.
     #
     # @example
     #   class WorkIndexer < Hyrax::Indexers::PcdmObjectIndexer
diff --git a/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb b/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
index ca3daa6726..77c58a3b69 100644
--- a/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
+++ b/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
@@ -12,7 +12,7 @@ class PcdmCollectionIndexer < Hyrax::Indexers::ResourceIndexer
       include Hyrax::Indexer(:core_metadata) if Hyrax.config.collection_include_metadata?
       include Hyrax::Indexers::RedirectsIndexer if Hyrax.config.redirects_enabled?
       # Flatten compound (hierarchical) metadata sub-properties into Solr. No-op for
-      # collections without compounds. See documentation/forms/compound_fields.md.
+      # collections without compounds. See documentation/compound_fields.md.
       include Hyrax::Indexers::CompoundIndexer if Hyrax.config.compound_metadata_enabled?
       check_if_flexible(Hyrax::PcdmCollection)
 
diff --git a/app/indexers/hyrax/indexers/pcdm_object_indexer.rb b/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
index 7cb547a646..907365367c 100644
--- a/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
+++ b/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
@@ -12,7 +12,7 @@ class PcdmObjectIndexer < Hyrax::Indexers::ResourceIndexer
       include Hyrax::WorkflowIndexer
       include Hyrax::Indexers::RedirectsIndexer if Hyrax.config.redirects_enabled?
       # Flatten compound (hierarchical) metadata sub-properties into Solr. No-op for
-      # resources without compounds. See documentation/forms/compound_fields.md.
+      # resources without compounds. See documentation/compound_fields.md.
       include Hyrax::Indexers::CompoundIndexer if Hyrax.config.compound_metadata_enabled?
 
       def to_solr # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
diff --git a/app/models/concerns/hyrax/solr_document/metadata.rb b/app/models/concerns/hyrax/solr_document/metadata.rb
index 1e4e63ca85..637f561a61 100644
--- a/app/models/concerns/hyrax/solr_document/metadata.rb
+++ b/app/models/concerns/hyrax/solr_document/metadata.rb
@@ -12,7 +12,7 @@ def attribute(name, type, field)
 
         # Declare a reader for a compound attribute, parsing the rows the
         # indexer stored in `<name>_json_ss`. See
-        # documentation/forms/compound_fields.md.
+        # documentation/compound_fields.md.
         def compound_attribute(name)
           define_method name do
             Solr::CompoundEntries.coerce(self["#{name}_json_ss"])
diff --git a/app/models/hyrax/pcdm_collection.rb b/app/models/hyrax/pcdm_collection.rb
index 52ce21ff91..f412664514 100644
--- a/app/models/hyrax/pcdm_collection.rb
+++ b/app/models/hyrax/pcdm_collection.rb
@@ -47,7 +47,7 @@ class PcdmCollection < Hyrax::Resource
 
     # Sample compound metadata, mirroring Hyrax::Work. In flexible mode the
     # compounds come from the m3 profile, so only the read-path normalization is
-    # included here. See documentation/forms/compound_fields.md.
+    # included here. See documentation/compound_fields.md.
     if Hyrax.config.compound_metadata_enabled?
       include Hyrax::Schema(:compound_metadata) unless Hyrax.config.flexible?
       include Hyrax::CompoundNormalization
diff --git a/app/models/hyrax/work.rb b/app/models/hyrax/work.rb
index d300fcd722..1c6c9a6ba7 100644
--- a/app/models/hyrax/work.rb
+++ b/app/models/hyrax/work.rb
@@ -101,7 +101,7 @@ class Work < Hyrax::Resource
 
     # Sample compound metadata. In flexible mode the compounds come from the m3
     # profile, so only the read-path normalization is included here. See
-    # documentation/forms/compound_fields.md.
+    # documentation/compound_fields.md.
     if Hyrax.config.compound_metadata_enabled?
       include Hyrax::Schema(:compound_metadata) unless Hyrax.config.flexible?
       include Hyrax::CompoundNormalization
diff --git a/app/presenters/hyrax/collection_presenter.rb b/app/presenters/hyrax/collection_presenter.rb
index 61c6a1fb08..dca38309ca 100644
--- a/app/presenters/hyrax/collection_presenter.rb
+++ b/app/presenters/hyrax/collection_presenter.rb
@@ -69,7 +69,7 @@ def terms_with_values
 
     # Inline compound terms for this collection (card compounds render
     # separately via `render_compound_cards`). Resolved from the backing
-    # document. See documentation/forms/compound_fields.md.
+    # document. See documentation/compound_fields.md.
     def compound_terms
       return [] unless Hyrax.config.compound_metadata_enabled?
       compound_schema.inline_compound_names
diff --git a/app/services/hyrax/compound_entry_validation.rb b/app/services/hyrax/compound_entry_validation.rb
index 737ebe906a..926ed26616 100644
--- a/app/services/hyrax/compound_entry_validation.rb
+++ b/app/services/hyrax/compound_entry_validation.rb
@@ -7,7 +7,7 @@ module Hyrax
   # Pure validation logic for a single compound's entries, decoupled from
   # ActiveModel and Reform so it can be reused (e.g. a future Bulkrax-side
   # check) and unit-tested directly. {Hyrax::CompoundEntryValidator} wraps this
-  # for the form layer. See documentation/forms/compound_fields.md.
+  # for the form layer. See documentation/compound_fields.md.
   #
   # Rules (driven by the normalized definition from {Hyrax::CompoundSchema}):
   #   * a compound marked `required` must have at least one populated row;
diff --git a/app/services/hyrax/compound_schema.rb b/app/services/hyrax/compound_schema.rb
index 3c7f415452..aede55fc9d 100644
--- a/app/services/hyrax/compound_schema.rb
+++ b/app/services/hyrax/compound_schema.rb
@@ -8,7 +8,7 @@ module Hyrax
   # is a `type: hash, multiple: true` parent property; its members are declared
   # as separate properties pointing back with `subproperty_of: <parent>`. The
   # declaration drives the generic form, indexer, and renderer so a hierarchical
-  # field can be defined in YAML alone. See documentation/forms/compound_fields.md.
+  # field can be defined in YAML alone. See documentation/compound_fields.md.
   #
   # The schema loaders exclude subproperties from a resource's real attributes
   # (so they get no accessor of their own) but fold each compound's members into
@@ -210,7 +210,7 @@ def name_meta_pairs(schema)
 
     # Normalizes a parent config plus its (folded) child configs into the
     # symbol-keyed shape the form, indexer, and renderer consume. See
-    # documentation/forms/compound_fields.md for the meaning of each key.
+    # documentation/compound_fields.md for the meaning of each key.
     def normalize(config, children)
       sub = children.each_with_object({}) { |(key, opts), memo| memo[key.to_s] = normalize_subproperty(opts) }
 
diff --git a/app/services/hyrax/flexible_schema_validators/compound_validator.rb b/app/services/hyrax/flexible_schema_validators/compound_validator.rb
index a5d2447347..563756838c 100644
--- a/app/services/hyrax/flexible_schema_validators/compound_validator.rb
+++ b/app/services/hyrax/flexible_schema_validators/compound_validator.rb
@@ -10,7 +10,7 @@ module FlexibleSchemaValidators
     # fields or unrenderable values. A compound is a `type: hash` parent with
     # members declared as separate properties pointing back via
     # `subproperty_of: <parent>` — see {Hyrax::CompoundSchema}. See
-    # documentation/forms/compound_fields.md for the rules.
+    # documentation/compound_fields.md for the rules.
     class CompoundValidator
       ##
       # @param profile [Hash] the flexible metadata profile
diff --git a/app/validators/hyrax/compound_entry_validator.rb b/app/validators/hyrax/compound_entry_validator.rb
index 5b47afc1da..952ccd40f1 100644
--- a/app/validators/hyrax/compound_entry_validator.rb
+++ b/app/validators/hyrax/compound_entry_validator.rb
@@ -9,7 +9,7 @@ module Hyrax
   # Record-level (not an EachValidator) because the compound set is schema-driven
   # and not known at form-class-definition time. The per-compound rules live in
   # the reusable {Hyrax::CompoundEntryValidation}. See
-  # documentation/forms/compound_fields.md.
+  # documentation/compound_fields.md.
   class CompoundEntryValidator < ActiveModel::Validator
     def validate(record)
       return unless Hyrax.config.compound_metadata_enabled?
diff --git a/app/views/hyrax/compounds/_compound_section.html.erb b/app/views/hyrax/compounds/_compound_section.html.erb
index bd80b032f7..5255d588c6 100644
--- a/app/views/hyrax/compounds/_compound_section.html.erb
+++ b/app/views/hyrax/compounds/_compound_section.html.erb
@@ -1,6 +1,6 @@
 <%# Renders one compound-attribute section: a repeatable stack of cards, one
     per entry. Schema-driven via the `definition` local. See
-    documentation/forms/compound_fields.md.
+    documentation/compound_fields.md.
 
     Locals:
       f             - form builder for the parent resource
diff --git a/documentation/forms/compound_fields.md b/documentation/compound_fields.md
similarity index 92%
rename from documentation/forms/compound_fields.md
rename to documentation/compound_fields.md
index 7df4cc2677..b58abbbff3 100644
--- a/documentation/forms/compound_fields.md
+++ b/documentation/compound_fields.md
@@ -12,6 +12,28 @@ schema under `HYRAX_FLEXIBLE=false`, or the m3 profile under
 form input, populator, and indexer all read the declaration from the schema
 and behave identically in both flex modes.
 
+## When to use a compound vs. a Field Behavior
+
+A compound is the **default** for any field whose entries are a hash of named
+sub-properties (each an open-entry string or a controlled-vocabulary lookup):
+declare it in the schema and the generic form, populator, indexer, and renderer
+do the rest, with no per-field Ruby or ERB.
+
+Reach for a hand-written [Field Behavior](field_behaviors.md) only for the
+narrow cases the generic path does not cover:
+
+- **A single value per entry** rather than a hash of sub-properties — e.g. a
+  controlled-vocabulary URI string wrapped in a presenter for the form
+  (`Hyrax::BasedNearFieldBehavior`).
+- **Bespoke per-field behavior** — a radio-group selection, write-time value
+  normalization, global-uniqueness validation against a separate table, or
+  feature gating (`Hyrax::RedirectsFieldBehavior`).
+
+`Hyrax::CompoundFieldBehavior` is itself a Field Behavior — the generic,
+schema-driven one — so the two mechanisms share the same Reform contract
+(documented in [`field_behaviors.md`](field_behaviors.md)); a compound is the
+case where that contract is satisfied entirely from the schema.
+
 ## Declaring a compound
 
 A compound is a `type: hash, multiple: true` **parent** property. Its members
@@ -133,9 +155,12 @@ can read. The picker is mounted as the `compound_works` QA authority at
 `/authorities/search/compound_works`.
 
 `db_table` (a typeahead backed by an ActiveRecord lookup table, with
-add-new) and `geocode` (a Geonames/coordinate lookup, like `based_near`) are
-planned additional sub-property types; the form's row partial has an explicit
-extension point for them.
+add-new) and `geocode` (a Geonames/coordinate lookup) are planned additional
+sub-property types; the form's row partial has an explicit extension point for
+them. `geocode` generalizes the existing single-value controlled-URI location
+field — see `Hyrax::BasedNearFieldBehavior` and
+[`field_behaviors.md`](field_behaviors.md), which `geocode` is intended to
+replace once it lands.
 
 ### Grouping (`group:` + `groups:`, optional)
 
diff --git a/documentation/forms/field_behaviors.md b/documentation/field_behaviors.md
similarity index 84%
rename from documentation/forms/field_behaviors.md
rename to documentation/field_behaviors.md
index 95c6d3856c..7c711d70c0 100644
--- a/documentation/forms/field_behaviors.md
+++ b/documentation/field_behaviors.md
@@ -15,16 +15,15 @@ Two examples ship with Hyrax:
 
 This document covers the contract a Field Behavior must satisfy, the decision points for a new behavior, and the worked examples.
 
-> **For new multi-sub-property compounds, prefer the generic, schema-driven path.**
-> A field whose entries are a hash of named sub-properties (each an open-entry
-> string or a controlled-vocabulary lookup) can be declared entirely in the
-> schema YAML / m3 profile and rendered, populated, and indexed with no
-> per-field Ruby or ERB — see [`compound_fields.md`](compound_fields.md). The
-> hand-written Field Behaviors documented below remain the right tool for
-> special cases: single-value-per-entry controlled URIs with a presenter
-> (`based_near`), or compounds with bespoke behavior such as a radio-group
-> selection, write-time normalization, global-uniqueness validation, or
-> feature gating (`redirects`).
+> **For a field whose entries are a hash of named sub-properties, prefer a
+> [compound](compound_fields.md) instead** — it satisfies this same contract
+> from the schema alone, with no per-field Ruby or ERB.
+> [`compound_fields.md`](compound_fields.md) covers when to use a compound vs. a
+> hand-written Field Behavior. The behaviors documented below are the right tool
+> for the cases a compound does not cover: a single controlled-URI value per
+> entry wrapped in a presenter (`based_near`), or bespoke behavior such as a
+> radio-group selection, write-time normalization, global-uniqueness validation,
+> or feature gating (`redirects`).
 
 ## Why this pattern exists
 
@@ -205,6 +204,21 @@ end
 - **View-side shape:** array of `Hyrax::ControlledVocabularies::Location` instances.
 - **Diff from a plain `_attributes` setup:** `deserialize!` strips `based_near` after the rename so `from_hash` doesn't overwrite the property with raw fragment hashes; the populator merges adds/removes onto the existing `model.based_near` so partial form submissions are non-destructive.
 
+`based_near` is **not** a [compound](compound_fields.md), for two reasons that
+make a compound the wrong fit rather than just an unused option:
+
+- Its persisted shape is a **bare URI string per entry**, where a compound
+  persists a hash of named sub-properties per entry. Declaring it as a compound
+  would change the stored shape from `["uri"]` to `[{ "key" => "uri" }]` — a data
+  migration, not a refactor.
+- Its populator **merges** (`(model.based_near + adds) - deletes`) rather than
+  replacing the whole array, so partial submissions are non-destructive; the
+  generic compound populator always writes a full replacement array.
+
+It is the reference case for the planned `geocode` compound sub-property type
+(see [`compound_fields.md`](compound_fields.md)), which will generalize a
+single-value controlled-URI location lookup once it lands.
+
 ## Example: `RedirectsFieldBehavior`
 
 ```ruby
@@ -250,6 +264,25 @@ The populator folds a sibling `redirects_display_url_index` scalar (a single rad
 - **View-side shape:** array of `Hyrax::Redirect` presenters, exposing `.path` and `.is_display_url`. The form partial wraps each persisted hash inline rather than via a prepopulator.
 - **Diff from BasedNear:** entries carry multiple sub-properties, so the persisted shape is a hash rather than a string. The populator normalizes paths up front (canonical form lives in storage). The behavior is feature-gated — every callback consults `Hyrax.config.redirects_active?`.
 
+`redirects` already uses the compound **parent** shape (`type: hash, multiple:
+true`), but it is intentionally **not** declared with `subproperty_of: redirects`
+children, so [`Hyrax::CompoundSchema`](compound_fields.md) does not treat it as a
+compound. Declaring those children would activate the whole generic compound
+stack — indexer, `render_as: compound` renderer, `Hyrax::CompoundEntryValidator`,
+`Hyrax::CompoundNormalization`, the `_compound_section` partial, and a second
+`redirects_attributes` populator — which would collide with the redirects-specific
+`RedirectsLabelAttributeRenderer`, indexer, `RedirectValidator`,
+`RedirectsNormalization`, and `_form_redirects` partial. That is a functional
+change, not a refactor. The populator also folds the sibling
+`redirects_display_url_index` radio scalar into per-row `is_display_url` flags and
+normalizes each path — neither of which the generic compound populator does.
+
+The populator does share its fragment-coercion plumbing with the compound
+populator: both include `Hyrax::CompoundRowPlumbing` for `fragment_pairs`
+and `row_hash`. Each keeps its own row-drop rule (redirects drops blank-path rows;
+the compound drops all-blank rows) and its own value handling (redirects
+normalizes the path) — only the shape coercion is shared.
+
 ## Wiring on `ResourceForm`
 
 ```ruby
diff --git a/documentation/redirects.md b/documentation/redirects.md
index 733846a7e2..2c03eddfb3 100644
--- a/documentation/redirects.md
+++ b/documentation/redirects.md
@@ -362,7 +362,7 @@ Add to the host app's Bulkrax field-mapping configuration (usually `config/initi
 'is_display_url' => { from: ['redirect_is_display_url'], object: 'redirects', nested_attributes: true }
 ```
 
-See [field_behaviors.md](forms/field_behaviors.md#wiring-up-bulkrax-imports) for the conventions around the `nested_attributes: true` flag.
+See [field_behaviors.md](field_behaviors.md#wiring-up-bulkrax-imports) for the conventions around the `nested_attributes: true` flag.
 
 ### Reserved-prefix list
 
@@ -412,7 +412,7 @@ Alternatively, gate the inclusion of the calling code itself on `Hyrax.config.re
 ## See also
 
 - `documentation/flexible_metadata.md` — m3 profile fundamentals and how the redirects feature interacts with flexible metadata.
-- `documentation/forms/field_behaviors.md` — the Field Behavior pattern used by `Hyrax::RedirectsFieldBehavior` to wire the form's nested-attribute property.
+- `documentation/field_behaviors.md` — the Field Behavior pattern used by `Hyrax::RedirectsFieldBehavior` to wire the form's nested-attribute property.
 - `Hyrax::Redirect` (`app/models/hyrax/redirect.rb`) — thin Ruby presenter for a single redirect entry; used on the form's render path.
 - `Hyrax::RedirectsFieldBehavior` (`app/forms/concerns/hyrax/redirects_field_behavior.rb`) — form-side wiring for the `redirects_attributes` virtual property and the `redirects_display_url_index` radio-group scalar. Owns the populator (which folds the radio-group index into per-row `is_display_url` flags) and the `deserialize!` strip for the nested-attributes payload. The form partial wraps each persisted hash in a `Hyrax::Redirect` presenter inline at render time.
 - `Hyrax::Indexers::RedirectsIndexer` (`app/indexers/hyrax/indexers/redirects_indexer.rb`) — the indexer mixin. Writes `redirects_path_tesim` to the Solr document for show-page rendering.
diff --git a/lib/hyrax/configuration.rb b/lib/hyrax/configuration.rb
index c6e74dd23d..adf59c4c7a 100644
--- a/lib/hyrax/configuration.rb
+++ b/lib/hyrax/configuration.rb
@@ -353,7 +353,7 @@ def redirects_enabled?
     # Whether the sample compound metadata schema ships on works and collections
     # by default. Defaults to true; respects +HYRAX_COMPOUND_METADATA_ENABLED+.
     #
-    # @see documentation/forms/compound_fields.md
+    # @see documentation/compound_fields.md
     attr_writer :compound_metadata_enabled
     def compound_metadata_enabled?
       return @compound_metadata_enabled if defined?(@compound_metadata_enabled) && !@compound_metadata_enabled.nil?
diff --git a/spec/models/solr_document_spec.rb b/spec/models/solr_document_spec.rb
index cc82fd1427..ee1554635a 100644
--- a/spec/models/solr_document_spec.rb
+++ b/spec/models/solr_document_spec.rb
@@ -247,7 +247,7 @@ class Mimes
     # blob. The document defines a reader per such field at construction, so an
     # application's own compounds render without a per-app declaration and
     # without depending on the (possibly stale) flexible schema. See
-    # documentation/forms/compound_fields.md.
+    # documentation/compound_fields.md.
     let(:attributes) do
       { 'contributors_json_ss' =>
           [%([{"given_name":"Grace","family_name":"Hopper"}])],

From fe4aece359e8952db678f9b33fbc874908c63898 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Sat, 6 Jun 2026 14:34:57 -0400
Subject: [PATCH 29/32] Remove config flag for compound metadata

The feature was on by default and had no reason to be toggleable;
applications that want to drop the sample compounds override the
schema in their own app instead.
---
 .../concerns/hyrax/flexible_form_behavior.rb      |  1 -
 app/forms/hyrax/forms.rb                          |  2 +-
 app/forms/hyrax/forms/pcdm_collection_form.rb     |  2 +-
 app/forms/hyrax/forms/resource_form.rb            |  6 ++----
 .../hyrax/indexers/pcdm_collection_indexer.rb     |  2 +-
 .../hyrax/indexers/pcdm_object_indexer.rb         |  2 +-
 app/models/hyrax/pcdm_collection.rb               |  6 ++----
 app/models/hyrax/work.rb                          |  6 ++----
 app/presenters/hyrax/collection_presenter.rb      |  2 --
 app/validators/hyrax/compound_entry_validator.rb  |  2 --
 config/metadata/compound_metadata.yaml            |  2 +-
 documentation/compound_fields.md                  | 15 ++++++---------
 lib/hyrax/configuration.rb                        | 11 -----------
 .../hyrax/forms/compound_metadata_form_spec.rb    |  1 -
 .../hyrax/forms/pcdm_collection_form_spec.rb      |  2 +-
 .../presenters/hyrax/collection_presenter_spec.rb |  8 --------
 .../hyrax/compound_entry_validator_spec.rb        | 11 -----------
 17 files changed, 18 insertions(+), 63 deletions(-)

diff --git a/app/forms/concerns/hyrax/flexible_form_behavior.rb b/app/forms/concerns/hyrax/flexible_form_behavior.rb
index f0874b1a23..286ea53b28 100644
--- a/app/forms/concerns/hyrax/flexible_form_behavior.rb
+++ b/app/forms/concerns/hyrax/flexible_form_behavior.rb
@@ -33,7 +33,6 @@ def schema
     # the resource's compound schema — the flex form definitions don't carry
     # `subproperties`. Memoized per form instance.
     def compound_field?(field)
-      return false unless Hyrax.config.respond_to?(:compound_metadata_enabled?) && Hyrax.config.compound_metadata_enabled?
       @compound_field_names ||= Hyrax::CompoundSchema.for(model).compound_names
       @compound_field_names.include?(field.to_sym)
     rescue StandardError
diff --git a/app/forms/hyrax/forms.rb b/app/forms/hyrax/forms.rb
index 3794bcc8d3..cf249437e3 100644
--- a/app/forms/hyrax/forms.rb
+++ b/app/forms/hyrax/forms.rb
@@ -17,7 +17,7 @@ def self.PcdmObjectForm(work_class) # rubocop:disable Naming/MethodName
         # Wire the compound form properties only for works whose model includes
         # the compound_metadata schema (non-flexible mode); the m3 loader
         # supplies them at init in flexible mode.
-        if Hyrax.config.compound_metadata_enabled? && !Hyrax.config.flexible? &&
+        if !Hyrax.config.flexible? &&
            work_class.ancestors.detect { |k| k.inspect == "Hyrax::Schema(compound_metadata)" }
           include Hyrax::FormFields(:compound_metadata)
         end
diff --git a/app/forms/hyrax/forms/pcdm_collection_form.rb b/app/forms/hyrax/forms/pcdm_collection_form.rb
index 6aa8b2f2f0..e8355706c4 100644
--- a/app/forms/hyrax/forms/pcdm_collection_form.rb
+++ b/app/forms/hyrax/forms/pcdm_collection_form.rb
@@ -9,7 +9,7 @@ class PcdmCollectionForm < Hyrax::Forms::ResourceForm # rubocop:disable Metrics/
       include Hyrax::FormFields(:core_metadata) if Hyrax.config.collection_include_metadata?
       # Wire the compound form properties (non-flexible mode), mirroring the
       # work-side wiring in the PcdmObjectForm factory.
-      if Hyrax.config.compound_metadata_enabled? && !Hyrax.config.flexible? &&
+      if !Hyrax.config.flexible? &&
          Hyrax::PcdmCollection.ancestors.detect { |k| k.inspect == "Hyrax::Schema(compound_metadata)" }
         include Hyrax::FormFields(:compound_metadata)
       end
diff --git a/app/forms/hyrax/forms/resource_form.rb b/app/forms/hyrax/forms/resource_form.rb
index 39fa1aa44b..2d7a65d572 100644
--- a/app/forms/hyrax/forms/resource_form.rb
+++ b/app/forms/hyrax/forms/resource_form.rb
@@ -69,10 +69,8 @@ class ResourceForm < Hyrax::ChangeSet # rubocop:disable Metrics/ClassLength
       # are Reform/Disposable forms — a bare `validates_with` does not hook into
       # Reform's `validate`, so it would never run. Record-level (no
       # `attributes:`), so it is replay-safe.
-      if Hyrax.config.compound_metadata_enabled?
-        validation(name: :default, inherit: true) do
-          validates_with Hyrax::CompoundEntryValidator
-        end
+      validation(name: :default, inherit: true) do
+        validates_with Hyrax::CompoundEntryValidator
       end
 
       ##
diff --git a/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb b/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
index 77c58a3b69..28599fabeb 100644
--- a/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
+++ b/app/indexers/hyrax/indexers/pcdm_collection_indexer.rb
@@ -13,7 +13,7 @@ class PcdmCollectionIndexer < Hyrax::Indexers::ResourceIndexer
       include Hyrax::Indexers::RedirectsIndexer if Hyrax.config.redirects_enabled?
       # Flatten compound (hierarchical) metadata sub-properties into Solr. No-op for
       # collections without compounds. See documentation/compound_fields.md.
-      include Hyrax::Indexers::CompoundIndexer if Hyrax.config.compound_metadata_enabled?
+      include Hyrax::Indexers::CompoundIndexer
       check_if_flexible(Hyrax::PcdmCollection)
 
       self.thumbnail_path_service = CollectionThumbnailPathService
diff --git a/app/indexers/hyrax/indexers/pcdm_object_indexer.rb b/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
index 907365367c..217569786f 100644
--- a/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
+++ b/app/indexers/hyrax/indexers/pcdm_object_indexer.rb
@@ -13,7 +13,7 @@ class PcdmObjectIndexer < Hyrax::Indexers::ResourceIndexer
       include Hyrax::Indexers::RedirectsIndexer if Hyrax.config.redirects_enabled?
       # Flatten compound (hierarchical) metadata sub-properties into Solr. No-op for
       # resources without compounds. See documentation/compound_fields.md.
-      include Hyrax::Indexers::CompoundIndexer if Hyrax.config.compound_metadata_enabled?
+      include Hyrax::Indexers::CompoundIndexer
 
       def to_solr # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
         super.tap do |solr_doc|
diff --git a/app/models/hyrax/pcdm_collection.rb b/app/models/hyrax/pcdm_collection.rb
index f412664514..32eeacf3f1 100644
--- a/app/models/hyrax/pcdm_collection.rb
+++ b/app/models/hyrax/pcdm_collection.rb
@@ -48,10 +48,8 @@ class PcdmCollection < Hyrax::Resource
     # Sample compound metadata, mirroring Hyrax::Work. In flexible mode the
     # compounds come from the m3 profile, so only the read-path normalization is
     # included here. See documentation/compound_fields.md.
-    if Hyrax.config.compound_metadata_enabled?
-      include Hyrax::Schema(:compound_metadata) unless Hyrax.config.flexible?
-      include Hyrax::CompoundNormalization
-    end
+    include Hyrax::Schema(:compound_metadata) unless Hyrax.config.flexible?
+    include Hyrax::CompoundNormalization
 
     attribute :collection_type_gid, Valkyrie::Types::String
     attribute :member_ids, Valkyrie::Types::Array.of(Valkyrie::Types::ID).meta(ordered: true)
diff --git a/app/models/hyrax/work.rb b/app/models/hyrax/work.rb
index 1c6c9a6ba7..df7652e276 100644
--- a/app/models/hyrax/work.rb
+++ b/app/models/hyrax/work.rb
@@ -102,10 +102,8 @@ class Work < Hyrax::Resource
     # Sample compound metadata. In flexible mode the compounds come from the m3
     # profile, so only the read-path normalization is included here. See
     # documentation/compound_fields.md.
-    if Hyrax.config.compound_metadata_enabled?
-      include Hyrax::Schema(:compound_metadata) unless Hyrax.config.flexible?
-      include Hyrax::CompoundNormalization
-    end
+    include Hyrax::Schema(:compound_metadata) unless Hyrax.config.flexible?
+    include Hyrax::CompoundNormalization
 
     attribute :admin_set_id,             Valkyrie::Types::ID
     attribute :member_ids,               Valkyrie::Types::Array.of(Valkyrie::Types::ID).meta(ordered: true)
diff --git a/app/presenters/hyrax/collection_presenter.rb b/app/presenters/hyrax/collection_presenter.rb
index dca38309ca..8fbd7473a6 100644
--- a/app/presenters/hyrax/collection_presenter.rb
+++ b/app/presenters/hyrax/collection_presenter.rb
@@ -71,7 +71,6 @@ def terms_with_values
     # separately via `render_compound_cards`). Resolved from the backing
     # document. See documentation/compound_fields.md.
     def compound_terms
-      return [] unless Hyrax.config.compound_metadata_enabled?
       compound_schema.inline_compound_names
     rescue StandardError
       []
@@ -84,7 +83,6 @@ def compound_term?(term)
     # All compound names (inline + card) declared for this collection, used to
     # delegate the readers to the solr document below.
     def all_compound_names
-      return [] unless Hyrax.config.compound_metadata_enabled?
       compound_schema.compound_names
     rescue StandardError
       []
diff --git a/app/validators/hyrax/compound_entry_validator.rb b/app/validators/hyrax/compound_entry_validator.rb
index 952ccd40f1..c68b350831 100644
--- a/app/validators/hyrax/compound_entry_validator.rb
+++ b/app/validators/hyrax/compound_entry_validator.rb
@@ -12,8 +12,6 @@ module Hyrax
   # documentation/compound_fields.md.
   class CompoundEntryValidator < ActiveModel::Validator
     def validate(record)
-      return unless Hyrax.config.compound_metadata_enabled?
-
       schema = Hyrax::CompoundSchema.for(schema_source(record))
       schema.definitions.each do |name, definition|
         next unless record.respond_to?(name)
diff --git a/config/metadata/compound_metadata.yaml b/config/metadata/compound_metadata.yaml
index 3db05d949f..0d8f4c265d 100644
--- a/config/metadata/compound_metadata.yaml
+++ b/config/metadata/compound_metadata.yaml
@@ -15,7 +15,7 @@
 # sub-property input types (open-entry `string` and `controlled` vocabulary).
 # Applications can add their own compounds the same way (in this file, an
 # app-level schema, or the m3 profile under HYRAX_FLEXIBLE=true) and may remove
-# these samples by setting `Hyrax.config.compound_metadata_enabled = false`.
+# or override these samples in their own schema.
 attributes:
   # Participants associated with the work: a person or organization with a
   # display title, a name, and a controlled role.
diff --git a/documentation/compound_fields.md b/documentation/compound_fields.md
index b58abbbff3..6cdce4ca24 100644
--- a/documentation/compound_fields.md
+++ b/documentation/compound_fields.md
@@ -303,11 +303,8 @@ They are declared in `config/metadata/compound_metadata.yaml` (non-flexible
 mode) and in the default m3 profile (`config/metadata_profiles/m3_profile.yaml`,
 flexible mode, `available_on` both `Hyrax::Work` and the collection class).
 The engine base `Hyrax::Work` and `Hyrax::PcdmCollection` include them, and the
-base work and collection indexers flatten them, when
-`Hyrax.config.compound_metadata_enabled?` is true (the default; set
-`compound_metadata_enabled = false`, or `HYRAX_COMPOUND_METADATA_ENABLED=false`,
-to omit them). Applications can add their own compounds the same way and remove
-or override the samples.
+base work and collection indexers flatten them. Applications can add their own
+compounds the same way and remove or override the samples in their own schema.
 
 ## Show-page rendering
 
@@ -416,10 +413,10 @@ relationship_note:
 ```
 
 Required sub-properties and required compounds render a `*` marker on the form
-label. On save, `Hyrax::CompoundEntryValidator` (wired on the resource form,
-gated by `compound_metadata_enabled?`) adds one error per compound, keyed on the
-compound's attribute name, so the failure is reported against that field. The
-rules are the same in both flex modes.
+label. On save, `Hyrax::CompoundEntryValidator` (wired on the resource form)
+adds one error per compound, keyed on the compound's attribute name, so the
+failure is reported against that field. The rules are the same in both flex
+modes.
 
 The decision logic lives in `Hyrax::CompoundEntryValidation`, a plain object
 decoupled from ActiveModel and Reform — given a compound's definition and its
diff --git a/lib/hyrax/configuration.rb b/lib/hyrax/configuration.rb
index adf59c4c7a..510edafd47 100644
--- a/lib/hyrax/configuration.rb
+++ b/lib/hyrax/configuration.rb
@@ -350,17 +350,6 @@ def redirects_enabled?
     end
     alias redirects_enabled redirects_enabled?
 
-    # Whether the sample compound metadata schema ships on works and collections
-    # by default. Defaults to true; respects +HYRAX_COMPOUND_METADATA_ENABLED+.
-    #
-    # @see documentation/compound_fields.md
-    attr_writer :compound_metadata_enabled
-    def compound_metadata_enabled?
-      return @compound_metadata_enabled if defined?(@compound_metadata_enabled) && !@compound_metadata_enabled.nil?
-      @compound_metadata_enabled = ActiveModel::Type::Boolean.new.cast(ENV.fetch('HYRAX_COMPOUND_METADATA_ENABLED', true))
-    end
-    alias compound_metadata_enabled compound_metadata_enabled?
-
     # @return [Boolean] true when both feature gates are open. Single
     #   source of truth for "is the redirects feature actively in use
     #   right now?". Short-circuits on the config so the Flipflop call
diff --git a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
index 5eea5d390d..c32579c355 100644
--- a/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
+++ b/spec/forms/hyrax/forms/compound_metadata_form_spec.rb
@@ -25,7 +25,6 @@
 # compound_field_behavior_spec and the live allinson UI.
 RSpec.describe 'Compound metadata form flow', type: :model, unless: Hyrax.config.flexible? do
   before do
-    allow(Hyrax.config).to receive(:compound_metadata_enabled?).and_return(true)
     allow(Hyrax.config).to receive(:flexible?).and_return(false)
     # A work-like resource that includes the shipped compound schema, the way
     # Hyrax::Work does. Named so the form factory's `*Form` lookup falls back
diff --git a/spec/forms/hyrax/forms/pcdm_collection_form_spec.rb b/spec/forms/hyrax/forms/pcdm_collection_form_spec.rb
index e9cff6cbcd..54a331d996 100644
--- a/spec/forms/hyrax/forms/pcdm_collection_form_spec.rb
+++ b/spec/forms/hyrax/forms/pcdm_collection_form_spec.rb
@@ -33,7 +33,7 @@
   # second, broken scalar input (a `required` compound would block form submit
   # client-side). PcdmCollectionForm overrides these terms, so it needs the same
   # exclusion ResourceForm has.
-  describe 'compound terms are excluded from scalar term lists', if: Hyrax.config.compound_metadata_enabled? do
+  describe 'compound terms are excluded from scalar term lists' do
     it 'keeps compounds out of primary_terms and secondary_terms' do
       compounds = form.compound_terms
       skip 'no compounds declared on the collection in this configuration' if compounds.empty?
diff --git a/spec/presenters/hyrax/collection_presenter_spec.rb b/spec/presenters/hyrax/collection_presenter_spec.rb
index 773d68c36d..9df9bfed63 100644
--- a/spec/presenters/hyrax/collection_presenter_spec.rb
+++ b/spec/presenters/hyrax/collection_presenter_spec.rb
@@ -39,14 +39,6 @@
       allow(presenter).to receive(:compound_terms).and_return([:participants, :identifiers])
       expect(presenter.terms).to end_with(:participants, :identifiers)
     end
-
-    context 'with compound metadata disabled' do
-      before { allow(Hyrax.config).to receive(:compound_metadata_enabled?).and_return(false) }
-
-      it 'is the default terms only' do
-        expect(presenter.terms).to eq described_class::DEFAULT_TERMS
-      end
-    end
   end
 
   describe "compound attribute delegation" do
diff --git a/spec/validators/hyrax/compound_entry_validator_spec.rb b/spec/validators/hyrax/compound_entry_validator_spec.rb
index 2d024a3edd..6868b74d82 100644
--- a/spec/validators/hyrax/compound_entry_validator_spec.rb
+++ b/spec/validators/hyrax/compound_entry_validator_spec.rb
@@ -21,23 +21,12 @@
   let(:schema) { instance_double(Hyrax::CompoundSchema, definitions: { relationships: definition }) }
 
   before do
-    allow(Hyrax.config).to receive(:compound_metadata_enabled?).and_return(true)
     allow(Hyrax::CompoundSchema).to receive(:for).and_return(schema)
   end
 
   # Compound errors are attached to :base (so the work and collection forms,
   # which render errors differently, both show them cleanly), and the message
   # names the compound.
-  context 'when the feature is disabled' do
-    let(:entries) { [{ 'related_item' => 'x' }] } # would otherwise be invalid
-    before { allow(Hyrax.config).to receive(:compound_metadata_enabled?).and_return(false) }
-
-    it 'does not validate' do
-      record.valid?
-      expect(record.errors[:base]).to be_empty
-    end
-  end
-
   context 'with no rows (optional compound)' do
     it 'is valid' do
       record.valid?

From fafb610bfe23ea5c90d74e7c73fce6415ff2c0e4 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Sat, 6 Jun 2026 14:54:39 -0400
Subject: [PATCH 30/32] Clean up a few comments

Documentation was moved and a few places were missed.
---
 .koppie/config/metadata_profiles/m3_profile.yaml     | 2 +-
 app/assets/stylesheets/hyrax/_compound_metadata.scss | 2 +-
 config/metadata/compound_metadata.yaml               | 2 +-
 config/metadata_profiles/m3_profile.yaml             | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.koppie/config/metadata_profiles/m3_profile.yaml b/.koppie/config/metadata_profiles/m3_profile.yaml
index 4159201425..c8f77ec9fb 100644
--- a/.koppie/config/metadata_profiles/m3_profile.yaml
+++ b/.koppie/config/metadata_profiles/m3_profile.yaml
@@ -933,7 +933,7 @@ properties:
   # parent; its members are declared as separate properties pointing back with
   # `subproperty_of: <parent>`, each carrying its own `available_on`, indexing,
   # and form placement. `subproperty_of` entries are not standalone resource
-  # attributes. See documentation/forms/compound_fields.md.
+  # attributes. See documentation/compound_fields.md.
   participants:
     available_on:
       class:
diff --git a/app/assets/stylesheets/hyrax/_compound_metadata.scss b/app/assets/stylesheets/hyrax/_compound_metadata.scss
index 17e8c6fcee..ad1c9cdd06 100644
--- a/app/assets/stylesheets/hyrax/_compound_metadata.scss
+++ b/app/assets/stylesheets/hyrax/_compound_metadata.scss
@@ -1,5 +1,5 @@
 // Compound metadata display on work and collection show pages.
-// See documentation/forms/compound_fields.md.
+// See documentation/compound_fields.md.
 //
 // `!important` throughout: the collection metadata area styles nested divs with
 // a descendant selector (`.hyc-metadata div { display: flex; border-bottom }`
diff --git a/config/metadata/compound_metadata.yaml b/config/metadata/compound_metadata.yaml
index 0d8f4c265d..6725d95b44 100644
--- a/config/metadata/compound_metadata.yaml
+++ b/config/metadata/compound_metadata.yaml
@@ -9,7 +9,7 @@
 # `subproperty_of` entries are NOT registered as standalone resource attributes
 # — their data lives only as keys inside the parent compound's row hashes. Every
 # key under `attributes:` must be globally unique. See
-# `documentation/forms/compound_fields.md`.
+# `documentation/compound_fields.md`.
 #
 # These are intentionally generic examples demonstrating the supported
 # sub-property input types (open-entry `string` and `controlled` vocabulary).
diff --git a/config/metadata_profiles/m3_profile.yaml b/config/metadata_profiles/m3_profile.yaml
index ae11e31d63..d9f3494e53 100644
--- a/config/metadata_profiles/m3_profile.yaml
+++ b/config/metadata_profiles/m3_profile.yaml
@@ -957,7 +957,7 @@ properties:
   # separate properties pointing back with `subproperty_of: <parent>`, each
   # carrying its own `available_on`, indexing, and form placement. Sibling order
   # follows document order. `subproperty_of` entries are not standalone resource
-  # attributes. See documentation/forms/compound_fields.md.
+  # attributes. See documentation/compound_fields.md.
   participants:
     available_on:
       class:

From 20b843b3fcfba07c6c57a4f4713375b3d4466566 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Mon, 8 Jun 2026 12:42:41 -0400
Subject: [PATCH 31/32] Re-render Valkyrie work form on failed validation

A work create that fails validation re-renders the form with its
errors instead of raising, because rebuild_form no longer wraps a
Hyrax::ChangeSet in the legacy FailedSubmissionFormWrapper.

The wrapper exists for ActiveFedora forms and reads permitted_params,
which a Valkyrie ChangeSet does not define, so wrapping one raised
ArgumentError and turned every validation error into a 500. The
ChangeSet already holds its submitted, validated state, mirroring the
guard already present in after_update_error.
---
 .../concerns/hyrax/works_controller_behavior.rb  | 11 ++++++++++-
 .../hyrax/works_controller_behavior_spec.rb      | 16 ++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/app/controllers/concerns/hyrax/works_controller_behavior.rb b/app/controllers/concerns/hyrax/works_controller_behavior.rb
index c3fbe24728..1845904f62 100644
--- a/app/controllers/concerns/hyrax/works_controller_behavior.rb
+++ b/app/controllers/concerns/hyrax/works_controller_behavior.rb
@@ -431,8 +431,17 @@ def after_create_error(errors, original_input_params_for_form = nil)
     end
 
     # Creating a form object that can re-render most of the submitted parameters.
-    # Required for ActiveFedora::Base objects only.
+    #
+    # The +FailedSubmissionFormWrapper+ re-exposes submitted params for the +new+
+    # view to re-render, and is required for +ActiveFedora::Base+ objects only. A
+    # Valkyrie +ChangeSet+ form already holds the submitted, validated state — it
+    # was populated by +form.validate(params)+ before the error — so +@form+
+    # re-renders directly with the user's input and errors. The wrapper has no
+    # +permitted_params+ source for a ChangeSet, so wrapping it would raise.
+    # Mirrors the same +Hyrax::ChangeSet+ guard in {#after_update_error}.
     def rebuild_form(original_input_params_for_form)
+      return if @form.is_a?(Hyrax::ChangeSet)
+
       build_form
       @form = Hyrax::Forms::FailedSubmissionFormWrapper
               .new(form: @form,
diff --git a/spec/controllers/concerns/hyrax/works_controller_behavior_spec.rb b/spec/controllers/concerns/hyrax/works_controller_behavior_spec.rb
index be1e88a5fe..5985b19256 100644
--- a/spec/controllers/concerns/hyrax/works_controller_behavior_spec.rb
+++ b/spec/controllers/concerns/hyrax/works_controller_behavior_spec.rb
@@ -104,6 +104,22 @@
         expect(Sipity::Entity(assigns[:curation_concern]).workflow_state).to have_attributes(name: "deposited")
       end
 
+      context 'when the submission fails validation' do
+        # A Valkyrie ChangeSet form re-renders directly on a failed create; it
+        # has no `permitted_params`, so the legacy FailedSubmissionFormWrapper
+        # must not wrap it (doing so raised ArgumentError). See #rebuild_form.
+        before do
+          allow_any_instance_of(Hyrax::ChangeSet).to receive(:validate).and_return(false)
+        end
+
+        it 'rebuilds the form and renders new with an unprocessable status' do
+          post :create, params: { test_simple_work: { title: 'comet in moominland' } }
+
+          expect(response).to have_http_status(:unprocessable_entity)
+          expect(assigns[:form]).to be_a(Hyrax::ChangeSet)
+        end
+      end
+
       context 'when depositing as a proxy for (on_behalf_of) another user' do
         let(:create_params) { { title: 'comet in moominland', on_behalf_of: target_user.user_key } }
         let(:target_user) { FactoryBot.create(:user) }

From 197e231878daed7749467445df78c801b3426826 Mon Sep 17 00:00:00 2001
From: LaRita Robinson <larita@notch8.com>
Date: Tue, 9 Jun 2026 17:38:57 -0400
Subject: [PATCH 32/32] Apply flexible profile changes to compound forms

A compound's form placement (e.g. `form: { primary: true }`) now takes
effect for new and edit forms as soon as a new metadata profile is
loaded, with no process restart, matching how other properties already
behave.
---
 app/services/hyrax/compound_schema.rb       | 17 ++++++++++-----
 spec/services/hyrax/compound_schema_spec.rb | 23 +++++++++++++++++++++
 2 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/app/services/hyrax/compound_schema.rb b/app/services/hyrax/compound_schema.rb
index aede55fc9d..ed054480b4 100644
--- a/app/services/hyrax/compound_schema.rb
+++ b/app/services/hyrax/compound_schema.rb
@@ -64,17 +64,24 @@ def self.flexible_attributes_for(klass, version)
     end
     private_class_method :flexible_attributes_for
 
-    # For a class, its own schema. For an instance, both the class schema
-    # (non-flexible) and the singleton schema (flexible: the m3 attributes are
-    # applied to the singleton at load time). Unioning both makes {.for} work in
-    # both flex modes.
+    # For a class, its own schema. For an instance, both the singleton schema
+    # (flexible mode) and the class schema (non-flexible mode), so {.for} works
+    # in both.
+    #
+    # Order is load-bearing: the singleton schema must come first so it wins
+    # {#build_definitions}' first-source-per-name dedup. The class schema is
+    # frozen at class-load and not refreshed when the active FlexibleSchema
+    # version changes, so a flexible instance's singleton schema (rebuilt at the
+    # current version) is the authoritative source for a freshly-uploaded
+    # profile. In non-flexible mode the singleton has no extra schema, so order
+    # is moot.
     def self.schema_sources_for(resource)
       if resource.is_a?(Class)
         [(resource.schema if resource.respond_to?(:schema))]
       else
         sources = []
-        sources << resource.class.schema if resource.class.respond_to?(:schema)
         sources << resource.singleton_class.schema if resource.respond_to?(:singleton_class) && resource.singleton_class.respond_to?(:schema)
+        sources << resource.class.schema if resource.class.respond_to?(:schema)
         sources
       end.compact
     end
diff --git a/spec/services/hyrax/compound_schema_spec.rb b/spec/services/hyrax/compound_schema_spec.rb
index 88d42e07ef..f7a596135d 100644
--- a/spec/services/hyrax/compound_schema_spec.rb
+++ b/spec/services/hyrax/compound_schema_spec.rb
@@ -244,6 +244,29 @@ def self.name
     end
   end
 
+  describe 'instance schema source ordering (singleton before class)' do
+    # build_definitions is first-source-wins per name, so a flexible instance's
+    # singleton schema (current version) must precede its class schema (frozen
+    # at class-load) for a freshly-uploaded profile to win. See
+    # #schema_sources_for.
+    it 'lists the singleton schema before the class schema for an instance' do
+      class_schema = double('class_schema')
+      singleton_schema = double('singleton_schema')
+      resource = double('resource',
+                        class: double('klass', schema: class_schema),
+                        singleton_class: double('singleton', schema: singleton_schema))
+
+      sources = described_class.send(:schema_sources_for, resource)
+      expect(sources).to eq([singleton_schema, class_schema])
+    end
+
+    it 'uses the class schema alone for a class argument (non-flexible)' do
+      schema_obj = double('schema')
+      klass = Class.new { define_singleton_method(:schema) { schema_obj } }
+      expect(described_class.send(:schema_sources_for, klass)).to eq([schema_obj])
+    end
+  end
+
   describe '.for_solr_document' do
     # The attribute map a flexible schema loader returns for a version:
     # `{ name => dry_type_with_meta }` (with subproperties folded into the