shopify_product_taxonomy 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 436ce3b89bb5636833505ce02d1bf30e96346158b2591630eccb840c0184dd32
-  data.tar.gz: 39d468ca12f1d50151eb5918aac1a1fda8122b9504d22db18e7331bc89873dd5
+  metadata.gz: da6547214a08a1014e88188ab157220a6f5cd23d60d0bb31074ff3e5418c5a7d
+  data.tar.gz: 3a06da2e5a5500d7a000b46e68307921291072120a52fd828b644b9188ca6760
 SHA512:
-  metadata.gz: 83aa402e17c4aaa1ce91980ea2bfac9652fa36ea7b9667ae910ca90030c187e2db3383cfbb70cf8ad6fa23d81ae14d4887639bbf4b8e67f4bec94ccf1ca94ef0
-  data.tar.gz: 8edb5a665aaea1c8ea7acf24b379fa7e3e346b5977313a4f03ab5fa0d74842e11bc3f167865b452ec80dea1692c64cc55fccf7f8266828f56c87cdd7da615891
+  metadata.gz: 97d4b42d26d93a1566f3e216f6be82357fcae6f30b771640a137182035d74f0bf545c3f1c3db69572f6b639d5d1d501b11217475bc9a15dd813da3b837c35c41
+  data.tar.gz: 188d03a6b94f9082fc80c3eee0d4f4400ad6dffed29a53542324ab6c7503d56c5aaf2a5b6213d34731c38b9ff96966a5ef3a0ff7bd4a3d7dc7c0beadbbb75ccf

data/lib/product_taxonomy/alphanumeric_sorter.rb

@@ -37,13 +37,13 @@ module ProductTaxonomy
 
       def normalize_sequential(match)
         [
-          normalize_text(match[:primary_text]),
+          normalize_text(match[:primary_text]) || "",
           normalize_single_number(match[:primary_step]),
           normalize_text(match[:primary_unit] || match[:secondary_unit]) || "",
           normalize_text(match[:seperator]) || "-",
-          normalize_text(match[:secondary_text]),
+          normalize_text(match[:secondary_text]) || "",
           normalize_single_number(match[:secondary_step]),
-          normalize_text(match[:trailing_text]),
+          normalize_text(match[:trailing_text]) || "",
         ]
       end
 

data/lib/product_taxonomy/command_executor.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module ProductTaxonomy
+  class CommandExecutor
+    DEFAULT_RUNNER = Open3.method(:capture3)
+
+    def initialize(command_runner: DEFAULT_RUNNER)
+      @command_runner = command_runner
+    end
+
+    def run!(*command, chdir:, failure_message:)
+      stdout, stderr, status = capture(*command, chdir:, failure_message:)
+      return stdout if status.success?
+
+      details = stderr.strip
+      details = stdout.strip if details.empty?
+      message = details.empty? ? failure_message : "#{failure_message} #{details}"
+      raise message
+    end
+
+    def capture(*command, chdir:, failure_message:)
+      @command_runner.call(*command, chdir:)
+    rescue SystemCallError => error
+      raise "#{failure_message} #{error.message}"
+    end
+  end
+end

data/lib/product_taxonomy/dist_asset_stager.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "zlib"
+
+module ProductTaxonomy
+  class DistAssetStager
+    ALLOWED_ROOT_FILES = ["README.md"].freeze
+    DATA_EXTENSIONS = [".json", ".txt"].freeze
+    LOCALE_PATTERN = /\A[a-z]{2,3}(?:-[A-Z]{2})?\z/
+
+    def initialize(input_path:, output_path:)
+      @input_path = File.expand_path(input_path)
+      @output_path = File.expand_path(output_path)
+    end
+
+    def stage
+      validate_paths!
+      staging_plan = build_staging_plan
+      validate_collisions!(staging_plan)
+
+      FileUtils.rm_rf(@output_path)
+      FileUtils.mkdir_p(@output_path)
+
+      staging_plan.map do |source_path, asset_name|
+        destination_path = File.join(@output_path, asset_name)
+        gzip_file(source_path, destination_path)
+        destination_path
+      end
+    end
+
+    private
+
+    def validate_paths!
+      raise ArgumentError, "Input path does not exist: #{@input_path}" unless File.directory?(@input_path)
+
+      paths_overlap = @output_path == @input_path ||
+        @output_path.start_with?("#{@input_path}#{File::SEPARATOR}") ||
+        @input_path.start_with?("#{@output_path}#{File::SEPARATOR}")
+      raise ArgumentError, "Input and output paths must not overlap" if paths_overlap
+
+      root_entries = Dir.children(@input_path).sort
+      unexpected_files = root_entries.reject do |entry|
+        path = File.join(@input_path, entry)
+        File.directory?(path) || (ALLOWED_ROOT_FILES.include?(entry) && File.file?(path))
+      end
+      unless unexpected_files.empty?
+        raise ArgumentError, "Unexpected files at distribution root: #{unexpected_files.join(", ")}"
+      end
+
+      unexpected_directories = root_entries.select do |entry|
+        File.directory?(File.join(@input_path, entry)) && !entry.match?(LOCALE_PATTERN)
+      end
+      return if unexpected_directories.empty?
+
+      raise ArgumentError, "Unexpected directories at distribution root: #{unexpected_directories.join(", ")}"
+    end
+
+    def build_staging_plan
+      locale_directories.flat_map do |locale_directory|
+        locale = File.basename(locale_directory)
+        data_files(locale_directory).map do |source_path|
+          [source_path, asset_name(source_path, locale_directory, locale)]
+        end
+      end.sort_by(&:last)
+    end
+
+    def locale_directories
+      Dir.children(@input_path).sort.filter_map do |entry|
+        path = File.join(@input_path, entry)
+        path if File.directory?(path)
+      end
+    end
+
+    def data_files(locale_directory)
+      files = Dir.glob(File.join(locale_directory, "**", "*"), File::FNM_DOTMATCH).select { File.file?(_1) }.sort
+      unexpected_files = files.reject { DATA_EXTENSIONS.include?(File.extname(_1)) }
+      unless unexpected_files.empty?
+        relative_paths = unexpected_files.map { _1.delete_prefix("#{@input_path}#{File::SEPARATOR}") }
+        raise ArgumentError, "Unexpected files in locale directories: #{relative_paths.join(", ")}"
+      end
+
+      files
+    end
+
+    def asset_name(source_path, locale_directory, locale)
+      relative_path = source_path.delete_prefix("#{locale_directory}#{File::SEPARATOR}")
+      extension = File.extname(relative_path)
+      basename = File.basename(relative_path, extension)
+      relative_directory = File.dirname(relative_path)
+      directory_parts = relative_directory == "." ? [] : relative_directory.split(File::SEPARATOR)
+
+      [*directory_parts, basename, locale].join(".") + extension + ".gz"
+    end
+
+    def gzip_file(source_path, destination_path)
+      Zlib::GzipWriter.open(destination_path) do |gzip_writer|
+        gzip_writer.mtime = 0
+        File.open(source_path, "rb") { IO.copy_stream(_1, gzip_writer) }
+      end
+    end
+
+    def validate_collisions!(staging_plan)
+      collisions = staging_plan.group_by(&:last).select { |_, sources| sources.length > 1 }
+      return if collisions.empty?
+
+      details = collisions.sort.map do |asset_name, sources|
+        source_paths = sources.map(&:first).join(", ")
+        "#{asset_name} (#{source_paths})"
+      end
+      raise ArgumentError, "Distribution asset naming collision: #{details.join("; ")}"
+    end
+  end
+end

data/lib/product_taxonomy/loader.rb

@@ -13,12 +13,14 @@ module ProductTaxonomy
         values_path = File.join(data_path, "values.yml")
         attributes_path = File.join(data_path, "attributes.yml")
         return_reasons_path = File.join(data_path, "return_reasons.yml")
+        disclosures_path = File.join(data_path, "disclosures.yml")
         categories_glob = Dir.glob(File.join(data_path, "categories", "*.yml"))
 
         begin
           ProductTaxonomy::Value.load_from_source(YAML.load_file(values_path))
           ProductTaxonomy::Attribute.load_from_source(YAML.load_file(attributes_path))
           ProductTaxonomy::ReturnReason.load_from_source(YAML.load_file(return_reasons_path))
+          ProductTaxonomy::Disclosure.load_from_source(YAML.load_file(disclosures_path))
 
           categories_source_data = categories_glob.each_with_object([]) do |file, array|
             array.concat(YAML.safe_load_file(file))
@@ -32,6 +34,7 @@ module ProductTaxonomy
 
         # Run validations that can only be run after the taxonomy has been loaded.
         ProductTaxonomy::Value.all.each { |model| model.validate!(:taxonomy_loaded) }
+        ProductTaxonomy::Disclosure.all.each { |model| model.validate!(:taxonomy_loaded) }
       end
     end
   end

data/lib/product_taxonomy/localizations_validator.rb

@@ -11,6 +11,7 @@ module ProductTaxonomy
         Category.validate_localizations!(locales)
         Attribute.validate_localizations!(locales)
         Value.validate_localizations!(locales)
+        ReturnReason.validate_localizations!(locales)
 
         validate_locales_are_consistent! if locales.nil?
       end
@@ -21,10 +22,12 @@ module ProductTaxonomy
         categories_locales = Category.localizations.keys
         attributes_locales = Attribute.localizations.keys
         values_locales = Value.localizations.keys
+        return_reasons_locales = ReturnReason.localizations.keys
 
         error_message = "Not all model localizations have the same set of locales"
-        raise ArgumentError,
-          error_message unless categories_locales == attributes_locales && attributes_locales == values_locales
+        all_locales_match = [attributes_locales, values_locales, return_reasons_locales]
+          .all? { |locales| locales == categories_locales }
+        raise ArgumentError, error_message unless all_locales_match
       end
     end
   end

data/lib/product_taxonomy/models/category.rb

@@ -22,7 +22,7 @@ module ProductTaxonomy
             id: item["id"],
             name: item["name"],
             attributes: Array(item["attributes"]).map { Attribute.find_by(friendly_id: _1) || _1 },
-            return_reasons: Array(item["return_reasons"]).map { ReturnReason.find_by(friendly_id: _1) || _1 },
+            return_reasons: parse_return_reasons(item["return_reasons"]),
           )
         end
 
@@ -42,6 +42,10 @@ module ProductTaxonomy
           root_nodes << node if node.root?
         end
         @verticals.sort_by!(&:name)
+
+        # Fourth pass: derive each category's effective return reasons — inherited from the closest defining ancestor,
+        # falling back to the global reasons when nothing is defined.
+        Category.all.each(&:resolve_return_reasons)
       end
 
       # Reset all class-level state
@@ -60,6 +64,13 @@ module ProductTaxonomy
 
       private
 
+      # `return_reasons: inherit` in the data marks a category as inheriting; anything else is an explicit list.
+      def parse_return_reasons(value)
+        return :inherit if value == "inherit"
+
+        Array(value).map { |friendly_id| ReturnReason.find_by(friendly_id:) || friendly_id }
+      end
+
       def add_children(type:, item:, parent:)
         item[type]&.each do |child_id|
           child = Category.find_by(id: child_id) || child_id
@@ -84,16 +95,24 @@ module ProductTaxonomy
     validate :id_starts_with_parent_id, unless: :root?, on: :category_tree_loaded
     validate :children_found?, on: :category_tree_loaded
     validate :secondary_children_found?, on: :category_tree_loaded
+    validate :root_does_not_inherit_return_reasons, if: :root?, on: :category_tree_loaded
 
     localized_attr_reader :name, keyed_by: :id
 
-    attr_reader :id, :children, :secondary_children, :attributes, :return_reasons
+    attr_reader :id,
+      :children,
+      :secondary_children,
+      :attributes,
+      :return_reasons,
+      :defined_return_reasons,
+      :inherits_return_reasons
     attr_accessor :parent, :secondary_parents
 
     # @param id [String] The ID of the category.
     # @param name [String] The name of the category.
     # @param attributes [Array<Attribute>] The attributes of the category.
-    # @param return_reasons [Array<ReturnReason>] The return reasons for the category.
+    # @param return_reasons [Array<ReturnReason>, :inherit] The return reasons for the category, or `:inherit` to copy
+    #   them from the closest ancestor that defines its own.
     # @param parent [Category] The parent category of the category.
     def initialize(id:, name:, attributes: [], return_reasons: [], parent: nil)
       @id = id
@@ -101,7 +120,9 @@ module ProductTaxonomy
       @children = []
       @secondary_children = []
       @attributes = attributes
-      @return_reasons = return_reasons
+      @inherits_return_reasons = return_reasons == :inherit
+      @defined_return_reasons = @inherits_return_reasons ? [] : return_reasons.dup
+      @return_reasons = @defined_return_reasons.dup
       @parent = parent
       @secondary_parents = []
     end
@@ -139,11 +160,29 @@ module ProductTaxonomy
       @attributes << attribute
     end
 
-    # Add a return reason to the category
+    # Add a return reason to the category. Explicitly adding a reason means the category defines its own reasons
+    # rather than inheriting them, so the first add on an inheriting category drops the inherited reasons.
     #
     # @param [ReturnReason] return_reason
     def add_return_reason(return_reason)
-      @return_reasons << return_reason
+      if @inherits_return_reasons
+        @inherits_return_reasons = false
+        @defined_return_reasons = []
+      end
+      @defined_return_reasons << return_reason
+      resolve_return_reasons
+    end
+
+    # Copy return reasons from the closest ancestor that defines its own, when this category inherits. No-op for
+    # categories that define their own reasons or have no defining ancestor.
+    def resolve_return_reasons
+      @return_reasons = if inherits_return_reasons
+        ancestors.find { |ancestor| !ancestor.inherits_return_reasons }&.defined_return_reasons&.dup || []
+      else
+        defined_return_reasons.dup
+      end
+
+      @return_reasons = ReturnReason.global.dup if @return_reasons.empty?
     end
 
     #
@@ -310,6 +349,13 @@ module ProductTaxonomy
       end
     end
 
+    def root_does_not_inherit_return_reasons
+      return unless inherits_return_reasons
+
+      # A root category has no ancestor to inherit from, so `inherit` cannot be resolved.
+      errors.add(:return_reasons, :root_cannot_inherit, message: "cannot be inherited by a root category")
+    end
+
     def children_found?
       children&.each do |child|
         next if child.is_a?(Category)

data/lib/product_taxonomy/models/disclosure.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module ProductTaxonomy
+  # A legally-required product disclosure (e.g. a safety warning or chemical
+  # exposure notice). Disclosures form a shallow hierarchy: grouping/root nodes
+  # (no `parent_public_id`) organize the axis, and leaf nodes carry the
+  # jurisdiction information, plus the optional copy that merchants surface.
+  class Disclosure
+    include ActiveModel::Validations
+    include FormattedValidationErrors
+    extend Localized
+    extend Indexed
+
+    # Surfaces on which a disclosure may be displayed.
+    SURFACES = ["product_page", "cart", "checkout"].freeze
+
+    # `public_id` must be a lowercase slug: alphanumeric segments joined by `-` or `_`.
+    PUBLIC_ID_FORMAT = /\A[a-z0-9]+(?:[_-][a-z0-9]+)*\z/
+
+    # String-typed fields validated for type on load.
+    STRING_FIELDS = [
+      :name,
+      :internal_label,
+      :description,
+      :legal_citation,
+      :symbol,
+      :display_requirements,
+      :title,
+      :content,
+      :source,
+    ].freeze
+
+    # Fields required on every leaf disclosure, in addition to jurisdictions.
+    LEAF_REQUIRED_FIELDS = [:legal_citation, :source].freeze
+
+    # Fields required on a leaf disclosure that names a display surface.
+    DISPLAY_REQUIRED_FIELDS = [:title, :content].freeze
+
+    class << self
+      # Load disclosures from source data. By default this is deserialized from
+      # `data/disclosures.yml`.
+      #
+      # @param source_data [Array<Hash>] The source data to load disclosures from.
+      # @return [void]
+      def load_from_source(source_data)
+        raise ArgumentError, "source_data must be an array" unless source_data.is_a?(Array)
+
+        source_data.each do |disclosure_data|
+          raise ArgumentError, "source_data must contain hashes" unless disclosure_data.is_a?(Hash)
+
+          disclosure = disclosure_from(disclosure_data)
+          Disclosure.add(disclosure)
+          disclosure.validate!(:create)
+        end
+      end
+
+      # Reset all class-level state.
+      def reset
+        @localizations = nil
+        @hashed_models = nil
+      end
+
+      # Get the next ID for a newly created disclosure.
+      #
+      # @return [Integer] The next ID.
+      def next_id = (all.max_by(&:id)&.id || 0) + 1
+
+      private
+
+      def disclosure_from(data)
+        Disclosure.new(
+          id: data["id"],
+          public_id: data["public_id"],
+          parent_public_id: data["parent_public_id"],
+          name: data["name"],
+          internal_label: data["internal_label"],
+          description: data["description"],
+          jurisdictions: data["jurisdictions"],
+          legal_citation: data["legal_citation"],
+          symbol: data["symbol"],
+          display_requirements: data["display_requirements"],
+          display_preferences: data["display_preferences"],
+          title: data["title"],
+          content: data["content"],
+          source: data["source"],
+          disclosure_attributes: data["disclosure_attributes"],
+          disclosure_attribute_values: data["disclosure_attribute_values"],
+        )
+      end
+    end
+
+    validates :id, presence: true, numericality: { only_integer: true }, on: :create
+    validates :public_id, presence: true, format: { with: PUBLIC_ID_FORMAT, allow_blank: true }, on: :create
+    validates :name, presence: true, on: :create
+    validates :internal_label, presence: true, on: :create
+    validates_with ProductTaxonomy::Indexed::UniquenessValidator, attributes: [:public_id, :id], on: :create
+    validate :field_types_are_valid, on: :create
+    validate :not_self_parenting, on: :create
+
+    # Validations that can only run once the whole axis is loaded.
+    validate :parent_reference_exists, on: :taxonomy_loaded
+    validate :hierarchy_is_shallow_and_acyclic, on: :taxonomy_loaded
+    validate :jurisdiction_and_display_only_on_leaves, on: :taxonomy_loaded
+    validate :leaf_required_fields_present, on: :taxonomy_loaded
+    validate :display_fields_are_consistent, on: :taxonomy_loaded
+    validate :display_preferences_surfaces_are_valid, on: :taxonomy_loaded
+
+    localized_attr_reader :name, :description, :title, :content, keyed_by: :public_id
+
+    attr_reader :id,
+      :public_id,
+      :parent_public_id,
+      :internal_label,
+      :jurisdictions,
+      :legal_citation,
+      :symbol,
+      :display_requirements,
+      :display_preferences,
+      :source,
+      :disclosure_attributes,
+      :disclosure_attribute_values
+
+    def initialize(
+      id:,
+      public_id:,
+      name:,
+      internal_label:,
+      parent_public_id: nil,
+      description: nil,
+      jurisdictions: nil,
+      legal_citation: nil,
+      symbol: nil,
+      display_requirements: nil,
+      display_preferences: nil,
+      title: nil,
+      content: nil,
+      source: nil,
+      disclosure_attributes: nil,
+      disclosure_attribute_values: nil
+    )
+      @id = id
+      @public_id = public_id
+      @parent_public_id = parent_public_id
+      @name = name
+      @internal_label = internal_label
+      @description = description
+      @jurisdictions = jurisdictions
+      @legal_citation = legal_citation
+      @symbol = symbol
+      @display_requirements = display_requirements
+      @display_preferences = display_preferences
+      @title = title
+      @content = content
+      @source = source
+      @disclosure_attributes = disclosure_attributes
+      @disclosure_attribute_values = disclosure_attribute_values
+    end
+
+    # The global ID of the disclosure.
+    #
+    # @return [String]
+    def gid
+      "gid://shopify/TaxonomyDisclosure/#{id}"
+    end
+
+    # Whether this is a grouping/root node (has no parent).
+    #
+    # @return [Boolean]
+    def root?
+      parent_public_id.nil?
+    end
+
+    # The parent disclosure, or nil for root nodes.
+    #
+    # @return [Disclosure, nil]
+    def parent
+      parent_public_id && Disclosure.find_by(public_id: parent_public_id)
+    end
+
+    # The direct children of this disclosure.
+    #
+    # @return [Array<Disclosure>]
+    def children
+      Disclosure.all.select { |disclosure| disclosure.parent_public_id == public_id }
+    end
+
+    # Whether this is a leaf node (no other disclosure points at it). Leaf nodes
+    # are the ones that carry jurisdiction and display information.
+    #
+    # @return [Boolean]
+    def leaf?
+      children.empty?
+    end
+
+    private
+
+    def field_types_are_valid
+      errors.add(:jurisdictions, :invalid, message: "must be an array") if jurisdictions && !jurisdictions.is_a?(Array)
+      errors.add(:display_preferences, :invalid, message: "must be a hash") if display_preferences && !display_preferences.is_a?(Hash)
+      unless disclosure_attributes.nil? || disclosure_attributes.is_a?(Array)
+        errors.add(:disclosure_attributes, :invalid, message: "must be an array")
+      end
+      unless disclosure_attribute_values.nil? || disclosure_attribute_values.is_a?(Array)
+        errors.add(:disclosure_attribute_values, :invalid, message: "must be an array")
+      end
+      STRING_FIELDS.each do |field|
+        value = send(field)
+        errors.add(field, :invalid, message: "must be a string") if value && !value.is_a?(String)
+      end
+    end
+
+    def not_self_parenting
+      return if parent_public_id.nil?
+
+      errors.add(:parent_public_id, :invalid, message: "cannot be its own parent") if parent_public_id == public_id
+    end
+
+    def parent_reference_exists
+      return if parent_public_id.nil?
+      return if Disclosure.find_by(public_id: parent_public_id)
+
+      errors.add(:parent_public_id, :not_found, message: "must reference an existing disclosure")
+    end
+
+    # Enforces a two-level axis (grouping/root → leaf) and guards against cycles.
+    def hierarchy_is_shallow_and_acyclic
+      return if parent_public_id.nil?
+
+      seen = [public_id]
+      current = Disclosure.find_by(public_id: parent_public_id)
+      while current
+        if seen.include?(current.public_id)
+          errors.add(:parent_public_id, :invalid, message: "introduces a cycle in the hierarchy")
+          return
+        end
+        seen << current.public_id
+        current = current.parent_public_id && Disclosure.find_by(public_id: current.parent_public_id)
+      end
+
+      parent = Disclosure.find_by(public_id: parent_public_id)
+      unless parent.nil? || parent.root?
+        errors.add(:parent_public_id, :invalid, message: "must reference a top-level grouping (max depth is two levels)")
+      end
+    end
+
+    def jurisdiction_and_display_only_on_leaves
+      if leaf?
+        errors.add(:jurisdictions, :blank, message: "must be present on leaf disclosures") if jurisdictions.blank?
+      else
+        errors.add(:jurisdictions, :present, message: "must not be set on grouping disclosures") if jurisdictions.present?
+        if display_preferences.present?
+          errors.add(:display_preferences, :present, message: "must not be set on grouping disclosures")
+        end
+      end
+    end
+
+    def leaf_required_fields_present
+      return unless leaf?
+
+      LEAF_REQUIRED_FIELDS.each do |field|
+        errors.add(field, :blank, message: "must be present on leaf disclosures") if send(field).blank?
+      end
+    end
+
+    # A leaf that names a display surface must carry the copy that buyers read.
+    def display_fields_are_consistent
+      return unless leaf?
+      return if display_preferences.blank?
+
+      DISPLAY_REQUIRED_FIELDS.each do |field|
+        errors.add(field, :blank, message: "must be present when display_preferences is set") if send(field).blank?
+      end
+    end
+
+    def display_preferences_surfaces_are_valid
+      return if display_preferences.blank?
+
+      surfaces = display_preferences.is_a?(Hash) ? display_preferences["surfaces"] : nil
+      unless surfaces.is_a?(Array) && surfaces.any?
+        errors.add(:display_preferences, :invalid, message: "must define a non-empty surfaces array")
+        return
+      end
+
+      invalid = surfaces - SURFACES
+      errors.add(:display_preferences, :invalid, message: "has invalid surfaces: #{invalid.join(", ")}") if invalid.any?
+      errors.add(:display_preferences, :invalid, message: "has duplicate surfaces") if surfaces.uniq.size != surfaces.size
+    end
+  end
+end

data/lib/product_taxonomy/models/mixins/formatted_validation_errors.rb

@@ -5,7 +5,13 @@ module ProductTaxonomy
     def validate!(...)
       super # Calls original ActiveModel::Validations#validate!
     rescue ActiveModel::ValidationError
-      id_field_name = self.is_a?(Category) ? :id : :friendly_id
+      id_field_name = if self.is_a?(Category)
+        :id
+      elsif self.respond_to?(:friendly_id)
+        :friendly_id
+      else
+        :public_id
+      end
       id_value = self.send(id_field_name)
 
       formatted_error_details = self.errors.map do |error|

data/lib/product_taxonomy/models/return_reason.rb

@@ -7,6 +7,17 @@ module ProductTaxonomy
     extend Localized
     extend Indexed
 
+    # Reasons that apply to every category, in the order they are always listed in. They sit at the end of a
+    # category's list, and stand in for categories that define no reasons of their own.
+    GLOBAL_FRIENDLY_IDS = [
+      "changed_my_mind",
+      "item_not_as_described",
+      "received_the_wrong_item",
+      "damaged_or_defective",
+      "unknown",
+      "other_reason",
+    ].freeze
+
     class << self
       # Override to match folder name convention (return_reasons vs returnreasons)
       def localizations_humanized_model_name
@@ -33,6 +44,15 @@ module ProductTaxonomy
       def reset
         @localizations = nil
         @hashed_models = nil
+        @global = nil
+      end
+
+      # The global return reasons, in their defined order. Reasons that are not loaded are skipped, so callers get
+      # whatever subset the current source data defines. Frozen because the memoized array is shared by all callers.
+      #
+      # @return [Array<ReturnReason>]
+      def global
+        @global ||= GLOBAL_FRIENDLY_IDS.filter_map { |friendly_id| find_by(friendly_id:) }.freeze
       end
 
       # Get the next ID for a newly created return reason.